全部技能 / 内容创作 / youtube-downloader
内容创作 · daymade/claude-code-skills

youtube-downloader

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

风险提醒：黄色 · 留意使用AI 侦查报告
作者 daymadeGitHub daymade/claude-code-skills ↗Stars 1378许可 MITcommit 63a65c1fcc
agent 宿主通常会约束 skill 执行权限；风险提醒为 AI 侦查观点，不构成质量或安全保证。第三方 skill 仅作拆解与展示，安装使用风险自负，版权归原作者。

1实现原理 · 为什么它能做到

核心是 yt-dlp/ffmpeg CLI 封装：SKILL.md 指导 agent 用 yt-dlp 下载、ffmpeg 处理 HLS/转码，并自带 python 包装脚本 download_video.py 把下载流程程序化。

SKILL.md
Enable reliable video and audio downloads from YouTube and HLS streaming platforms (Mux, Vimeo, etc.) using yt-dlp and ffmpeg.
注：实现原理=编排外部 CLI，非自带解码。脚本内部 cmd = ["yt-dlp"] 开始拼 argv 再 subprocess.run，全程无 shell=True。

PO Token 提供者自动编排（高画质关键）：自动 pip 安装插件进 yt-dlp 的 Python 环境，优先 docker 跑 brainicism/bgutil-ytdlp-pot-provider 容器（-p 4416:4416），ping 127.0.0.1:4416 探活，Docker 缺失/失败则回退 pip 安装 yt-dlp-getpot-wpc 走浏览器 WPC 方案。

scripts/download_video.py
run_cmd = ["docker", "run", "-d", "--name", name] ... "-p", "4416:4416", *env_args, "--init", "brainicism/bgutil-ytdlp-pot-provider"
注：此处在做：把第三方 PO token 提供者容器化拉起并注入代理 env；对应 SKILL.md 声明 'YouTube downloads (up to 4K) using PO token providers'。代码不可在本 repo 审计（供应链面）。

cookie 认证路径：经授权后把浏览器 cookie 会话交给 yt-dlp（--cookies-from-browser chrome/firefox 或 --cookies 文件），有 cookie 时强制 youtube player client 走 web_safari。

scripts/download_video.py
cmd.extend(["--cookies-from-browser", cookies_from_browser]) ... elif cookies_file: cmd.extend(["--cookies", cookies_file])
注：此处在做：cookie 解密/读取实际由 yt-dlp 完成，脚本只透传参数，并据 SKILL.md 约定 'Ask before extracting browser cookies.' 走权限确认。

面向非技术用户的 UX 编排：agent 全代跑——先 --info 取元数据（失败走 YouTube oEmbed 兜底）确认视频身份，再按默认/选择下载，最后报告文件路径、大小、分辨率，全程不要求用户敲命令。

SKILL.md
Assume the user is non-technical. Do not ask them to run commands. Execute everything yourself and report progress in plain language.
注：oEmbed 兜底在脚本 fetch_oembed_info：urlopen https://www.youtube.com/oembed?...，bot 拦截时仍可确认标题/上传者，降低下错视频风险。

错误驱动重试链：把 yt-dlp 常见失败（403 / nsig / 'Only images are available' / SSL EOF）映射为策略——403 退非 m3u8 progressive 格式；PO token 故障则重启容器或切 WPC 重试；cookie+403 则换 web_safari client。

scripts/download_video.py
return "http error 403" in text or "403: forbidden" in text or "fragment 1 not found" in text
注：has_403_error/has_pot_error/has_wpc_error + download_video 内多重 retry 分支，是技能'可靠性'声称的技术来源。

代理感知设计（面向中国大陆网络）：读取环境代理 ALL_PROXY/HTTPS_PROXY/HTTP_PROXY 透传给 yt-dlp、pip、docker 容器，localhost 代理改写为 host.docker.internal；pip 走硬编码清华镜像 pypi.tuna.tsinghua.edu.cn。

