youtube-downloader by daymade/claude-code-skills
npx skills add https://github.com/daymade/claude-code-skills --skill youtube-downloader使用 yt-dlp 和 ffmpeg,实现从 YouTube 和 HLS 流媒体平台(Mux、Vimeo 等)可靠地下载视频和音频。此技能提供以下工作流:
假设用户是非技术人员。不要要求他们运行命令。自行执行所有操作,并用通俗语言报告进度。除非用户询问,否则避免提及工具。
默认流程:
以用户友好的术语提供选择:
始终在可用时渲染缩略图:
。在进行额外工作前询问:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
法律/安全提醒(简短):
响应模板(使用通俗语言,无命令):

标题:…
频道:…
时长:…
我可以帮助您:
1) 下载视频(最佳质量,MP4)
2) 仅下载音频(MP3)
3) 选择特定质量(1080p/720p/480p/360p)
4) 包含字幕(如果可用)
我应该将它保存在哪里?(默认:下载文件夹)
如果用户说“直接下载”:
遵循此 SOP 以避免常见失败和混淆:
? 视为通配符)。示例:'https://www.youtube.com/watch?v=VIDEO_ID'。web_safari 播放器客户端。否则,对于 PO 令牌,优先使用 mweb。scripts/download_video.py URL --info(如果已授予权限,则添加 --cookies-from-browser chrome)以获取元数据和缩略图。--subtitles 和请求的 --sub-lang 运行。web_safari 重试。--auto-po-token 默认)。如果无法启动则快速失败。host.docker.internal 以供 Docker 使用。当用户出现以下情况时,应调用此技能:
which yt-dlp
yt-dlp --version
如果未安装或版本过旧(< 2025.10.22):
brew upgrade yt-dlp # macOS
# 或
pip install --upgrade yt-dlp # 跨平台
关键:过时的 yt-dlp 版本会导致 nsig 提取失败和格式缺失。
在下载前,检查可用格式:
yt-dlp -F "https://youtu.be/VIDEO_ID"
如果仅出现格式 18(360p):需要设置 PO 令牌提供程序以访问高质量。
要访问 1080p/1440p/4K,请将 PO 令牌提供程序插件安装到 yt-dlp 的 Python 环境中:
# 查找 yt-dlp 的 Python 路径(yt-dlp 使用的解释器)
head -1 $(which yt-dlp)
# 使用上一行的解释器安装插件
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider
验证:再次运行 yt-dlp -F "VIDEO_URL"。查找格式 137(1080p)、271(1440p)或 313(4K)。
有关详细设置说明和故障排除,请参阅 references/po-token-setup.md。
一旦安装了 PO 令牌提供程序:
# 下载最高 1080p 的最佳质量
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# 下载最佳可用质量(如果可用则为 4K)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"
# 检查视频分辨率
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name -of default=noprint_wrappers=1 video.mp4
1080p 的预期输出:
codec_name=vp9
width=1920
height=1080
如果 PO 令牌提供程序设置有问题,请使用浏览器 Cookie:
# Firefox
yt-dlp --cookies-from-browser firefox -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Chrome
yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
优点:可访问年龄限制和会员专属内容。要求:
提取音频为 MP3:
yt-dlp -x --audio-format mp3 "VIDEO_URL"
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
YouTube 高质量下载通常使用 WebM 格式(VP9 编解码器)。转换为 MP4 以获得更广泛的兼容性:
# 检查是否安装了 ffmpeg
which ffmpeg || brew install ffmpeg # macOS
# 使用良好的质量设置将 WebM 转换为 MP4
ffmpeg -i "video.webm" -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "video.mp4"
参数说明:
-c:v libx264:使用 H.264 视频编解码器(广泛兼容)-preset medium:编码速度和文件大小之间的平衡-crf 23:质量恒定速率因子(范围 18-28,越低 = 质量越好)-c:a aac:使用 AAC 音频编解码器-b:a 128k:音频比特率 128 kbps提示:转换保持 1080p 分辨率,并在现代硬件上提供约 6 倍的编码速度。
原因:缺少 PO 令牌提供程序或 yt-dlp 过时。
解决方案:
brew upgrade yt-dlp原因:YouTube 需要身份验证才能继续。
解决方案:
--cookies-from-browser chrome)。web_safari 客户端重试。原因:未应用 PO 令牌或提供程序/浏览器验证失败。
解决方案:
web_safari 客户端并重试。症状:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
解决方案:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"原因:代理或网络不稳定。
解决方案:
对于在中国或使用限制性代理的用户:
WARNING: android client https formats require a GVS PO Token
操作:如果下载成功则忽略。这表明 Android 客户端在没有 PO 令牌的情况下格式访问受限。
使用此便捷包装器,默认自动启动 PO 令牌提供程序以进行高质量下载。自行使用它,并向用户报告结果,而不要求他们运行命令。
基本用法:
scripts/download_video.py "VIDEO_URL"
参数:
url - YouTube 视频 URL(必需)-o, --output-dir - 输出目录--output-template - 输出文件名模板(yt-dlp 语法)-f, --format - 格式规范-q, --quality - 质量预设(best, 1080p, 720p, 480p, 360p, worst)。默认:best(对于 --audio-only 则跳过)-a, --audio-only - 提取音频为 MP3--subtitles - 如果可用则下载字幕--sub-lang - 字幕语言(逗号分隔,默认:en)--cookies-from-browser - 从浏览器加载 Cookie(例如,chrome, firefox)--cookies-file - 从 cookies.txt 文件加载 Cookie--player-client - 使用特定的 YouTube 播放器客户端(例如,web_safari)--auto-po-token - 自动启动 PO 令牌提供程序(默认;如果可用则使用 Docker,否则切换到基于浏览器的提供程序)--no-auto-po-token - 禁用自动 PO 令牌设置--proxy - yt-dlp 和 PO 令牌提供程序的代理 URL(例如,http://127.0.0.1:1082)--wpc-browser-path - WPC 提供程序的浏览器可执行文件路径-F, --list-formats - 列出可用格式--merge-format - 合并输出容器(例如,mp4, mkv)。默认:mp4--playlist - 允许播放列表下载(默认:仅单个视频)--info - 打印标题/上传者/时长/缩略图并退出--no-android-client - 禁用 Android 客户端回退注意:仅当 PO 令牌被禁用时才使用 Android 客户端。保持 PO 令牌启用以获得高质量。
| 设置 | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| 自动 PO 令牌(默认) | ✓ | ✓ | ✓ | ✓ | ✓ |
| 仅 Android 客户端 | ✓ | ✗ | ✗ | ✗ | ✗ |
| PO 令牌提供程序(手动) | ✓ | ✓ | ✓ | ✓ | ✓ |
| 浏览器 Cookie | ✓ | ✓ | ✓ | ✓ | ✓ |
对于像 Mux、Vimeo 和其他基于 HLS 的服务这样的流媒体平台,使用 ffmpeg 作为主要工具。这些流通常需要 yt-dlp 可能无法正确处理的身份验证标头。
HLS 流使用 .m3u8 播放列表文件:
从视频源获取 m3u8 URL。对于受保护的流:
许多 CDN 需要身份验证标头:
https://maven.com/)检查网络标签页以查看浏览器发送了哪些标头。
使用带有 -headers 标志的 ffmpeg 处理受保护的流:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/path/rendition.m3u8?params" \
-c copy -bsf:a aac_adtstoasc \
output.mp4
关键参数:
-headers:设置 HTTP 标头(对身份验证至关重要)-protocol_whitelist:启用 HLS 所需的协议-c copy:流复制(无需重新编码,更快)-bsf:a aac_adtstoasc:修复 AAC 音频兼容性常见标头模式:
# 单个标头
-headers "Referer: https://example.com/"
# 多个标头
-headers "Referer: https://example.com/" \
-headers "User-Agent: Mozilla/5.0..."
# 替代语法
-headers $'Referer: https://example.com/\r\nUser-Agent: Mozilla/5.0...'
某些平台(如 Mux)分别提供音频和视频:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/audio/rendition.m3u8" \
-c copy audio.m4a
2. 下载视频流:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/video/rendition.m3u8" \
-c copy video.mp4
3. 合并流:
ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4
原因:缺少或不正确的身份验证标头。
解决方案:
症状:Extracting cookies from chrome 无限期挂起。
解决方案:对于 HLS 流,直接使用 ffmpeg 而不是 yt-dlp。
错误:Protocol 'https' not on whitelist 'file,crypto,data'
解决方案:添加 -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy
原因:m3u8 URL 中的签名已过期。
解决方案:
-c copy 无需重新编码(最快)references/po-token-setup.md每周安装次数
146
仓库
GitHub 星标数
713
首次出现
2026 年 1 月 21 日
安全审计
安装于
opencode119
claude-code118
codex113
gemini-cli112
cursor104
github-copilot102
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:
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:
Offer choices in user-friendly terms:
Always render the thumbnail when available:
.Ask before doing extra work:
Legal/Safety reminder (brief):
Response template (use plain language, no commands):

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”:
Follow this SOP to avoid common failures and confusion:
? as a glob). Example: 'https://www.youtube.com/watch?v=VIDEO_ID'.web_safari player client. Otherwise prefer mweb for PO tokens.scripts/download_video.py URL --info (add --cookies-from-browser chrome if permission granted) to fetch metadata and thumbnail.--subtitles and the requested --sub-lang.web_safari.--auto-po-token default). Fail fast if it cannot start.This skill should be invoked when users:
which yt-dlp
yt-dlp --version
If not installed or outdated (< 2025.10.22):
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.
Before downloading, check available formats:
yt-dlp -F "https://youtu.be/VIDEO_ID"
If only format 18 (360p) appears : PO token provider setup needed for high-quality access.
For 1080p/1440p/4K access, install a PO token provider plugin into yt-dlp's Python environment:
# 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.
Once PO token provider is installed:
# 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"
# Check video resolution
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name -of default=noprint_wrappers=1 video.mp4
Expected output for 1080p:
codec_name=vp9
width=1920
height=1080
If PO token provider setup is problematic, use browser cookies:
# Firefox
yt-dlp --cookies-from-browser firefox -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Chrome
yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
Benefits : Access to age-restricted and members-only content. Requirements :
Extract audio as MP3:
yt-dlp -x --audio-format mp3 "VIDEO_URL"
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
YouTube high-quality downloads often use WebM format (VP9 codec). Convert to MP4 for wider compatibility:
# Check if ffmpeg is installed
which ffmpeg || brew install ffmpeg # macOS
# Convert WebM to MP4 with good quality settings
ffmpeg -i "video.webm" -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "video.mp4"
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 kbpsTip : Conversion maintains 1080p resolution and provides ~6x encoding speed on modern hardware.
Cause : Missing PO token provider or outdated yt-dlp.
Solution :
brew upgrade yt-dlpCause : YouTube requires authentication to proceed.
Solution :
--cookies-from-browser chrome).web_safari client if needed.Cause : PO tokens not applied or provider/browser verification failed.
Solution :
web_safari client and retry.Symptoms :
WARNING: [youtube] nsig extraction failed: Some formats may be missing
Solution :
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"Cause : Proxy or network instability.
Solution :
For users in China or behind restrictive proxies:
WARNING: android client https formats require a GVS PO Token
Action : Ignore if download succeeds. This indicates Android client has limited format access without PO tokens.
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:
scripts/download_video.py "VIDEO_URL"
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)Note : Use the Android client only when PO tokens are disabled. Keep PO tokens enabled for high quality.
| Setup | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| Auto PO token (default) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Android client only | ✓ | ✗ | ✗ | ✗ | ✗ |
| PO token provider (manual) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Browser cookies | ✓ | ✓ | ✓ | ✓ | ✓ |
For streaming platforms like Mux, Vimeo, and other HLS-based services, use ffmpeg as the primary tool. These streams often require authentication headers that yt-dlp may not handle correctly.
HLS streams use .m3u8 playlist files:
Get the m3u8 URL from the video source. For protected streams:
Many CDNs require authentication headers:
https://maven.com/)Check the Network tab to see which headers the browser sends.
Use ffmpeg with the -headers flag for protected streams:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/path/rendition.m3u8?params" \
-c copy -bsf:a aac_adtstoasc \
output.mp4
Key parameters:
-headers: Set HTTP headers (critical for authentication)-protocol_whitelist: Enable required protocols for HLS-c copy: Stream copy (no re-encoding, faster)-bsf:a aac_adtstoasc: Fix AAC audio compatibilityCommon header patterns:
# Single header
-headers "Referer: https://example.com/"
# Multiple headers
-headers "Referer: https://example.com/" \
-headers "User-Agent: Mozilla/5.0..."
# Alternative syntax
-headers $'Referer: https://example.com/\r\nUser-Agent: Mozilla/5.0...'
Some platforms (like Mux) deliver audio and video separately:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/audio/rendition.m3u8" \
-c copy audio.m4a
2. Download video stream:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/video/rendition.m3u8" \
-c copy video.mp4
3. Merge streams:
ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4
Cause : Missing or incorrect authentication headers.
Solution :
Symptom : Extracting cookies from chrome hangs indefinitely.
Solution : Use ffmpeg directly instead of yt-dlp for HLS streams.
Error : Protocol 'https' not on whitelist 'file,crypto,data'
Solution : Add -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy
Cause : Expired signatures in the m3u8 URLs.
Solution :
-c copy (fastest)references/po-token-setup.md for detailed installation and troubleshootingWeekly Installs
146
Repository
GitHub Stars
713
First Seen
Jan 21, 2026
Security Audits
Gen Agent Trust HubWarnSocketPassSnykFail
Installed on
opencode119
claude-code118
codex113
gemini-cli112
cursor104
github-copilot102
Skills CLI 使用指南:AI Agent 技能包管理器安装与管理教程
40,000 周安装
host.docker.internal for Docker.--cookies-from-browser--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