Skip to content

README.en.md

Latest commit

 

History

History
250 lines (161 loc) · 10.9 KB

README.en.md

File metadata and controls

250 lines (161 loc) · 10.9 KB
Raw

yt-dlp-win-script

Chinese

A Windows interactive yt-dlp downloader script. Double-click to start, auto-check yt-dlp updates, paste a video or live URL, compare top video formats by codec/resolution/FPS/HDR/SDR/bitrate, and choose what to download.

Files

  • Start-Interactive-YTDLP.bat: double-click entry point.
  • interactive-yt-dlp.ps1: main interactive script.
  • yt-dlp.exe: recommended in this folder or in PATH; if missing from both places, the script downloads it automatically.
  • chrome-extension\ / edge-extension\: browser extension source folders for Chrome and Edge.
  • Register-Chrome-Bridge.bat / Register-Edge-Bridge.bat: double-click native host registration helpers.
  • ffmpeg.exe / ffprobe.exe: used for merging, remuxing, subtitle conversion, and embedding; if missing, the script downloads them automatically.
  • Output\: default output folder. You can choose another folder at startup.

Requirements

  • Windows
  • Built-in Windows PowerShell or PowerShell 7 pwsh.exe

Usage

  1. Optional: put yt-dlp.exe in this folder or add it to PATH; otherwise the script downloads it on startup.
  2. Optional: put ffmpeg.exe and ffprobe.exe in this folder or add them to PATH; otherwise the script downloads them on startup.
  3. Double-click Start-Interactive-YTDLP.bat.
  4. The script runs yt-dlp -U first to check for updates.
  5. Choose the output directory.
  6. Choose whether to use Chrome cookies. Default is Y.
  7. Paste a video or live URL.
  8. Choose video, audio, subtitles, and output container from the listed options.

Downloads are saved to the startup-selected output directory. The default is Output\.

Output Directory

At startup, the script asks for an output directory:

  • Press Enter or type 1: use the default Output\
  • Type 2: enter a custom path
  • Or paste a path directly

Relative paths are resolved from the script folder. Missing folders are created automatically.

Browser Extension Launch

The project includes Chrome and Edge extensions. They can launch the local downloader directly from the current page and export relevant site cookies as a Netscape cookie file for yt-dlp. This avoids copying the browser cookie database directly and can still include HttpOnly cookies.

Chrome Setup

  1. Double-click Register-Chrome-Bridge.bat.
  2. The script copies the chrome-extension folder path to the clipboard.
  3. Open chrome://extensions manually.
  4. Enable Developer mode in Chrome.
  5. Click Load unpacked and select the chrome-extension folder.
  6. Copy the extension ID from the extension card, paste it into the script window, and press Enter.

Manual command:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Install-Chrome-Bridge.ps1

Edge Setup

  1. Double-click Register-Edge-Bridge.bat.
  2. The script copies the edge-extension folder path to the clipboard.
  3. Open edge://extensions manually.
  4. Enable Developer mode in Edge.
  5. Click Load unpacked and select the edge-extension folder.
  6. Copy the extension ID from the extension card, paste it into the script window, and press Enter.

Manual command:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Install-Edge-Bridge.ps1

Extension Usage

  • Click the yt-dlp-win-script extension button in Chrome or Edge.
  • Or right-click a page, link, or video and choose Send to yt-dlp.

The extension sends the current URL and cookies to the local Native Host. The Native Host will:

  • Save cookies to chrome-helper\cookies\chrome-cookies-*.txt
  • Open a new PowerShell window
  • Pass the page URL to interactive-yt-dlp.ps1
  • Use the exported cookie file automatically

If the extension cannot connect to the Native Host, the extension ID is usually not registered, or it changed after reloading the unpacked extension. Copy the current extension ID again and rerun the matching registration script.

If you move the whole tool folder, register the Native Host again from the new location. For example, after moving to D:\Tools\yt-dlp:

Double-click D:\Tools\yt-dlp\Register-Chrome-Bridge.bat
Double-click D:\Tools\yt-dlp\Register-Edge-Bridge.bat

Move the folder as a whole and keep yt-dlp.exe, interactive-yt-dlp.ps1, chrome-helper, chrome-extension, and edge-extension under the same main folder.

Note: Browsers restrict local unpacked extension installation. A normal script usually cannot silently install an unpacked extension and read its extension ID. These registration helpers copy the extension folder path; you still load the extension manually and paste the ID once.

Video Selection

The script reads yt-dlp JSON metadata and finds the highest resolution available for each video codec. The list shows only comparable top resolution tiers formed from those codec maxima. If one codec tops out at 1080p while another reaches 2160p, 2160p is shown, and 1080p is also shown for the other codecs. At the same codec and resolution, different FPS and HDR/SDR variants are listed separately. Exact duplicate tiers keep the highest-bitrate format.

Example:

  1. av1        2160p   60fps HDR   12000.0 kbps id=701 ext=mp4  video-only
  2. av1        1080p   60fps SDR    3200.0 kbps id=399 ext=mp4  video-only
  3. av1        1080p   30fps HDR    3600.0 kbps id=699 ext=mp4  video-only
  4. avc/h264   1080p   30fps SDR    2800.0 kbps id=137 ext=mp4  video-only
  5. vp9        1080p   60fps SDR    3000.0 kbps id=248 ext=webm video-only

