YouTube Batch Downloader

An asynchronous, multi-threaded Windows desktop utility designed for downloading YouTube videos in batches safely and efficiently.

Downloading videos or audio shouldn't freeze your desktop or output unplayable files. YouTube Batch Downloader is a lightweight, zero-registry GUI tool built with Python, PySide6, and yt-dlp. It launches through an instant loading screen (heavy libraries load behind it), and runs all active downloads asynchronously in the background so the user interface remains completely responsive.

To guarantee maximum playback compatibility across default video players and standard video editors, the downloader automatically prioritizes standard H.264 (AVC) video and AAC audio formats instead of less-supported formats like AV1 or Opus.

---

Quick Start & Installation

You can run the application instantly as a standalone program or set it up from the source code.

Option A: Download the Standalone Executable

You do not need to install Python, FFmpeg, or manage command-line dependencies.

1. Go to the Release section on this repository page.
2. Download the latest YouTubeBatchDownloader.exe.
3. Move the file to any directory or USB drive and run it. (This single .exe is entirely self-contained and pre-packaged with a lightweight FFmpeg binary).

Option B: Run from Source

If you prefer to run the application using your own local Python runtime:

Step 1: Install Python

Ensure you have Python 3.11 or newer installed.

1. Download it from the Official Python Downloads Page.
2. Run the installer and check the box to "Add python.exe to PATH" before finishing.

Step 2: Install Dependencies

1. Extract the project folder to your desired directory.
2. Double-click install.bat. This automatically creates a localized virtual environment (venv), installs all required libraries, and creates the folder structure.
3. Note: If FFmpeg is missing from your system, the script will automatically fetch a lightweight, safe binary (v4.4.1, ~37MB) from ffbinaries and place it in your tools/ folder.

Step 3: Run the Program

• Double-click run.bat to launch the graphical interface.

---

Building a Standalone Executable

If you modify the source code and want to compile your own self-contained executable:

1. Double-click build.bat.
2. The compiler script uses PyInstaller to bundle your code, standard libraries, and the tools/ffmpeg.exe binary into a single file.
3. Once completed, your custom YouTubeBatchDownloader.exe will be ready inside the newly created dist/ folder.

---

How to Use

The application interface is designed to make batch queue management straightforward:

1. Paste Target Links: Enter your YouTube URLs (one link per line) in the primary text area. You can also drag & drop links anywhere onto the window, and any YouTube link already on your clipboard is loaded automatically at startup.
2. Configure Download Options: Click the compact ⚙ options chip (e.g. MP4 · Best) to open the Download Options dialog — pick your Format (Best Quality, MP4 Video, MP3 Audio…), cap the Quality, set an Audio Boost, and toggle behavior preferences. Your choices stay visible on the main window at a glance.
3. Set Download Location: The application automatically creates and defaults to a local downloads/ directory. You can use the Browse button to select any other folder or drive.
4. Download: Click Add to Queue and Download or simply press Ctrl+Enter. You can safely monitor download progress, speeds, and estimated times of arrival in real-time from the status table.

Handy extras: right-click any row in the queue for Open File / Open Folder / Copy URL / Retry / Cancel / Remove, duplicate links are skipped automatically, and overall batch progress is mirrored on the Windows taskbar with a tray notification when everything finishes.

---

Understanding Key Features

• Responsive Multithreading: Download queues are offloaded to dedicated background worker threads. The GUI never hangs, stutters, or goes into an "Unresponsive" state, even during massive high-speed downloads.
• Universal Codec Priority: Instead of downloading raw .webm (VP9/AV1) streams that cause playback errors in legacy editors, the engine automatically remuxes downloads into globally accepted MP4 (H.264 + AAC) files.
• Smart URL Safeguards: To prevent accidental infinite loops, the program intelligently detects dynamic YouTube Mixes or watch-and-playlist combo links and strips them down to single-video downloads.
• Zero-Registry Portable Design: The application does not write data to your Windows registry or system folders. It is entirely self-contained and runs safely on restricted user profiles without requiring administrator privileges.
• Full-Bandwidth Engine: Up to eight videos download simultaneously and audio tracks run in their own wide pool, so fast connections stay saturated instead of idling. Power users on gigabit lines can opt into the bundled aria2c multi-connection engine by adding "use_aria2": true to settings.json.
• Frictionless Input: Drag & drop links onto the window, press Ctrl+Enter to start, and let duplicate-link detection keep your queue clean automatically. Clipboard monitoring is debounced and batched — copying several links in a row results in one tidy add instead of popup spam.
• Dark & Light Themes: The interface ships in a sleek dark theme by default, switchable to light anytime from Download Options → Theme — applied live and remembered across sessions.
• Blazing MP3 Conversion: Audio extraction uses benchmark-tuned LAME settings, and audio tasks get a dedicated pool that converts whole batches in parallel across every CPU core — a 20-song queue finishes its conversions several times faster than serial encoding.

---

Troubleshooting

• How to view detailed error logs: If a download fails, check the detailed output and exception reports located in logs/app.log.
• Download says "Failed: FFmpeg required...": YouTube hosts audio and video streams separately. If you are running from source and chose MP3, the program needs ffmpeg.exe to convert the stream safely. Run install.bat to automatically acquire the missing binary in your tools/ folder.
• Blocked Requests (HTTP 403 / Forbidden Error): If YouTube blocks your automated download requests, your local downloader library may be outdated. Open your command prompt inside the project folder, activate your virtual environment, and run:

  pip install --upgrade yt-dlp

• Want even faster downloads? By default the app balances speed and stability. If your internet line is very fast (gigabit+), open settings.json and set "use_aria2": true to enable the bundled aria2c engine, which splits each file into 16 parallel connections. Note: per-row progress bars update less frequently while this mode is active, and progress returns to normal once each file finishes its download phase.

---

License (Click to expand)

This project is open-source and distributed under the MIT License.