YouTube 下载器
概述
使用 yt-dlp 和 ffmpeg,从 YouTube 和 HLS 流媒体平台(如 Mux、Vimeo 等)可靠地下载视频和音频。该技能提供了以下工作流:
- YouTube 下载(最高 4K),使用 PO 令牌提供器或浏览器 cookie
- 使用认证头进行 HLS 流下载
- 处理受保护内容并排查常见下载失败问题
何时使用此技能
当用户出现以下情况时应调用此技能:
- 请求下载 YouTube 视频或播放列表
- 想从 YouTube 视频中提取音频
- 遇到 yt-dlp 下载失败或可用格式有限
- 需要格式选择或质量选项方面的帮助
- 仅报告低质量(360p)格式可用
- 询问以特定质量(1080p、4K 等)下载 YouTube 内容
- 需要将下载的 WebM 视频转换为 MP4 格式以获得更广泛的兼容性
- 请求从 Mux、Vimeo 或其他流媒体服务下载 HLS 流 (m3u8)
- 需要下载需要认证头的受保护流
前置条件
1. 验证 yt-dlp 安装
which yt-dlp
yt-dlp --version
如果未安装或版本过旧(< 2025.10.22):
brew upgrade yt-dlp # macOS
# 或
pip install --upgrade yt-dlp # 跨平台
关键:过旧的 yt-dlp 版本会导致 nsig 提取失败和格式缺失。
2. 检查当前质量访问权限
在下载前,检查可用格式:
yt-dlp -F "https://youtu.be/VIDEO_ID"
如果仅出现格式 18(360p):需要设置 PO 令牌提供器以获得高质量访问。
高质量下载工作流
步骤 1:安装 PO 令牌提供器(一次性设置)
要访问 1080p/1440p/4K,在 yt-dlp 的 Python 环境中安装 PO 令牌提供器插件:
# 查找 yt-dlp 的 Python 路径
head -1 $(which yt-dlp)
# 安装插件(根据 yt-dlp 版本调整路径)
/opt/homebrew/Cellar/yt-dlp/$(yt-dlp --version)/libexec/bin/python -m pip install bgutil-ytdlp-pot-provider
验证:再次运行 yt-dlp -F "VIDEO_URL"。查找格式 137(1080p)、271(1440p)或 313(4K)。
有关详细的安装说明和故障排除,请参阅 references/po-token-setup.md。
步骤 2:以最佳质量下载
安装 PO 令牌提供器后:
# 下载最高 1080p 的最佳质量
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# 下载最佳可用质量(如果可用则为 4K)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"
步骤 3:验证下载质量
# 检查视频分辨率
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
替代方案:浏览器 Cookie 方法
如果 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"
优点:可访问受年龄限制和会员专属内容。 要求:必须在指定浏览器中登录 YouTube。
常见任务
仅下载音频
将音频提取为 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"
将 WebM 转换为 MP4
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 倍的编码速度。
故障排查快速参考
仅 360p 可用(格式 18)
原因:缺少 PO 令牌提供器或 yt-dlp 版本过旧。
解决方案:
- 更新 yt-dlp:
brew upgrade yt-dlp - 安装 PO 令牌提供器(参见上面的步骤 1)
- 或使用浏览器 cookie 方法
nsig 提取失败
症状:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
解决方案:
- 将 yt-dlp 更新到最新版本
- 安装 PO 令牌提供器
- 如果仍然失败,请使用 Android 客户端:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
下载缓慢或网络错误
对于在中国或受限代理后面的用户:
- 由于网络状况,下载可能会很慢
- 留出足够的时间完成
- yt-dlp 会在临时故障时自动重试
PO 令牌警告(无害)
WARNING: android client https formats require a GVS PO Token
操作:如果下载成功,请忽略。这表明没有 PO 令牌,Android 客户端的格式访问受限。
捆绑脚本参考
scripts/download_video.py
一个便利封装器,默认应用 Android 客户端解决方法:
基本用法:
scripts/download_video.py "VIDEO_URL"
参数:
url- YouTube 视频 URL(必需)-o, --output-dir- 输出目录-f, --format- 格式规范-a, --audio-only- 将音频提取为 MP3-F, --list-formats- 列出可用格式--no-android-client- 禁用 Android 客户端解决方法
注意:此脚本使用 Android 客户端(没有 PO 令牌时仅支持 360p)。要获得高质量,请直接使用带 PO 令牌提供器的 yt-dlp。
质量预期
| 设置 | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| 无设置(默认) | ✗ | ✗ | ✗ | ✗ | ✗ |
| 仅 Android 客户端 | ✓ | ✗ | ✗ | ✗ | ✗ |
| PO 令牌提供器 | ✓ | ✓ | ✓ | ✓ | ✓ |
| 浏览器 cookie | ✓ | ✓ | ✓ | ✓ | ✓ |
HLS 流下载 (m3u8)
对于像 Mux、Vimeo 和其他基于 HLS 的服务等流媒体平台,请使用 ffmpeg 作为主要工具。这些流通常需要认证头,yt-dlp 可能无法正确处理。
识别 HLS 流
HLS 流使用 .m3u8 播放列表文件:
- 主播放列表:列出多个质量选项
- 转码播放列表:包含实际的视频/音频片段 URL
下载工作流
步骤 1:获取流 URL
从视频源获取 m3u8 URL。对于受保护的流:
- 打开浏览器开发者工具 → 网络选项卡
- 播放视频
- 过滤 "m3u8" 以查找播放列表 URL
- 复制转码 URL(通常包含质量信息,如 "rendition.m3u8")
步骤 2:识别所需头
许多 CDN 需要认证头:
- Referer:来源网站(例如
https://maven.com/) - Origin:与 Referer 相同,用于 CORS
- User-Agent:浏览器标识
检查网络选项卡以查看浏览器发送了哪些头。
步骤 3:使用 ffmpeg 下载
对于受保护的流,使用带有 -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
- 下载视频流:
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
- 合并流:
ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4
HLS 下载故障排查
403 禁止错误
原因:缺失或不正确的认证头。
解决方案:
- 验证 Referer 头与视频源网站匹配
- 检查是否需要其他头(Origin、User-Agent)
- 确保 m3u8 URL 包含浏览器中的所有查询参数
yt-dlp 在 Cookie 提取时卡住
症状: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 中的签名已过期。
解决方案:
- 从浏览器开发者工具获取新的 URL
- 获取 URL 后立即下载
- 查找具有更新签名参数的转码 URL
性能提示
- HLS 下载通常以 10-15 倍实时速度运行
- 使用
-c copy无需重新编码(最快) - 通过实时进度显示监控下载
- 使用绝对输出路径以避免目录混乱
延伸阅读
- PO 令牌设置:请参阅
references/po-token-setup.md了解详细的安装和故障排除 - yt-dlp 文档:https://github.com/yt-dlp/yt-dlp
- 格式选择指南:https://github.com/yt-dlp/yt-dlp#format-selection