youtube-downloader

What this skill does

# YouTube Downloader

## Overview

Enable reliable video and audio downloads from YouTube and HLS streaming platforms (Mux, Vimeo, etc.) using yt-dlp and ffmpeg. This skill provides workflows for:
- YouTube downloads (up to 4K) using PO token providers or browser cookies
- HLS stream downloads with authentication headers
- Handling protected content and troubleshooting common download failures

## Non-Technical User Experience (Default)

Assume the user is non-technical. Do not ask them to run commands. Execute everything yourself and report progress in plain language. Avoid mentioning tooling unless the user asks.

**Default flow:**
1. Ask for the URL (if not provided).
2. Fetch video metadata (title/uploader/duration/thumbnail) and confirm it matches the user's intent.
   - If yt-dlp is blocked by “confirm you’re not a bot”, fall back to YouTube oEmbed for title/uploader/thumbnail (duration may be unknown).
3. Offer simple choices (video vs. audio-only, quality, subtitles, save location).
4. Proceed with sensible defaults if the user does not specify:
   - Video download at best quality
   - MP4 merged output
   - Single video only (no playlists)
5. Download and report the final file path, file size, and resolution (if video).

**Offer choices in user-friendly terms:**
- “Download the video in best quality (default)”
- “Download audio only (MP3)”
- “Pick a quality: 1080p / 720p / 480p / 360p”
- “Include subtitles (if available)”
- “Save to the Downloads folder (default) or tell me another folder”

**Always render the thumbnail when available:**
- If metadata includes a thumbnail URL, include it using Markdown image syntax: `![Thumbnail](URL)`.

**Ask before doing extra work:**
- Confirm playlist downloads (can be large).
- Confirm installing/upgrading dependencies if missing.
- Ask before extracting browser cookies.
- If using cookies, never mention cookie counts or raw cookie details in user-facing responses. Say “used your Chrome login session”.
- If verification is required, automatically set up a local PO Token helper (no user actions). If Docker is missing or fails, do **not** attempt to install Docker—switch to the browser-based PO Token provider instead.

**Legal/Safety reminder (brief):**
- Proceed only if the user has the rights or permission to download the content.

**Response template (use plain language, no commands):**
```
![Thumbnail](THUMBNAIL_URL)

Title: …
Channel: …
Duration: …

I can help you:
1) Download the video (best quality, MP4)
2) Download audio only (MP3)
3) Pick a specific quality (1080p/720p/480p/360p)
4) Include subtitles (if available)

Where should I save it? (Default: Downloads folder)
```

**If the user says “just download”:**
- Proceed with defaults and confirm when the download finishes.
  - If blocked by a 403, automatically set up the verification helper and retry.

## Reliable Download SOP (Internal)

Follow this SOP to avoid common failures and confusion:

1. Quote URLs in shell commands (zsh treats `?` as a glob). Example: `'https://www.youtube.com/watch?v=VIDEO_ID'`.
2. Ensure proxy is active for both yt-dlp and PO Token providers (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
3. If you see “Sign in to confirm you’re not a bot”, request permission and use browser cookies. Do not proceed without cookies.
4. Start a PO Token provider before downloading (fail fast if it cannot start).
   - Use Docker bgutil provider when available.
   - If Docker is missing or fails, switch to browser-based WPC provider.
5. If cookies are in use, prefer the `web_safari` player client. Otherwise prefer `mweb` for PO tokens.
6. Keep the browser window open while WPC is minting tokens. Ensure Chrome can reach YouTube through the same proxy.
7. If you get “Only images are available” or “Requested format is not available”, treat it as a PO Token failure and retry after fixing token provider/browser state.
8. If you get SSL EOF or fragment errors, treat it as a proxy/network issue. Retry with progressive formats and/or a better proxy.

## Agent Execution Checklist (Internal)

- Run `scripts/download_video.py URL --info` (add `--cookies-from-browser chrome` if permission granted) to fetch metadata and thumbnail.
- If yt-dlp metadata fails, rely on the script’s oEmbed fallback for title/uploader/thumbnail and note that duration may be unavailable.
- If a thumbnail URL is present, render it in the response with Markdown image syntax.
- Ask the user to choose video vs. audio-only and (optionally) a quality preset.
- Use a friendly default save location (Downloads folder) unless the user specifies a folder.
- For subtitles, run with `--subtitles` and the requested `--sub-lang`.
- After download, report file name, size, and resolution (if video) in plain language.
- If download fails with 403/fragment errors, retry once with non-m3u8 progressive formats.
- If “Sign in to confirm you’re not a bot” appears, request cookie access and retry with cookies + `web_safari`.
- If “Only images are available” appears, treat it as PO Token failure and retry after fixing provider/browser state.
- Start the PO Token provider before downloads (`--auto-po-token` default). Fail fast if it cannot start.
- If Docker-based provider fails (common in China), automatically fall back to the browser-based WPC provider (it may briefly open a browser window).
- If the WPC provider is used, keep the browser window open until download starts. If the browser fails to launch, set the Chrome path explicitly.
- If the PO Token provider times out, restart it once and retry.
- If a system proxy is configured, pass it into the provider container. If the proxy points to 127.0.0.1/localhost, rewrite it to `host.docker.internal` for Docker.

## When to Use This Skill

This skill should be invoked when users:
- Request downloading YouTube videos or playlists
- Want to extract audio from YouTube videos
- Experience yt-dlp download failures or limited format availability
- Need help with format selection or quality options
- Report only low-quality (360p) formats available
- Ask about downloading YouTube content in specific quality (1080p, 4K, etc.)
- Need to convert downloaded WebM videos to MP4 format for wider compatibility
- Request downloading HLS streams (m3u8) from platforms like Mux, Vimeo, or other streaming services
- Need to download protected streams that require authentication headers

## Prerequisites

### 1. Verify yt-dlp Installation (Run this yourself)

```bash
which yt-dlp
yt-dlp --version
```

If not installed or outdated (< 2025.10.22):

```bash
brew upgrade yt-dlp  # macOS
# or
pip install --upgrade yt-dlp  # Cross-platform
```

**Critical**: Outdated yt-dlp versions cause nsig extraction failures and missing formats.

### 2. Check Current Quality Access (Run this yourself)

Before downloading, check available formats:

```bash
yt-dlp -F "https://youtu.be/VIDEO_ID"
```

**If only format 18 (360p) appears**: PO token provider setup needed for high-quality access.

## High-Quality Download Workflow

### Step 1: Install PO Token Provider (One-time Setup)

For 1080p/1440p/4K access, install a PO token provider plugin into yt-dlp's Python environment:

```bash
# Find yt-dlp's Python path (interpreter used by yt-dlp)
head -1 $(which yt-dlp)

# Install plugin using the interpreter from the line above
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider
```

**Verification**: Run `yt-dlp -F "VIDEO_URL"` again. Look for formats 137 (1080p), 271 (1440p), or 313 (4K).

See `references/po-token-setup.md` for detailed setup instructions and troubleshooting.

### Step 2: Download with Best Quality

Once PO token provider is installed:

```bash
# Download best quality up to 1080p
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"

# Download best available quality (4K if available)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"
```

### Step 3: Verify Download Quality

```bash
# Check video resolution
ffprobe -v error -select_streams v:0 -show_entries stream=width,