YouTube下载器 是做什么的?
概述
使用yt-dlp和ffmpeg从YouTube和HLS流媒体平台(如Mux、Vimeo等)实现可靠的视频和音频下载。此技能提供以下工作流:
- 使用PO令牌提供程序或浏览器cookie进行YouTube下载(最高4K)
- 使用认证头进行HLS流下载
- 处理受保护内容并解决常见下载故障
非技术用户体验(默认)
假设用户是非技术人员。不要要求他们运行命令。自己执行所有操作,并用通俗的语言报告进度。除非用户询问,否则避免提及工具。
默认流程:
- 询问URL(如果未提供)。
- 获取视频元数据(标题/上传者/时长/缩略图)并确认与用户意图匹配。
- 如果yt-dlp被“确认你不是机器人”阻止,则回退到YouTube oEmbed以获取标题/上传者/缩略图(时长可能未知)。
- 提供简单选项(视频与纯音频、质量、字幕、保存位置)。
- 如果用户未指定,则使用合理的默认值:
- 以最佳质量下载视频
- 合并输出为MP4
- 仅下载单个视频(无播放列表)
- 下载并报告最终文件路径、文件大小和分辨率(如果是视频)。
以用户友好的术语提供选项:
- “以最佳质量下载视频(默认)”
- “仅下载音频(MP3)”
- “选择质量:1080p / 720p / 480p / 360p”
- “包含字幕(如果可用)”
- “保存到下载文件夹(默认)或告诉我其他文件夹”
始终在可用时渲染缩略图:
- 如果元数据包含缩略图URL,使用Markdown图像语法包含它:
。
在进行额外工作前询问:
- 确认播放列表下载(可能很大)。
- 确认安装/升级依赖项(如果缺失)。
- 在提取浏览器cookie前询问。
- 如果使用cookie,切勿在面向用户的响应中提及cookie数量或原始cookie详细信息。请说“使用了您的Chrome登录会话”。
- 如果需要验证,自动设置本地PO令牌助手(无需用户操作)。如果Docker缺失或失败,不要尝试安装Docker——切换到基于浏览器的PO令牌提供程序。
法律/安全提醒(简短):
- 仅当用户拥有下载内容的权利或许可时才继续。
响应模板(使用通俗语言,无命令):

标题:…
频道:…
时长:…
我可以帮您:
1) 下载视频(最佳质量,MP4)
2) 仅下载音频(MP3)
3) 选择特定质量(1080p/720p/480p/360p)
4) 包含字幕(如果可用)
应该保存到哪里?(默认:下载文件夹)
如果用户说“直接下载”:
- 使用默认值继续,并在下载完成时确认。
- 如果被403阻止,自动设置验证助手并重试。
可靠下载SOP(内部)
遵循此SOP以避免常见故障和混淆:
- 在shell命令中引用URL(zsh将
?视为通配符)。示例:'https://www.youtube.com/watch?v=VIDEO_ID'。 - 确保代理对yt-dlp和PO令牌提供程序均处于活动状态(HTTP_PROXY/HTTPS_PROXY/ALL_PROXY)。
- 如果看到“登录以确认你不是机器人”,请求权限并使用浏览器cookie。在没有cookie的情况下不要继续。
- 在下载前启动PO令牌提供程序(如果无法启动则快速失败)。
- 当可用时使用Docker bgutil提供程序。
- 如果Docker缺失或失败,切换到基于浏览器的WPC提供程序。
- 如果正在使用cookie,优先使用
web_safari播放器客户端。否则,对于PO令牌优先使用mweb。 - 在WPC铸造令牌时保持浏览器窗口打开。确保Chrome可以通过同一代理访问YouTube。
- 如果遇到“仅图像可用”或“请求的格式不可用”,将其视为PO令牌失败,并在修复令牌提供程序/浏览器状态后重试。
- 如果遇到SSL EOF或片段错误,将其视为代理/网络问题。使用渐进格式和/或更好的代理重试。
代理执行检查清单(内部)
- 运行
scripts/download_video.py URL --info(如果获得许可,添加--cookies-from-browser chrome)以获取元数据和缩略图。 - 如果yt-dlp元数据失败,依赖脚本的oEmbed回退获取标题/上传者/缩略图,并注意时长可能不可用。
- 如果存在缩略图URL,在响应中使用Markdown图像语法渲染它。
- 询问用户选择视频还是纯音频,并(可选)选择质量预设。
- 使用友好的默认保存位置(下载文件夹),除非用户指定了文件夹。
- 对于字幕,使用
--subtitles和请求的--sub-lang运行。 - 下载后,用通俗语言报告文件名、大小和分辨率(如果是视频)。
- 如果下载失败并出现403/片段错误,使用非m3u8渐进格式重试一次。
- 如果出现“登录以确认你不是机器人”,请求cookie访问权限并用cookie +
web_safari重试。 - 如果出现“仅图像可用”,将其视为PO令牌失败,并在修复提供程序/浏览器状态后重试。
- 在下载前启动PO令牌提供程序(
--auto-po-token默认)。如果无法启动则快速失败。 - 如果基于Docker的提供程序失败(在中国常见),自动回退到基于浏览器的WPC提供程序(它可能会短暂打开浏览器窗口)。
- 如果使用WPC提供程序,在下载开始前保持浏览器窗口打开。如果浏览器启动失败,显式设置Chrome路径。
- 如果PO令牌提供程序超时,重启一次并重试。
- 如果配置了系统代理,将其传递给提供程序容器。如果代理指向127.0.0.1/localhost,将其重写为
host.docker.internal以供Docker使用。
何时使用此技能
当用户出现以下情况时应调用此技能:
- 请求下载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访问权限,将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。
步骤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。
- 浏览器和yt-dlp必须使用相同的IP/代理。
- 不要将Android客户端与cookie一起使用(Android客户端不支持cookie)。
常见任务
仅下载音频(自行运行)
将音频提取为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方法
登录以确认你不是机器人
原因:YouTube需要身份验证才能继续。
解决方案:
- 请求许可并使用浏览器cookie(
--cookies-from-browser chrome)。 - 确保浏览器和yt-dlp使用相同的IP/代理。
- 如果需要,使用
web_safari客户端重试。
仅图像可用 / 请求的格式不可用
原因:未应用PO令牌或提供程序/浏览器验证失败。
解决方案:
- 在下载前验证PO令牌提供程序正在运行。
- 如果使用WPC,保持浏览器窗口打开。
- 如果正在使用cookie,优先使用
web_safari客户端并重试。
nsig提取失败
症状:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
解决方案:
- 将yt-dlp更新到最新版本
- 安装PO令牌提供程序
- 如果仍然失败且PO令牌被禁用,使用Android客户端:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
SSL EOF / 片段错误
原因:代理或网络不稳定。
解决方案:
- 使用渐进格式(非m3u8)重试。
- 切换到更稳定的代理/节点。
- 避免在下载过程中关闭PO令牌浏览器窗口。
下载慢或网络错误
对于在中国或受限制代理后面的用户:
- 由于网络条件,下载可能较慢
- 允许足够的时间完成
- yt-dlp会自动重试临时故障
PO令牌警告(无害)
WARNING: android client https formats require a GVS PO Token
操作:如果下载成功则忽略。这表示没有PO令牌时Android客户端对格式访问受限。
捆绑脚本参考
scripts/download_video.py
使用此便捷包装器默认自动启动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 | ✓ | ✓ | ✓ | ✓ | ✓ |