用途:这是一个用于下载 YouTube 视频的技能,借助 yt-dlp 实现交互式分辨率与字幕选择。当用户想下载或保存 YouTube 视频时可使用。
前置依赖:使用前会静默检测 yt-dlp 与 ffmpeg 是否可用(yt-dlp --version、ffmpeg -version)。缺失时自动安装,无需询问用户:pip install -U yt-dlp 与 pip install ffmpeg-static;若无 pip 则尝试 pip3,ffmpeg-static 失败可用 imageio[ffmpeg],macOS 可用 brew install ffmpeg,Linux 可用 apt-get install -y ffmpeg。还会检查 JavaScript 运行时(node 或 deno),可选安装 apt-get install -y nodejs 或 brew install node。安装后需验证并告知用户。
主要流程:第一步运行 yt-dlp -F "URL" 获取格式表,整理为视频+音频、纯视频、纯音频三类摘要(含分辨率、编解码器、大致大小),让用户选择最佳画质、1080p MP4、720p MP4、纯音频或自定义。第二步运行 yt-dlp --list-subs "URL" 检查字幕,告知手动字幕与自动生成字幕的语言,让用户选择不下载字幕、英文 SRT、全部语言或指定语言。第三步在下载前展示选择摘要与将执行的完整 yt-dlp 命令并确认。第四步下载完成后用 ls -lh 列出文件大小并报告路径、实际分辨率与编解码器。
格式选择器:最佳画质用 -f "bv*+ba/b";1080p MP4 用 -f "bv*[height<=1080][ext=mp4]+ba[ext=m4a]/b[ext=mp4]";720p MP4 用 -f "bv*[height<=720][ext=mp4]+ba[ext=m4a]/b[ext=mp4]";纯音频用 -f "ba/b" --extract-audio --audio-format mp3。字幕相关参数:手动字幕用 --write-subs --sub-langs "LANG" --convert-subs srt;自动生成用 --write-auto-subs --sub-langs "LANG" --convert-subs srt;两者兼有则同时加两个写入参数;全部语言用 --sub-langs "all"。下载字幕时始终加 --convert-subs srt,因为 YouTube 原生为 VTT/srv3,SRT 兼容性更好。
受限内容认证:年龄限制、私密或会员专属视频需要认证。桌面环境(Claude Code、Cursor)可用 --cookies-from-browser chrome(或 firefox、edge、safari),前提是用户已在该浏览器登录 YouTube。沙箱环境(Cowork、云)无本地浏览器配置,可借助 Playwright 获取 cookie:导航到 https://accounts.google.com 让用户登录,登录后提取 cookie,写入 Netscape cookie 文件(如 /tmp/yt-cookies.txt),再用 --cookies /tmp/yt-cookies.txt 重试,下载完成后清理该文件。注意 DRM 保护内容(租赁/购买影片、YouTube Premium 原创)即使认证也无法下载。
错误处理:会解析 yt-dlp 的 stderr 并给出可操作建议,例如机器人检测或私密视频触发浏览器认证,会员内容需用户为频道会员,视频不可用说明已删除,地区限制建议 VPN 或 --proxy,DRM 说明无法下载,格式不匹配回退到 -f "bv*+ba/b",ffmpeg 缺失则重跑安装,缺少 JS 运行时则安装 nodejs 后重试。不会向用户展示原始错误输出。
疑难排查:下载慢可加 --concurrent-fragments 4 并行下载;地区限制视频需要 VPN 或代理,用户提供时可用 --proxy URL。
限制:无法下载 DRM 加密内容;部分功能依赖浏览器登录或 Playwright 环境;资料未提供费用、平台支持范围等更多信息。