Content & Media Creation · daymade/claude-code-skills

youtube-downloader

Name: youtube-downloader
Author: daymade/claude-code-skills

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 Restricted · Isolated sandbox & strict auditV2 Human-AuditedCredential / SessionExecute CommandInstall DepsNetwork AccessWrite FileDual-pass Audit

Author daymadeGitHub daymade/claude-code-skills ↗Stars 1378License MITCommit 63a65c1fcc

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Core implementation relies on yt-dlp/ffmpeg CLI wrappers: SKILL.md guides the agent to use yt-dlp for downloading and ffmpeg for HLS processing/transcoding, bundled with a Python wrapper script download_video.py to programmatically automate the download process.

SKILL.md

Enable reliable video and audio downloads from YouTube and HLS streaming platforms (Mux, Vimeo, etc.) using yt-dlp and ffmpeg.

Implementation mechanism = orchestrating external CLIs rather than built-in decoders. The script constructs argv starting with cmd = ["yt-dlp"] and executes it via subprocess.run, strictly avoiding shell=True throughout.

Automated orchestration of PO Token providers (crucial for high quality): Automatically runs pip install to add plugins into yt-dlp's Python environment. It prioritizes launching the brainicism/bgutil-ytdlp-pot-provider Docker container (-p 4416:4416) with health checks pinging 127.0.0.1:4416; if Docker is missing or fails, it falls back to pip install yt-dlp-getpot-wpc to run the browser-based WPC approach.

scripts/download_video.py

run_cmd = ["docker", "run", "-d", "--name", name] ... "-p", "4416:4416", *env_args, "--init", "brainicism/bgutil-ytdlp-pot-provider"

What is happening here: Pulling up and containerizing a third-party PO token provider while injecting proxy env variables; aligns with the SKILL.md claim 'YouTube downloads (up to 4K) using PO token providers'. The container code cannot be audited within this repo (supply chain surface).

Cookie authentication pipeline: Upon authorization, passes the browser cookie session to yt-dlp (--cookies-from-browser chrome/firefox or a --cookies file), forcing the youtube player client to web_safari when cookies are present.

scripts/download_video.py

cmd.extend(["--cookies-from-browser", cookies_from_browser]) ... elif cookies_file: cmd.extend(["--cookies", cookies_file])

What is happening here: Cookie decryption/reading is actually handled by yt-dlp; the script merely passes arguments through and follows the SKILL.md convention 'Ask before extracting browser cookies.' to obtain permission.

UX orchestration designed for non-technical users: Fully delegated to the agent—first fetches metadata via --info (falling back to YouTube oEmbed on failure) to verify video identity, downloads according to defaults or selections, and finally reports the file path, size, and resolution, requiring zero terminal commands from the user throughout.

SKILL.md

Assume the user is non-technical. Do not ask them to run commands. Execute everything yourself and report progress in plain language.

The oEmbed fallback is in the script's fetch_oembed_info: urlopen https://www.youtube.com/oembed?...; when bot detection blocks requests, it can still confirm the title/uploader, reducing the risk of downloading the wrong video.

Error-driven retry chain: Maps common yt-dlp failures (403 / nsig / 'Only images are available' / SSL EOF) to strategies—falling back to non-m3u8 progressive formats on 403; restarting the container or switching to WPC on PO token failure; switching to the web_safari client on cookie+403 errors.

scripts/download_video.py

return "http error 403" in text or "403: forbidden" in text or "fragment 1 not found" in text

The has_403_error/has_pot_error/has_wpc_error handlers combined with multiple retry branches inside download_video form the technical foundation for the skill's 'reliability' claims.

Proxy-aware design (tailored for Mainland China network environments): Reads ambient proxies ALL_PROXY/HTTPS_PROXY/HTTP_PROXY and passes them to yt-dlp, pip, and Docker containers, rewriting localhost proxies to host.docker.internal; pip uses a hardcoded Tsinghua mirror pypi.tuna.tsinghua.edu.cn.

scripts/download_video.py

PYPI_MIRROR = "https://pypi.tuna.tsinghua.edu.cn/simple"

normalize_proxy_for_docker preserves user:password within the proxy URL and injects it into container environment variables—proxy credentials will enter the third-party container process environment.

2Core Capabilities

01YouTube video/playlist downloads with quality presets: best/1080p/720p/480p/360p/worst (merged MP4 output)

