Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failure

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): 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) If not installed or outdated (< 2025.10.22): 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: 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: 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: Step 3: Verify Download Quality Expected output for 1080p: Alternative: Browser Cookies Method If PO token provider setup is problematic, use browser cookies: Benefits : Access to age restricted and members only content. Requirements : Must be logged into YouTube in the specified browser. Browser and yt dlp must use the same IP/proxy. Do not use Android client with cookies (Android client does not support cookies). Common Tasks Audio Only Download (Run this yourself) Extract audio as MP3: Custom Output Directory (Run this yourself) Download with Subtitles (Run this yourself) Playlist Download (Run this yourself) Convert WebM to MP4 (Run this yourself) YouTube high quality downloads often use WebM format (VP9 codec). Convert to MP4 for wider compatibility: Parameters explained: c:v libx264 : Use H.264 video codec (widely compatible) preset medium : Balance between encoding speed and file size crf 23 : Constant Rate Factor for quality (18 28 range, lower = better quality) c:a aac : Use AAC audio codec b:a 128k : Audio bitrate 128 kbps Tip : Conversion maintains 1080p resolution and provides ~6x encoding speed on modern hardware. Troubleshooting Quick Reference Only 360p Available (Format 18) Cause : Missing PO token provider or outdated yt dlp. Solution : 1. Update yt dlp: brew upgrade yt dlp 2. Install PO token provider (see Step 1 above) 3. Or use browser cookies method Sign in to Confirm You’re Not a Bot Cause : YouTube requires authentication to proceed. Solution : 1. Request permission and use browser cookies ( cookies from browser chrome ). 2. Ensure the browser and yt dlp use the same IP/proxy. 3. Retry with web safari client if needed. Only Images Available / Requested Format Not Available Cause : PO tokens not applied or provider/browser verification failed. Solution : 1. Verify PO Token provider is running before download. 2. Keep the browser window open if using WPC. 3. If cookies are in use, prefer web safari client and retry. nsig Extraction Failed Symptoms : Solution : 1. Update yt dlp to latest version 2. Install PO token provider 3. If still failing and PO tokens are disabled, use Android client: yt dlp extractor args "youtube:player client=android" "VIDEO URL" SSL EOF / Fragment Errors Cause : Proxy or network instability. Solution : 1. Retry with progressive formats (non m3u8). 2. Switch to a more stable proxy/node. 3. Avoid closing the PO token browser window during download. Slow Downloads or Network Errors For users in China or behind restrictive proxies: Downloads may be slow due to network conditions Allow sufficient time for completion yt dlp automatically retries on transient failures PO Token Warning (Harmless) Action : Ignore if download succeeds. This indicates Android client has limited format access without PO tokens. Bundled Script Reference scripts/download video.py Use this convenience wrapper to auto start a PO Token provider by default for high quality downloads. Use it yourself and report results to the user without asking them to run commands. Basic usage: Arguments: url YouTube video URL (required) o, output dir Output directory output template Output filename template (yt dlp syntax) f, format Format specification q, quality Quality preset (best, 1080p, 720p, 480p, 360p, worst). Default: best (skipped for audio only ) a, audio only Extract audio as MP3 subtitles Download subtitles if available sub lang Subtitle languages (comma separated, default: en) cookies from browser Load cookies from a browser (e.g., chrome, firefox) cookies file Load cookies from a cookies.txt file player client Use a specific YouTube player client (e.g., web safari) auto po token Auto start PO Token provider (default; uses Docker if available, otherwise switches to browser based provider) no auto po token Disable auto PO Token setup proxy Proxy URL for yt dlp and the PO Token provider (e.g., http://127.0.0.1:1082) wpc browser path Browser executable path for WPC provider F, list formats List available formats merge format Merge output container (e.g., mp4, mkv). Default: mp4 playlist Allow playlist downloads (default: single video only) info Print title/uploader/duration/thumbnail and exit no android client Disable Android client fallback Note : Use the Android client only when PO tokens are disabled. Keep PO tokens enabled for high quality. Quality Expectations Setup 360p 720p 1080p 1440p 4K Auto PO token (default) ✓ ✓ ✓ ✓ ✓ Android client only ✓ ✗ ✗ ✗ ✗ PO token provider (manual) ✓ ✓ ✓ ✓ ✓ Browser cookies ✓ ✓ ✓ ✓ ✓ HLS Stream Downloads (m3u8) For streaming platforms like Mux, Vimeo, and other HLS based services, use ffmpeg as the primary tool. These streams often require authentication headers that y

youtube-downloader