scripts/download_video.py
PYPI_MIRROR = "https://pypi.tuna.tsinghua.edu.cn/simple"
注：normalize_proxy_for_docker 保留代理 URL 中的 user:password 并注入容器环境变量——代理凭证会进入第三方容器进程环境。

2核心能力

01YouTube 视频/播放列表下载，质量预设 best/1080p/720p/480p/360p/worst（MP4 合并输出）
02音频提取 MP3 与字幕下载（-x --audio-format mp3 / --write-subs --write-auto-subs --sub-lang）
03元数据预取与确认（--dump-json 解析 title/uploader/duration/thumbnail，失败回退 YouTube oEmbed）
04自动 PO Token 高画质解锁（Docker bgutil 优先 → 浏览器 WPC 回退 → 故障重启重试）
05浏览器 cookie 认证下载（--cookies-from-browser chrome/firefox，web_safari client，日志脱敏）
06HLS (m3u8) 受保护流下载指引与降级重试（ffmpeg -headers + -protocol_whitelist 指南；脚本内非 m3u8 progressive 回退格式）
07代理与镜像适配（中国大陆网络：清华 PyPI 镜像装插件、代理透传/容器化改写）

3外部依赖

类型依赖
cliyt-dlp
cliffmpeg / ffprobe
clidocker
clipython / pip（yt-dlp 解释器）
networkyoutube.com（下载取流 + oEmbed 元数据）
network清华 PyPI 镜像（硬编码装插件源）
networkDocker Hub 镜像 brainicism/bgutil-ytdlp-pot-provider（第三方 PO token 服务，拉取即执行）
network本机 PO provider 探活端点
network用户提供任意视频/HLS URL（m3u8 可指向任意第三方 CDN，如 Mux/Vimeo）
packagebgutil-ytdlp-pot-provider（pip 插件）
packageyt-dlp-getpot-wpc（pip 浏览器版 token 提供者，会启动真实浏览器）

4风险提醒 风险提醒：黄色 · 留意使用

风险提醒：黄色 · 留意使用
  • cookie 授权无程序强制，依赖 agent 遵循 SKILL 文本；恶意链接/长上下文可诱导携 cookie 下载 — SKILL.md 'Ask before extracting browser cookies.' 只是约定；cookie 解密后位于 yt-dlp 内存/下载流中
  • 供应链信任：自动 pip 装插件 + docker 常驻第三方 brainicism 镜像，容器内代码不在本 repo 审计范围 — .security-scan-passed 只是目录静态文本 gitleaks 标记（Content hash 6dc9ae…），不含运行时第三方代码
  • WPC 路径会真实拉起本机 Chrome 在用户登录态访问 YouTube 铸 token，属用户身份下的外部请求 — SKILL.md 'Keep the browser window open while WPC is minting tokens.' + with_wpc_browser 传参
  • 任意 URL/headers 原样信任：可被诱导对任意端点（含内网）发起 yt-dlp/ffmpeg 请求；HLS 的 Referer/Origin headers 由用户提供直接使用 — SKILL.md HLS 章节要求从 DevTools 复制 headers 喂 ffmpeg；下载 URL 无白名单/校验
  • 环境改动面大：pip 写 yt-dlp 的 Python 环境、docker 起常驻容器、--output-template 支持绝对路径任意写 — build_output_template 对绝对模板原样接受；脚本无任何输出路径限制
侦查意见，非认证。黄标主因是凭证与供应链：(a) cookie 读取路径真实存在且是核心卖点（cookie 解密在 yt-dlp 侧完成，脚本透传并做日志脱敏，SKILL 要求先征询——有纪律但无强制）；(b) 自动 pip 安装两个第三方插件 + docker 拉取并常驻第三方 brainicism 容器，容器内代码超出本 repo 审计范围，.security-scan-passed 仅覆盖本目录静态文本的 gitleaks 扫描；(c) WPC 路径会拉起真实 Chrome 以用户登录态访问 YouTube；(d) 下载任意用户 URL、headers/模板原样信任构成 SSRF 与任意文件写侧面。脚本本身无 shell=True/无混淆/无隐蔽外发，故未到 red；绿档要求不成立，故定 yellow。