02Audio extraction to MP3 and subtitle downloads (-x --audio-format mp3 / --write-subs --write-auto-subs --sub-lang)

03Metadata pre-fetching and verification (--dump-json to parse title/uploader/duration/thumbnail, falling back to YouTube oEmbed on failure)

04Automatic PO Token high-quality unlocking (Docker bgutil prioritized → browser WPC fallback → failure restart retry)

05Browser cookie authenticated downloads (--cookies-from-browser chrome/firefox, web_safari client, log sanitization)

06HLS (m3u8) protected stream download guidance and fallback retry (ffmpeg -headers + -protocol_whitelist guidance; fallback to non-m3u8 progressive formats in script)

07Proxy and mirror adaptation (Mainland China network: plugin installation via Tsinghua PyPI mirror, proxy passthrough/containerized rewriting)

3External Dependencies

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

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Isolated environment, per-use explicit authorization

For Administrators

Strict authorization, full audit, compliance signoff

Evidence & Triggers (File Paths & Excerpts)

本地凭据 / 浏览器配置: Reading user login cookies/sessions/keyrings: Browser cookies: --cookies-from-browser chrome/firefox → yt-dlp reads browser cookie stores (script
scripts/: Executing local scripts or commands: External CLIs: yt-dlp (downloading/metadata/format listing), ffprobe/ffmpeg, docker run/start/rm/info, pip inst
scripts/ 或 SKILL.md: Declares dynamic installation of external language package dependencies
网络端点: Declares external network access: youtube.com: yt-dlp metadata/stream fetching; oEmbed fallback via urlopen https://www.youtube.com/oembed (
本地工作目录: File I/O and artifact output: Download output: recursive mkdir for output_dir + writing video/audio/subtitle files per -o templates (templates support absolute paths and yt-dlp %()s syntax, user configurable

Audit Notes: Investigative opinion, not an official certification. The yellow flag is primarily due to credentials and supply chain risks: (a) Cookie reading pipeline genuinely exists and is a core feature (cookie decryption happens on yt-dlp's side, while the script passes arguments through and sanitizes logs; SKILL mandates asking first—disciplined but not enforced at runtime); (b) Automatically runs pip install for two third-party plugins + pulls and runs a resident third-party brainicism container; container code is outside the audit scope of this repository, and .security-scan-passed only covers gitleaks scanning of static text in this directory; (c) The WPC path launches a real Chrome instance to access YouTube with user login state; (d) Downloading arbitrary user URLs and blindly trusting headers/templates introduces SSRF and arbitrary file write attack surfaces. The script itself does not use shell=True, contains no obfuscation, and has no covert data exfiltration, so it does not reach red; however, green tier criteria are not met, hence yellow.

5Second-Pass Verification

[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 行硬编码

6Verdict & Scenarios

Highly engineered anti-scraping troubleshooting knowledge: common issues like nsig/PO token/403/'Only images'/SSL EOF are codified into error classification and automated retry chains, giving the script strong self-healing capabilities

Two-tier UX design: plain-language workflow for non-technical users + internal SOP for the agent, featuring clear division of responsibilities and consistent discipline (one-to-one mapping between references/internal-sop.md and the SKILL checklist)

Cookie privacy discipline implemented across two layers: SKILL text prohibits exposing raw cookie details + script layer filters log lines

Comprehensive adaptation for China's domestic network (Tsinghua mirror, proxy passthrough, localhost proxy rewriting inside Docker, WPC fallback), making it practically usable for mainland users

oEmbed metadata fallback + pre-download confirmation, preventing downloading the wrong video even under bot-detection scenarios

Best for: Individual users looking for one-click high-quality YouTube/public HLS video downloads via an agent, willing to grant one-time cookie access or install Docker/PO plugins (including Mainland China users behind proxies); or ops/content creators needing to batch-download authorized content in their own controlled environments.

Not for: Zero-trust/supply-chain-sensitive production agent sandboxes (installs third-party plugins, pulls third-party containers, automatically launches browsers); headless environments lacking GUI and Docker (WPC requires a browser window, leaving only the 360p Android client); enterprise environments whose policies prohibit reading browser cookies; direct connections from Mainland China without a proxy (the SKILL's own failure modes depend on a proxy).

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

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 63a65c1fcc.