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

标题:...
频道:...
时长:...
我可以帮你:
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 Token 提供程序都处于活动状态(
HTTP_PROXY/HTTPS_PROXY/ALL_PROXY)。 - 如果看到“登录以确认你不是机器人”,请求许可并使用浏览器 cookie。没有 cookie 不要继续。
- 在下载前启动 PO Token 提供程序(如果无法启动则快速失败)。
- 如果可用,使用 Docker bgutil 提供程序。
- 如果 Docker 缺失或失败,切换到基于浏览器的 WPC 提供程序。
- 如果使用 cookie,优先选择
web_safari播放器客户端。否则对于 PO Token,优先选择mweb。 - 当 WPC 在铸造 token 时,保持浏览器窗口打开。确保 Chrome 可以通过同一代理访问 YouTube。
- 如果收到“仅提供图片”或“请求的格式不可用”,将其视为 PO Token 故障,并在修复 token 提供程序/浏览器状态后重试。
- 如果收到 SSL EOF 或片段错误,将其视为代理/网络问题。使用渐进式格式和/或更好的代理重试。
代理执行检查清单(内部)
- 运行
scripts/download_video.py URL --info(如果获得许可,添加--cookies-from-browser chrome)以获取元数据和缩略图。 - 如果 yt-dlp 元数据失败,依赖脚本的 oEmbed 回退来获取标题/上传者/缩略图,并注意时长可能不可用。
- 如果存在缩略图 URL,在响应中使用 Markdown 图片语法渲染它。
- 要求用户选择视频 vs. 仅音频,以及(可选)质量标准。
- 使用友好的默认保存位置(下载文件夹),除非用户指定了文件夹。
- 对于字幕,使用
--subtitles和请求的--sub-lang运行。 - 下载后,用通俗语言报告文件名、大小和分辨率(如果是视频)。
- 如果下载失败并返回 403/片段错误,使用非 m3u8 的渐进式格式重试一次。
- 如果出现“登录以确认你不是机器人”,请求 cookie 访问并使用 cookie +
web_safari重试。 - 如果出现“仅提供图片”,将其视为 PO Token 故障,并在修复提供程序/浏览器状态后重试。
- 在下载前启动 PO Token 提供程序(默认
--auto-po-token)。如果无法启动则快速失败。 - 如果基于 Docker 的提供程序失败(在中国常见),自动回退到基于浏览器的 WPC 提供程序(它可能会短暂打开一个浏览器窗口)。
- 如果使用 WPC 提供程序,保持浏览器窗口打开直到下载开始。如果浏览器无法启动,明确设置 Chrome 路径。
- 如果 PO Token 提供程序超时,重启一次并重试。
- 如果配置了系统代理,将其传递给提供程序容器。如果代理指向 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 Token 提供程序才能访问高质量。
高质量下载工作流程
步骤 1:安装 PO Token 提供程序(一次性设置)
为了获得 1080p/1440p/4K 访问权限,在 yt-dlp 的 Python 环境中安装 PO Token 提供程序插件:
# 找到 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 Token 提供程序后:
# 下载最高 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 Token 提供程序设置有问题,请使用浏览器 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/代理。
- 不要将 cookie 与 Android 客户端一起使用(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 Token 提供程序或 yt-dlp 版本过旧。
解决方案:
- 更新 yt-dlp:
brew upgrade yt-dlp - 安装 PO Token 提供程序(参见上面的步骤 1)
- 或使用浏览器 cookie 方法
登录以确认你不是机器人
原因:YouTube 要求进行身份验证。
解决方案:
- 请求许可并使用浏览器 cookie(
--cookies-from-browser chrome)。 - 确保浏览器和 yt-dlp 使用相同的 IP/代理。
- 如果需要,使用
web_safari客户端重试。
仅提供图片 / 请求的格式不可用
原因:未应用 PO Token 或提供程序/浏览器验证失败。
解决方案:
- 在下载前验证 PO Token 提供程序是否在运行。
- 如果使用 WPC,保持浏览器窗口打开。
- 如果使用 cookie,优先选择
web_safari客户端并重试。
nsig 提取失败
症状:
警告:[youtube] nsig 提取失败:某些格式可能缺失
解决方案:
- 将 yt-dlp 更新到最新版本
- 安装 PO Token 提供程序
- 如果仍然失败且 PO Token 已禁用,使用 Android 客户端:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
SSL EOF / 片段错误
原因:代理或网络不稳定。
解决方案:
- 使用渐进式格式(非 m3u8)重试。
- 切换到更稳定的代理/节点。
- 避免在下载过程中关闭 PO Token 浏览器窗口。
下载速度慢或网络错误
对于中国用户或位于限制性代理后面的用户:
- 由于网络状况,下载可能很慢
- 留出足够的时间完成
- yt-dlp 会在临时故障时自动重试
PO Token 警告(无害)
警告:android 客户端 https 格式需要 GVS PO Token
操作:如果下载成功,请忽略。这表明 Android 客户端在没有 PO Token 的情况下格式访问受限。
捆绑脚本参考
scripts/download_video.py
使用此便捷包装脚本默认自动启动 PO Token 提供程序,以实现高质量下载。你自己使用它并向用户报告结果,无需要求他们运行命令。
基本用法:
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 Token 提供程序(默认;如果可用则使用 Docker,否则切换到基于浏览器的提供程序)--no-auto-po-token- 禁用自动 PO Token 设置--proxy- 用于 yt-dlp 和 PO Token 提供程序的代理 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 Token 禁用时使用 Android 客户端。保持 PO Token 启用以获得高质量。
质量预期
| 设置 | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| 自动 PO token(默认) | ✓ | ✓ | ✓ | ✓ | ✓ |
| 仅 Android 客户端 | ✓ | ✗ | ✗ | ✗ | ✗ |
| PO token 提供程序(手动) | ✓ | ✓ | ✓ | ✓ | ✓ |
| 浏览器 cookie | ✓ | ✓ | ✓ |