Youtube Downloader

YouTube Downloader

Downloads YouTube videos interactively — lists available resolutions, checks for subtitles, and lets the user choose exactly what to download.

Prerequisites (auto-install)

Before doing anything else, silently check if both tools are available:

yt-dlp --version 2>/dev/null; echo "yt-dlp:$?"
ffmpeg -version 2>/dev/null | head -1; echo "ffmpeg:$?"

If anything is missing, install it automatically — no need to ask the user. Both tools are pip-installable and require no sudo or system package manager:

pip install -U yt-dlp    # pure Python, works everywhere
pip install ffmpeg-static # pre-built ffmpeg binary, no sudo needed

If pip is not found, try pip3. If ffmpeg-static fails, try imageio[ffmpeg] as a fallback which bundles its own ffmpeg binary. As a last resort on macOS try brew install ffmpeg, on Linux try apt-get install -y ffmpeg (may need sudo — only then ask the user).

Also check for a JavaScript runtime — yt-dlp uses it for some format detection:

node --version 2>/dev/null || deno --version 2>/dev/null

If missing, install one silently: apt-get install -y nodejs 2>/dev/null || brew install node 2>/dev/null. This is optional — yt-dlp works without it but may warn or miss some formats.

After installation, verify all tools work before proceeding. Tell the user what was installed.

Workflow

Follow these steps in order when the user provides a YouTube URL.

Step 1: List available formats

Run yt-dlp -F "URL" to get the format table. Parse the output and present a summary to the user — do not dump the raw table. Group the results into:

• Video+Audio (single files): list resolution, codec, and approximate size
• Video-only: list resolution, codec, and approximate size
• Audio-only: list quality, codec, and approximate size

Use AskUserQuestion to let the user pick. Offer sensible defaults:

Step 2: Check for subtitles

Run:

yt-dlp --list-subs "URL" 2>&1

Parse the output and tell the user:

• Which manual (creator-uploaded) subtitle languages are available
• Which auto-generated caption languages are available
• Whether no subtitles are available at all

Use AskUserQuestion to let the user choose:

If the user's preferred language is only available as auto-generated, inform them and ask if that's acceptable.

Step 3: Confirm and download

Before downloading, show the user a summary of their selections:

• Video format and resolution
• Subtitle choice (if any)
• The full yt-dlp command that will be run

Use AskUserQuestion to confirm: "Start download?" with options "Yes (Recommended)" and "Change settings".

Construct the yt-dlp command based on user choices. Use these format selectors:

For subtitles, append these flags:

Always add --convert-subs srt when downloading subtitles — YouTube serves VTT/srv3 natively, and SRT is more universally compatible.

Run the command and show the user the download progress.

Step 4: Confirm results

After download completes, list the downloaded files with their sizes:

ls -lh FILENAME*

Tell the user:

• The video file path and size
• Any subtitle files downloaded
• The actual resolution and codec of the downloaded video

Format Selector Reference

Authentication via Browser (for restricted videos)

Some videos require authentication: age-restricted, private, or members-only content. When yt-dlp reports an error like "Sign in to confirm your age", "Private video", or "Join this channel to get access", use this workflow:

On desktop (Claude Code, Cursor)

Add --cookies-from-browser chrome (or firefox, edge, safari) to the yt-dlp command. This reads cookies from the user's local browser profile. The user must be logged into YouTube in that browser.

In sandboxed environments (Cowork, cloud)

There's no local browser profile, so use Playwright to get cookies:

1. Launch a browser and navigate to YouTube:

   Use browser_navigate to go to https://accounts.google.com
   

2. Tell the user to log in. Wait for them to complete the Google login flow — use browser_snapshot to check if they've reached the YouTube homepage or their Google account page.

3. Once logged in, extract cookies:

   Use browser_evaluate to run: JSON.stringify(await (async () => {
     const cookies = document.cookie.split('; ').map(c => {
       const [name, ...rest] = c.split('=');
       return { name, value: rest.join('='), domain: '.youtube.com' };
     });
     return cookies;
   })())
   

   Better approach — if the Playwright MCP exposes a cookies API, use that directly to get all cookies for .youtube.com and .google.com domains.

4. Write cookies to a Netscape cookie file:

   # Netscape cookie file format (one line per cookie):
   # domain\tinclude_subdomains\tpath\tsecure\texpiry\tname\tvalue
   .youtube.com    TRUE    /    TRUE    0    COOKIE_NAME    COOKIE_VALUE
   

   Save to a temporary file, e.g., /tmp/yt-cookies.txt.

5. Retry the yt-dlp command with --cookies /tmp/yt-cookies.txt.

6. Clean up the cookie file after download completes.

What authentication CANNOT fix

DRM-protected content (rented/purchased movies, YouTube Premium originals) cannot be downloaded even with authentication. The video stream is encrypted. If yt-dlp reports a DRM error, inform the user that this content is not downloadable.

Error Handling

When yt-dlp fails, parse its stderr and respond with actionable advice:

Do not show raw yt-dlp error output to the user. Translate it into a clear message with a next step.

Troubleshooting

Slow download: YouTube may throttle. Add --concurrent-fragments 4 for parallel fragment downloads.

Geo-restricted video: Requires a VPN or proxy. Use --proxy URL if the user provides one.