5第二遍独立确认

  • [ok] yt-dlp 调用真实存在（下载/-F/-o/-f/--dump-json） — 脚本 cmd = ["yt-dlp"] 起步（738 行），全部参数列表化
  • [ok] ffmpeg/ffprobe 调用 — SKILL.md 多处 ffmpeg 命令 + 脚本 get_video_resolution 中 which ffprobe 实测存在
  • [ok] cookie 读取路径（--cookies-from-browser / --cookies） — 773-776 行真实拼接；注意解密主体是 yt-dlp 而非脚本，脚本无 cookie 解析代码
  • [ok] cookie 日志脱敏 filter_cookie_lines — 仅过滤含 'extracting cookies' 或 'extracted'+'cookies' 的行，非完整脱敏（其他含 cookie 内容行仍会输出）——实现与声称基本一致，范围略窄
  • [ok] oEmbed 兜底网络端点 — 660-663 行 urlopen youtube.com/oembed，URL 经 quote 编码，无注入面
  • [ok] PO token：docker bgutil 容器 + 4416 ping 探活 — 437-446/553-563 行 docker run brainicism 镜像，255-257 行 ping；容器内实现本 repo 无法审计 → 供应链项如实标注
  • [ok] WPC 浏览器回退自动拉起 Chrome — 脚本只传 --extractor-args youtubepot-wpc:browser_path=…（249-252 行）+ find_chrome_path；真实浏览器启动由第三方插件 yt-dlp-getpot-wpc 完成，脚本侧证据到传参为止
  • [ok] pip 自动安装插件（清华镜像） — 350、377 行安装命令真实存在，PYPI_MIRROR 38 行硬编码

6结论

  • 反爬故障知识高度工程化：nsig/PO token/403/'Only images'/SSL EOF 等坑被编码成错误分类与自动重试链，脚本自愈能力强
  • 双层 UX 设计：面向非技术用户的白话流程 + 面向 agent 的内部 SOP，两者职责清晰、纪律一致（references/internal-sop.md 与 SKILL 清单逐条对应）
  • cookie 隐私纪律罕见地落在两层：SKILL 文本禁止暴露 cookie 明细 + 脚本层过滤日志行
  • 国内网络定向适配完整（清华镜像、代理透传、docker 内 localhost 代理改写、WPC 兜底），对大陆用户实际可用
  • 元数据 oEmbed 兜底 + 下载前确认，bot 拦截场景仍能避免下错视频
    • 适合：希望 agent 一键高质量下载 YouTube/公开 HLS 视频、愿意一次性授权 cookie 或安装 Docker/PO 插件的个人用户（含中国大陆走代理场景）；或需要在自有受控环境批量拉取有权内容的运维/内容工作者。
    不适合：零信任/供应链敏感的生产 agent 沙箱（会装第三方插件、拉第三方容器、自动开浏览器）；headless 无 GUI 且无 Docker 的环境（WPC 需浏览器窗口，仅剩 360p Android client）；不允许读取浏览器 cookie 的企业策略环境；无代理的国内直连（SKILL 自述失败模式依赖代理）。
    安装 agent 直装可复制
    ② 上游 GitHub · 原始来源
    能访问 GitHub？直接去上游安装（实时版，可能已更新）GitHub 原始 ↗
    本页镜像锁定 commit 63a65c1fcc；上游为实时仓库。
    来源信息 GitHub 原始
    作者 / 仓库daymade / daymade/claude-code-skills
    原始 GitHubdaymade/claude-code-skills ↗
    Stars1378
    最近推送2026-09-06
    本 skill commit63a65c1fcc
    许可MIT
    本站信息
    收录日期2026-09-06
    分类内容创作
    侦查报告2026-09-06 · 2 遍
    本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。