video-download

Video Download Skill

Wraps yt-dlp with automatic recovery for YouTube anti-bot challenges.

Tool

scripts/download.py — installs yt-dlp on first run, merges video+audio to MP4, auto-rotates strategies on bot detection, uses a download-archive for safe resume.

Workflow

1. Collect all URLs from the user's request.
2. Determine output directory (current working directory if unspecified).
3. Decide single-video vs playlist mode:
   • User says "this video" / single URL → leave default (single-video).
   • User says "playlist" / "all videos" / passes a playlist?list= URL → add --playlist.
4. Run the script. If YouTube bot detection hits, the script auto-rotates strategies.
5. Report which files were saved and which strategy worked.

Usage

# Single video, current directory
python scripts/download.py "https://www.youtube.com/watch?v=..."

# Multiple URLs to a folder
python scripts/download.py "URL1" "URL2" -o "/path/to/output"

# Full playlist as 720p MP4
python scripts/download.py "https://www.youtube.com/playlist?list=..." --playlist -o "./out"

# Force a specific browser for cookies (skips auto-rotation)
python scripts/download.py "URL" --cookies-from-browser chrome

# Force a manual cookies.txt file
python scripts/download.py "URL" --cookies "~/Downloads/www.youtube.com_cookies.txt"

# Higher quality
python scripts/download.py "URL" --max-height 1080

Flags

Flag	Default	Notes
-o, --output	cwd	Output directory
--max-height	720	Max video height (e.g. 1080, 480)
--playlist	off	Download full playlist; default is single-video
--cookies-from-browser	auto	Force one browser; skips auto-rotation
--cookies	auto	Force one cookies.txt file; skips auto-rotation
--no-archive	off	Disable .download-archive.txt resume tracking

Auto-Recovery Strategy Chain

When a request fails with bot-detection markers (Sign in to confirm, LOGIN_REQUIRED), the script automatically advances through these strategies in order, stopping at the first one that succeeds:

1. No auth + throttle — Default. Sleep intervals between requests.
2. Player client rotation — default,tv,mweb,web_safari. Bypasses softer blocks.
3. Browser cookies rotation — Tries chrome → edge → firefox → brave → vivaldi → opera, only browsers actually installed on the system.
4. Cookies file discovery — Picks the newest valid cookies file from ~/Downloads/www.youtube.com_cookies.txt, youtube*cookies*.txt, cookies.txt (< 7 days old to be considered fresh).

If all 4 strategies fail, the script prints a context-aware recovery walkthrough (see "Recovery instructions for the user" below).

If the user explicitly passes --cookies-from-browser or --cookies, the chain is skipped and only that source is used (useful when the user already knows what works).

Recovery instructions for the user

When all strategies fail, the script auto-prints a step-by-step guide. Surface the most relevant subset to the user verbatim — it is concrete and actionable.

The guide branches based on what the script saw:

• Cookies file found but rejected (file is stale): tell the user to re-export cookies right now, since YouTube invalidates cookies aggressively once a bot-block triggers.
• No cookies file found: walk the user through the first-time export.
• Otherwise: just list alternatives (close browser, change network, wait).

Cookie export walkthrough (the part the user will likely need)

1. Install a cookie export browser extension:

   • Chrome / Edge / Brave / Vivaldi / Opera: "Get cookies.txt LOCALLY" — https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc
   • Firefox: "cookies.txt" — https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/

2. Open https://www.youtube.com in that browser, signed in to a Google account.

3. Click the extension's toolbar icon:

   • "Get cookies.txt LOCALLY" → "Export As" → Netscape format → use the "Current Site" option so only youtube.com cookies are included.
   • Firefox "cookies.txt" → "Current Site" → Save.

4. Save the file to the OS default Downloads folder. Any of these names work (auto-detected, newest wins):

   • www.youtube.com_cookies.txt (extension default — easiest)
   • youtube.com_cookies.txt
   • cookies.txt

5. Re-run the same download command. Strategy 4 picks the file up automatically.

When to recommend each alternative

• Close the browser (Chrome / Edge): fastest fix on Windows, where App-Bound Encryption locks the cookie database while the browser runs. Costs the user their open tabs unless "Continue where you left off" is enabled.
• Different network (mobile hotspot, VPN): bypasses an IP-level block. Fastest if the user already has a VPN.
• Wait it out: YouTube IP blocks lift on their own, usually within 24 h. Recommend only if no other option fits.

Resume / Re-Run Safety

--download-archive .download-archive.txt is enabled by default. Already-downloaded videos are skipped on re-runs, so it's safe to re-run after partial failure or when adding more URLs to the same folder. Pass --no-archive to disable.

Output Filename Pattern

• Single video: {title} [{id}].mp4
• Playlist: {NNN} - {title} [{id}].mp4 (zero-padded index keeps order in file managers)

--windows-filenames is always on, so files are safe across OSes.

Authentication Notes

• Auto-rotation handles most cases without user input.
• --cookies-from-browser chrome requires Chrome closed on Windows (App-Bound Encryption locks the cookie DB while Chrome is running).
• If Chrome must stay open, recommend the user export cookies via the "Get cookies.txt LOCALLY" Chrome extension and drop the file in ~/Downloads/. The script picks it up automatically on next run.

Supported Platforms

YouTube (single + playlists), Instagram, TikTok, Twitter/X, Facebook, Vimeo, Reddit, and 1000+ more via yt-dlp.