Bitrate uses yt-dlp vbr / tbr when available. If not, it is estimated from file size and duration when possible.

Audio Selection

Audio formats are grouped by codec plus language, then the highest-bitrate format in each group is listed.

You can choose:

  • A separate audio stream, such as opus or aac
  • 0 for no extra audio when the selected video format already contains audio

Subtitles

Subtitle selection supports multiple choices:

  • Type 1,3-5 to select multiple subtitle rows
  • Type all to select all subtitles
  • Press Enter to skip subtitles

The script does two things:

  1. Saves a copy in the source subtitle format.
  2. Converts subtitles to srt when possible and embeds them in the main download.

Note: MP4 has limited support for embedded SRT. ffmpeg/container behavior may convert subtitles to an MP4-compatible text track. Choose mkv if you want more reliable subtitle preservation.

Container Format

Choose the output container:

  • 1: mkv
  • 2: mp4

Press Enter to default to mkv. Text input mkv or mp4 is still accepted.

Recommendation:

  • Choose mkv for multiple subtitles or better track preservation.
  • Choose mp4 for broader player compatibility.

Chrome Cookies

The interactive script supports --cookies-from-browser chrome for videos that need a logged-in browser session.

If you see:

ERROR: Could not copy Chrome cookie database

The script asks you to close Chrome and retry. If it still fails, it continues without Chrome cookies for metadata reading.

Common fixes:

  • Fully exit Chrome, including background processes.
  • Close browser windows using the same Chrome profile.
  • If the video does not require login, choose not to use cookies.

System Proxy

The script reads Windows manual proxy settings and passes them to yt-dlp as --proxy.

If no Windows manual proxy is enabled, yt-dlp uses its default network behavior.

Live Streams

If yt-dlp metadata clearly reports live_status as is_live or is_upcoming, the script asks whether to use:

--live-from-start

Choosing Y lets yt-dlp try to download from the start of the live stream. Whether this works depends on the site providing DVR/live rewind data.

For upcoming YouTube live streams, metadata reading may fail with a message like:

This live event will begin in 17 hours.

The script detects this and asks whether to enter wait mode. Before waiting, it asks for the container, --live-from-start, and live anti-interruption mode, so the download can start unattended. 17 hours is treated as a rough estimate, not an exact start time. After choosing Y, the script shows a countdown and periodically re-reads metadata to recalibrate:

  • More than 6 hours away: check every 1 hour
  • 1 to 6 hours away: check every 15 minutes
  • 15 to 60 minutes away: check every 5 minutes
  • Within 15 minutes: hand off to yt-dlp wait mode

The yt-dlp wait mode uses:

--wait-for-video 5-15

If the actual start time is earlier or later than the rough estimate, yt-dlp keeps waiting at 5-15 second intervals and starts as soon as possible. Since an upcoming live stream often has no format list yet, wait mode automatically chooses the highest-video-bitrate video stream and highest-audio-bitrate audio stream:

-f bestvideo+bestaudio/best --format-sort-force --format-sort vbr,abr,tbr

vbr prioritizes video bitrate, abr prioritizes audio bitrate, and tbr is a fallback when bitrate fields are incomplete.

When a live stream is detected, the script also asks whether to enable anti-interruption mode. Default is enabled. It adds:

  • --retries infinite
  • --fragment-retries 6, to avoid endless retries on post-end 404 fragments
  • --file-access-retries infinite
  • --extractor-retries infinite
  • Exponential --retry-sleep
  • --continue
  • --downloader dash,m3u8:native, forcing yt-dlp native HLS/DASH handling to avoid ffmpeg polling playlists forever after the live stream ends
  • --keep-fragments

If yt-dlp exits during a live download, the script re-reads metadata to check whether the stream has ended. If it is still live, the same download command restarts immediately, up to 30 attempts. If the stream has ended, the script stops restarting and lets downloaded content move into finalization/remuxing.

Important limitation: these measures help with short network drops, fragment timeouts, temporary metadata failures, and yt-dlp exits, and they avoid chasing missing post-end fragments forever. They cannot recover segments that were already outside the DVR window, removed by the platform, or never downloaded locally. For important live streams, do not delete .part, .ytdl, .frag, .ts, or similar temporary files; they may help with manual recovery if final muxing fails.

FAQ

Why are some formats not listed?

The script does not show the full yt-dlp -F list. It shows comparable top resolution tiers for each codec and keeps different FPS/HDR/SDR variants at the same resolution. Lower ordinary resolutions are hidden.

Why does bitrate show unknown?

Some sites do not provide bitrate, file size, or duration information. If the script cannot estimate it, it shows unknown.

Why do embedded subtitles behave differently in MP4?

MP4 containers have stricter subtitle limitations. Prefer MKV when you need multiple subtitle languages or better subtitle track preservation.

Why does the script continue if update check fails?

At startup, the script tries yt-dlp -U. If network or permission issues make the update check fail, it prints a warning and continues to the download flow.