首页 / 全部技能 / 内容创作 / youtube-downloader
English (EN)简体中文 (ZH)日本語 (JA)
内容创作 · 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.

L5 严管 · 隔离环境与严格审计V2 已复核凭据/登录态执行命令安装依赖联网读写文件Dual-pass Audit
Author daymadeGitHub daymade/claude-code-skills ↗Stars 1378License MITCommit 63a65c1fcc
管控等级描述 skill 的能力与建议配套的管控措施，不代表质量或安全认证，也不表示可用或不可用。是否使用由用户和管理者决定。不同 agent 宿主对权限的约束各不相同，请勿假定宿主一定会提供安全兜底。第三方 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外部依赖

KindDependency / Endpoint
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管控建议与判定依据

建议配套管控措施
面向 Agent
隔离环境，逐次授权
面向管理者
严格授权、全量审计、合规确认
判定依据（文件路径与关键语句摘要）
  • 本地凭据 / 浏览器配置: 读取用户登录 Cookie/会话/密钥环: 浏览器 cookie：--cookies-from-browser chrome/firefox → yt-dlp 读取浏览器 cookie 库（脚本
  • scripts/: 执行本地脚本或命令: 外部 CLI：yt-dlp（下载/元数据/格式列出）、ffprobe/ffmpeg、docker run/start/rm/info、pip inst
  • scripts/ 或 SKILL.md: 声明动态安装外部语言包依赖
  • 网络端点: 声明外部网络访问: youtube.com：yt-dlp 元数据/取流；oEmbed 兜底 urlopen https://www.youtube.com/oembed（
  • 本地工作目录: 文件读写与工件输出: 下载输出：output_dir 递归 mkdir + 按 -o 模板写视频/音频/字幕文件（模板支持绝对路径与 yt-dlp %()s 语法，用户可指
审计说明： 侦查意见，非认证。黄标主因是凭证与供应链：(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 自述失败模式依赖代理）。
    Install Agent-Ready
    ① Verified Mirror 2026-09-06
    Option A · Direct DownloadDownload youtube-downloader.tar.gz
    sha256: 6c6c403e7e905b4e…
    Option B · Copy Guide for Agent
    install.json
    agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 63a65c1fcc.