YouTube视频下载器 - 支持4K高清与HLS流媒体，一键下载视频/音频

youtube-downloader by daymade/claude-code-skills

173 周安装量

775 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/daymade/claude-code-skills --skill youtube-downloader

内容创作自动化文件管理

🇨🇳中文介绍

YouTube 下载器

概述

使用 yt-dlp 和 ffmpeg，实现从 YouTube 和 HLS 流媒体平台（Mux、Vimeo 等）可靠地下载视频和音频。此技能提供以下工作流：

使用 PO 令牌提供程序或浏览器 Cookie 下载 YouTube 视频（最高 4K）
使用身份验证标头下载 HLS 流
处理受保护内容并解决常见的下载失败问题

非技术用户体验（默认）

假设用户是非技术人员。不要要求他们运行命令。自行执行所有操作，并用通俗语言报告进度。除非用户询问，否则避免提及工具。

默认流程：

询问 URL（如果未提供）。
获取视频元数据（标题/上传者/时长/缩略图）并确认其符合用户意图。
- 如果 yt-dlp 被“确认您不是机器人”阻止，则回退到 YouTube oEmbed 获取标题/上传者/缩略图（时长可能未知）。
提供简单的选择（视频与纯音频、质量、字幕、保存位置）。
如果用户未指定，则使用合理的默认值继续：
- 以最佳质量下载视频
- 合并输出为 MP4
- 仅下载单个视频（非播放列表）
下载并报告最终文件路径、文件大小和分辨率（如果是视频）。

以用户友好的术语提供选择：

“以最佳质量下载视频（默认）”
“仅下载音频（MP3）”
“选择质量：1080p / 720p / 480p / 360p”
“包含字幕（如果可用）”
“保存到下载文件夹（默认）或告诉我另一个文件夹”

始终在可用时渲染缩略图：

如果元数据包含缩略图 URL，请使用 Markdown 图片语法包含它：![Thumbnail](URL)。

在进行额外工作前询问：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

可靠下载标准操作程序（内部）

遵循此 SOP 以避免常见失败和混淆：

在 shell 命令中引用 URL（zsh 将 ? 视为通配符）。示例：'https://www.youtube.com/watch?v=VIDEO_ID'。
确保代理对 yt-dlp 和 PO 令牌提供程序都处于活动状态（HTTP_PROXY/HTTPS_PROXY/ALL_PROXY）。
如果看到“登录以确认您不是机器人”，请求许可并使用浏览器 Cookie。没有 Cookie 则不继续。
在下载前启动 PO 令牌提供程序（如果无法启动则快速失败）。
- 可用时使用 Docker bgutil 提供程序。
- 如果 Docker 缺失或失败，切换到基于浏览器的 WPC 提供程序。
如果使用 Cookie，优先使用 web_safari 播放器客户端。否则，对于 PO 令牌，优先使用 mweb。
在 WPC 铸造令牌时保持浏览器窗口打开。确保 Chrome 可以通过相同的代理访问 YouTube。
如果收到“仅图像可用”或“请求的格式不可用”，将其视为 PO 令牌失败，并在修复令牌提供程序/浏览器状态后重试。
如果收到 SSL EOF 或片段错误，将其视为代理/网络问题。使用渐进式格式和/或更好的代理重试。

代理执行清单（内部）

运行 scripts/download_video.py URL --info（如果已授予权限，则添加 --cookies-from-browser chrome）以获取元数据和缩略图。
如果 yt-dlp 元数据失败，则依赖脚本的 oEmbed 回退来获取标题/上传者/缩略图，并注意时长可能不可用。
如果存在缩略图 URL，请在响应中使用 Markdown 图片语法渲染它。
请用户选择视频与纯音频以及（可选）质量预设。
使用友好的默认保存位置（下载文件夹），除非用户指定了文件夹。
对于字幕，使用 --subtitles 和请求的 --sub-lang 运行。
下载后，用通俗语言报告文件名、大小和分辨率（如果是视频）。
如果下载因 403/片段错误而失败，使用非 m3u8 渐进式格式重试一次。
如果出现“登录以确认您不是机器人”，请求 Cookie 访问权限，并使用 Cookie + web_safari 重试。
如果出现“仅图像可用”，将其视为 PO 令牌失败，并在修复提供程序/浏览器状态后重试。
在下载前启动 PO 令牌提供程序（--auto-po-token 默认）。如果无法启动则快速失败。
如果基于 Docker 的提供程序失败（在中国常见），自动回退到基于浏览器的 WPC 提供程序（它可能会短暂打开一个浏览器窗口）。
如果使用 WPC 提供程序，请保持浏览器窗口打开直到下载开始。如果浏览器无法启动，请显式设置 Chrome 路径。
如果 PO 令牌提供程序超时，重启一次并重试。
如果配置了系统代理，请将其传递到提供程序容器中。如果代理指向 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 令牌提供程序以访问高质量。

高质量下载工作流

步骤 1：安装 PO 令牌提供程序（一次性设置）

要访问 1080p/1440p/4K，请将 PO 令牌提供程序插件安装到 yt-dlp 的 Python 环境中：

# 查找 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 令牌提供程序：

# 下载最高 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 令牌提供程序设置有问题，请使用浏览器 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/代理。
不要将 Android 客户端与 Cookie 一起使用（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 令牌提供程序或 yt-dlp 过时。

更新 yt-dlp：brew upgrade yt-dlp
安装 PO 令牌提供程序（见上文步骤 1）
或使用浏览器 Cookie 方法

登录以确认您不是机器人

原因：YouTube 需要身份验证才能继续。

请求许可并使用浏览器 Cookie（--cookies-from-browser chrome）。
确保浏览器和 yt-dlp 使用相同的 IP/代理。
如果需要，使用 web_safari 客户端重试。

仅图像可用 / 请求的格式不可用

原因：未应用 PO 令牌或提供程序/浏览器验证失败。

验证 PO 令牌提供程序在下载前正在运行。
如果使用 WPC，请保持浏览器窗口打开。
如果使用 Cookie，优先使用 web_safari 客户端并重试。

WARNING: [youtube] nsig extraction failed: Some formats may be missing

将 yt-dlp 更新到最新版本
安装 PO 令牌提供程序
如果仍然失败且 PO 令牌被禁用，请使用 Android 客户端：yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"

SSL EOF / 片段错误

原因：代理或网络不稳定。

使用渐进式格式（非 m3u8）重试。
切换到更稳定的代理/节点。
避免在下载期间关闭 PO 令牌浏览器窗口。

下载速度慢或网络错误

对于在中国或使用限制性代理的用户：

由于网络状况，下载可能很慢
允许足够的完成时间
yt-dlp 会在瞬时失败时自动重试

PO 令牌警告（无害）

WARNING: android client https formats require a GVS PO Token

操作：如果下载成功则忽略。这表明 Android 客户端在没有 PO 令牌的情况下格式访问受限。

scripts/download_video.py

使用此便捷包装器，默认自动启动 PO 令牌提供程序以进行高质量下载。自行使用它，并向用户报告结果，而不要求他们运行命令。

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 令牌提供程序（默认；如果可用则使用 Docker，否则切换到基于浏览器的提供程序）
--no-auto-po-token - 禁用自动 PO 令牌设置
--proxy - yt-dlp 和 PO 令牌提供程序的代理 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 令牌被禁用时才使用 Android 客户端。保持 PO 令牌启用以获得高质量。

设置	360p	720p	1080p	1440p	4K
自动 PO 令牌（默认）	✓	✓	✓	✓	✓
仅 Android 客户端	✓	✗	✗	✗	✗
PO 令牌提供程序（手动）	✓	✓	✓	✓	✓
浏览器 Cookie	✓	✓	✓	✓	✓

HLS 流下载（m3u8）

对于像 Mux、Vimeo 和其他基于 HLS 的服务这样的流媒体平台，使用 ffmpeg 作为主要工具。这些流通常需要 yt-dlp 可能无法正确处理的身份验证标头。

HLS 流使用 .m3u8 播放列表文件：

主播放列表：列出多个质量选项
呈现播放列表：包含实际的视频/音频片段 URL

步骤 1：获取流 URL

从视频源获取 m3u8 URL。对于受保护的流：

打开浏览器开发者工具 → 网络标签页
播放视频
过滤“m3u8”以查找播放列表 URL
复制呈现 URL（通常包含质量信息，如“rendition.m3u8”）

步骤 2：识别所需标头

许多 CDN 需要身份验证标头：

Referer：来源网站（例如，https://maven.com/）
Origin：与 Referer 相同，用于 CORS
User-Agent：浏览器标识

检查网络标签页以查看浏览器发送了哪些标头。

步骤 3：使用 ffmpeg 下载

使用带有 -headers 标志的 ffmpeg 处理受保护的流：

ffmpeg -headers "Referer: https://example.com/" \
  -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
  -i "https://cdn.example.com/path/rendition.m3u8?params" \
  -c copy -bsf:a aac_adtstoasc \
  output.mp4

-headers：设置 HTTP 标头（对身份验证至关重要）
-protocol_whitelist：启用 HLS 所需的协议
-c copy：流复制（无需重新编码，更快）
-bsf:a aac_adtstoasc：修复 AAC 音频兼容性

常见标头模式：

# 单个标头
-headers "Referer: https://example.com/"

# 多个标头
-headers "Referer: https://example.com/" \
-headers "User-Agent: Mozilla/5.0..."

# 替代语法
-headers $'Referer: https://example.com/\r\nUser-Agent: Mozilla/5.0...'

处理独立的音频/视频流

某些平台（如 Mux）分别提供音频和视频：

下载音频流：

ffmpeg -headers "Referer: https://example.com/" \

  -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
  -i "https://cdn.example.com/audio/rendition.m3u8" \
  -c copy audio.m4a

2. 下载视频流：

ffmpeg -headers "Referer: https://example.com/" \
  -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
  -i "https://cdn.example.com/video/rendition.m3u8" \
  -c copy video.mp4

ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4

HLS 下载故障排除

原因：缺少或不正确的身份验证标头。

验证 Referer 标头与视频源网站匹配
检查是否需要其他标头（Origin, User-Agent）
确保 m3u8 URL 包含来自浏览器的所有查询参数

yt-dlp 卡在 Cookie 提取

症状：Extracting cookies from chrome 无限期挂起。

解决方案：对于 HLS 流，直接使用 ffmpeg 而不是 yt-dlp。

协议未列入白名单

错误：Protocol 'https' not on whitelist 'file,crypto,data'

解决方案：添加 -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy

原因：m3u8 URL 中的签名已过期。

从浏览器开发者工具获取新的 URL
获取 URL 后立即下载
查找带有更新签名参数的呈现 URL

HLS 下载通常以 10-15 倍实时速度运行
使用 -c copy 无需重新编码（最快）
使用实时进度显示监控下载
使用绝对输出路径以避免目录混淆

PO 令牌设置：有关详细安装和故障排除，请参阅 references/po-token-setup.md
yt-dlp 文档：https://github.com/yt-dlp/yt-dlp
格式选择指南：https://github.com/yt-dlp/yt-dlp#format-selection

2026 年 1 月 21 日

🇺🇸English

YouTube Downloader

Overview

Enable reliable video and audio downloads from YouTube and HLS streaming platforms (Mux, Vimeo, etc.) using yt-dlp and ffmpeg. This skill provides workflows for:

YouTube downloads (up to 4K) using PO token providers or browser cookies
HLS stream downloads with authentication headers
Handling protected content and troubleshooting common download failures

Non-Technical User Experience (Default)

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

Default flow:

Ask for the URL (if not provided).
Fetch video metadata (title/uploader/duration/thumbnail) and confirm it matches the user's intent.
- If yt-dlp is blocked by “confirm you’re not a bot”, fall back to YouTube oEmbed for title/uploader/thumbnail (duration may be unknown).
Offer simple choices (video vs. audio-only, quality, subtitles, save location).
Proceed with sensible defaults if the user does not specify:
- Video download at best quality
- MP4 merged output
- Single video only (no playlists)
Download and report the final file path, file size, and resolution (if video).

Offer choices in user-friendly terms:

“Download the video in best quality (default)”
“Download audio only (MP3)”
“Pick a quality: 1080p / 720p / 480p / 360p”
“Include subtitles (if available)”
“Save to the Downloads folder (default) or tell me another folder”

Always render the thumbnail when available:

If metadata includes a thumbnail URL, include it using Markdown image syntax: ![Thumbnail](URL).

Ask before doing extra work:

Confirm playlist downloads (can be large).
Confirm installing/upgrading dependencies if missing.
Ask before extracting browser cookies.
If using cookies, never mention cookie counts or raw cookie details in user-facing responses. Say “used your Chrome login session”.
If verification is required, automatically set up a local PO Token helper (no user actions). If Docker is missing or fails, do not attempt to install Docker—switch to the browser-based PO Token provider instead.

Legal/Safety reminder (brief):

Proceed only if the user has the rights or permission to download the content.

Response template (use plain language, no commands):

![Thumbnail](THUMBNAIL_URL)

Title: …
Channel: …
Duration: …

I can help you:
1) Download the video (best quality, MP4)
2) Download audio only (MP3)
3) Pick a specific quality (1080p/720p/480p/360p)
4) Include subtitles (if available)

Where should I save it? (Default: Downloads folder)

If the user says “just download”:

Proceed with defaults and confirm when the download finishes.
- If blocked by a 403, automatically set up the verification helper and retry.

Reliable Download SOP (Internal)

Follow this SOP to avoid common failures and confusion:

Quote URLs in shell commands (zsh treats ? as a glob). Example: 'https://www.youtube.com/watch?v=VIDEO_ID'.
Ensure proxy is active for both yt-dlp and PO Token providers (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
If you see “Sign in to confirm you’re not a bot”, request permission and use browser cookies. Do not proceed without cookies.
Start a PO Token provider before downloading (fail fast if it cannot start).
- Use Docker bgutil provider when available.
- If Docker is missing or fails, switch to browser-based WPC provider.
If cookies are in use, prefer the web_safari player client. Otherwise prefer mweb for PO tokens.
Keep the browser window open while WPC is minting tokens. Ensure Chrome can reach YouTube through the same proxy.
If you get “Only images are available” or “Requested format is not available”, treat it as a PO Token failure and retry after fixing token provider/browser state.
If you get SSL EOF or fragment errors, treat it as a proxy/network issue. Retry with progressive formats and/or a better proxy.

Agent Execution Checklist (Internal)

Run scripts/download_video.py URL --info (add --cookies-from-browser chrome if permission granted) to fetch metadata and thumbnail.
If yt-dlp metadata fails, rely on the script’s oEmbed fallback for title/uploader/thumbnail and note that duration may be unavailable.
If a thumbnail URL is present, render it in the response with Markdown image syntax.
Ask the user to choose video vs. audio-only and (optionally) a quality preset.
Use a friendly default save location (Downloads folder) unless the user specifies a folder.
For subtitles, run with --subtitles and the requested --sub-lang.
After download, report file name, size, and resolution (if video) in plain language.
If download fails with 403/fragment errors, retry once with non-m3u8 progressive formats.
If “Sign in to confirm you’re not a bot” appears, request cookie access and retry with cookies + web_safari.
If “Only images are available” appears, treat it as PO Token failure and retry after fixing provider/browser state.
Start the PO Token provider before downloads (--auto-po-token default). Fail fast if it cannot start.

When to Use This Skill

This skill should be invoked when users:

Request downloading YouTube videos or playlists
Want to extract audio from YouTube videos
Experience yt-dlp download failures or limited format availability
Need help with format selection or quality options
Report only low-quality (360p) formats available
Ask about downloading YouTube content in specific quality (1080p, 4K, etc.)
Need to convert downloaded WebM videos to MP4 format for wider compatibility
Request downloading HLS streams (m3u8) from platforms like Mux, Vimeo, or other streaming services
Need to download protected streams that require authentication headers

Prerequisites

1. Verify yt-dlp Installation (Run this yourself)

which yt-dlp
yt-dlp --version

If not installed or outdated (< 2025.10.22):

brew upgrade yt-dlp  # macOS
# or
pip install --upgrade yt-dlp  # Cross-platform

Critical : Outdated yt-dlp versions cause nsig extraction failures and missing formats.

2. Check Current Quality Access (Run this yourself)

Before downloading, check available formats:

yt-dlp -F "https://youtu.be/VIDEO_ID"

If only format 18 (360p) appears : PO token provider setup needed for high-quality access.

High-Quality Download Workflow

Step 1: Install PO Token Provider (One-time Setup)

For 1080p/1440p/4K access, install a PO token provider plugin into yt-dlp's Python environment:

# Find yt-dlp's Python path (interpreter used by yt-dlp)
head -1 $(which yt-dlp)

# Install plugin using the interpreter from the line above
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider

Verification : Run yt-dlp -F "VIDEO_URL" again. Look for formats 137 (1080p), 271 (1440p), or 313 (4K).

See references/po-token-setup.md for detailed setup instructions and troubleshooting.

Step 2: Download with Best Quality

Once PO token provider is installed:

# Download best quality up to 1080p
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"

# Download best available quality (4K if available)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"

Step 3: Verify Download Quality

# Check video resolution
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name -of default=noprint_wrappers=1 video.mp4

Expected output for 1080p:

codec_name=vp9
width=1920
height=1080

Alternative: Browser Cookies Method

If PO token provider setup is problematic, use browser cookies:

# 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"

Benefits : Access to age-restricted and members-only content. Requirements :

Must be logged into YouTube in the specified browser.
Browser and yt-dlp must use the same IP/proxy.
Do not use Android client with cookies (Android client does not support cookies).

Common Tasks

Audio-Only Download (Run this yourself)

Extract audio as MP3:

yt-dlp -x --audio-format mp3 "VIDEO_URL"

Custom Output Directory (Run this yourself)

yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"

Download with Subtitles (Run this yourself)

yt-dlp --write-subs --sub-lang en "VIDEO_URL"

Playlist Download (Run this yourself)

yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"

Convert WebM to MP4 (Run this yourself)

YouTube high-quality downloads often use WebM format (VP9 codec). Convert to MP4 for wider compatibility:

# Check if ffmpeg is installed
which ffmpeg || brew install ffmpeg  # macOS

# Convert WebM to MP4 with good quality settings
ffmpeg -i "video.webm" -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "video.mp4"

Parameters explained:

-c:v libx264: Use H.264 video codec (widely compatible)
-preset medium: Balance between encoding speed and file size
-crf 23: Constant Rate Factor for quality (18-28 range, lower = better quality)
-c:a aac: Use AAC audio codec
-b:a 128k: Audio bitrate 128 kbps

Tip : Conversion maintains 1080p resolution and provides ~6x encoding speed on modern hardware.

Troubleshooting Quick Reference

Only 360p Available (Format 18)

Cause : Missing PO token provider or outdated yt-dlp.

Solution :

Update yt-dlp: brew upgrade yt-dlp
Install PO token provider (see Step 1 above)
Or use browser cookies method

Sign in to Confirm You’re Not a Bot

Cause : YouTube requires authentication to proceed.

Solution :

Request permission and use browser cookies (--cookies-from-browser chrome).
Ensure the browser and yt-dlp use the same IP/proxy.
Retry with web_safari client if needed.

Only Images Available / Requested Format Not Available

Cause : PO tokens not applied or provider/browser verification failed.

Solution :

Verify PO Token provider is running before download.
Keep the browser window open if using WPC.
If cookies are in use, prefer web_safari client and retry.

nsig Extraction Failed

Symptoms :

WARNING: [youtube] nsig extraction failed: Some formats may be missing

Solution :

Update yt-dlp to latest version
Install PO token provider
If still failing and PO tokens are disabled, use Android client: yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"

SSL EOF / Fragment Errors

Cause : Proxy or network instability.

Solution :

Retry with progressive formats (non-m3u8).
Switch to a more stable proxy/node.
Avoid closing the PO token browser window during download.

Slow Downloads or Network Errors

For users in China or behind restrictive proxies:

Downloads may be slow due to network conditions
Allow sufficient time for completion
yt-dlp automatically retries on transient failures

PO Token Warning (Harmless)

WARNING: android client https formats require a GVS PO Token

Action : Ignore if download succeeds. This indicates Android client has limited format access without PO tokens.

Bundled Script Reference

scripts/download_video.py

Use this convenience wrapper to auto-start a PO Token provider by default for high-quality downloads. Use it yourself and report results to the user without asking them to run commands.

Basic usage:

scripts/download_video.py "VIDEO_URL"

Arguments:

url - YouTube video URL (required)
-o, --output-dir - Output directory
--output-template - Output filename template (yt-dlp syntax)
-f, --format - Format specification
-q, --quality - Quality preset (best, 1080p, 720p, 480p, 360p, worst). Default: best (skipped for --audio-only)
-a, --audio-only - Extract audio as MP3
--subtitles - Download subtitles if available
--sub-lang - Subtitle languages (comma-separated, default: en)
- Load cookies from a browser (e.g., chrome, firefox)

Note : Use the Android client only when PO tokens are disabled. Keep PO tokens enabled for high quality.

Quality Expectations

Setup	360p	720p	1080p	1440p	4K
Auto PO token (default)	✓	✓	✓	✓	✓
Android client only	✓	✗	✗	✗	✗
PO token provider (manual)	✓	✓	✓	✓	✓
Browser cookies	✓	✓	✓	✓	✓

HLS Stream Downloads (m3u8)

For streaming platforms like Mux, Vimeo, and other HLS-based services, use ffmpeg as the primary tool. These streams often require authentication headers that yt-dlp may not handle correctly.

Identifying HLS Streams

HLS streams use .m3u8 playlist files:

Master playlist: Lists multiple quality options
Rendition playlist: Contains actual video/audio segment URLs

Download Workflow

Step 1: Obtain the Stream URL

Get the m3u8 URL from the video source. For protected streams:

Open browser DevTools → Network tab
Play the video
Filter for "m3u8" to find the playlist URLs
Copy the rendition URL (usually contains quality info like "rendition.m3u8")

Step 2: Identify Required Headers

Many CDNs require authentication headers:

Referer : Origin website (e.g., https://maven.com/)
Origin : Same as Referer for CORS
User-Agent : Browser identification

Check the Network tab to see which headers the browser sends.

Step 3: Download with ffmpeg

Use ffmpeg with the -headers flag for protected streams:

ffmpeg -headers "Referer: https://example.com/" \
  -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
  -i "https://cdn.example.com/path/rendition.m3u8?params" \
  -c copy -bsf:a aac_adtstoasc \
  output.mp4

Key parameters:

-headers: Set HTTP headers (critical for authentication)
-protocol_whitelist: Enable required protocols for HLS
-c copy: Stream copy (no re-encoding, faster)
-bsf:a aac_adtstoasc: Fix AAC audio compatibility

Common header patterns:

# Single header
-headers "Referer: https://example.com/"

# Multiple headers
-headers "Referer: https://example.com/" \
-headers "User-Agent: Mozilla/5.0..."

# Alternative syntax
-headers $'Referer: https://example.com/\r\nUser-Agent: Mozilla/5.0...'

Handling Separate Audio/Video Streams

Some platforms (like Mux) deliver audio and video separately:

Download audio stream:

ffmpeg -headers "Referer: https://example.com/" \

  -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
  -i "https://cdn.example.com/audio/rendition.m3u8" \
  -c copy audio.m4a

2. Download video stream:

ffmpeg -headers "Referer: https://example.com/" \
  -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
  -i "https://cdn.example.com/video/rendition.m3u8" \
  -c copy video.mp4

3. Merge streams:

ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4

Troubleshooting HLS Downloads

403 Forbidden Errors

Cause : Missing or incorrect authentication headers.

Solution :

Verify Referer header matches the video source website
Check if additional headers (Origin, User-Agent) are needed
Ensure the m3u8 URL includes all query parameters from browser

yt-dlp Stuck on Cookie Extraction

Symptom : Extracting cookies from chrome hangs indefinitely.

Solution : Use ffmpeg directly instead of yt-dlp for HLS streams.

Protocol Not Whitelisted

Error : Protocol 'https' not on whitelist 'file,crypto,data'

Solution : Add -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy

Empty Segments or No Streams

Cause : Expired signatures in the m3u8 URLs.

Solution :

Get fresh URLs from browser DevTools
Download immediately after obtaining URLs
Look for rendition URLs with updated signature parameters

Performance Tips

HLS downloads typically run at 10-15x realtime speed
No re-encoding with -c copy (fastest)
Monitor download with real-time progress display
Use absolute output paths to avoid directory confusion

YouTube视频下载器 - 支持4K高清与HLS流媒体，一键下载视频/音频

🇨🇳中文介绍

YouTube 下载器

概述

非技术用户体验（默认）

相关 Skills

可靠下载标准操作程序（内部）

代理执行清单（内部）

何时使用此技能

先决条件

1. 验证 yt-dlp 安装（自行运行）

2. 检查当前质量访问权限（自行运行）

高质量下载工作流

步骤 1：安装 PO 令牌提供程序（一次性设置）

步骤 2：以最佳质量下载

步骤 3：验证下载质量

替代方案：浏览器 Cookie 方法

常见任务

仅下载音频（自行运行）

自定义输出目录（自行运行）

下载带字幕（自行运行）

播放列表下载（自行运行）

将 WebM 转换为 MP4（自行运行）

故障排除快速参考

仅 360p 可用（格式 18）

登录以确认您不是机器人

仅图像可用 / 请求的格式不可用

nsig 提取失败

SSL EOF / 片段错误

下载速度慢或网络错误

PO 令牌警告（无害）

捆绑脚本参考

scripts/download_video.py

质量预期

HLS 流下载（m3u8）

识别 HLS 流

下载工作流

步骤 1：获取流 URL

步骤 2：识别所需标头

步骤 3：使用 ffmpeg 下载

处理独立的音频/视频流

HLS 下载故障排除

403 禁止错误

yt-dlp 卡在 Cookie 提取

协议未列入白名单

空片段或无流

性能提示

延伸阅读

🇺🇸English

YouTube Downloader

Overview

Non-Technical User Experience (Default)

Reliable Download SOP (Internal)

Agent Execution Checklist (Internal)

When to Use This Skill

Prerequisites

1. Verify yt-dlp Installation (Run this yourself)

2. Check Current Quality Access (Run this yourself)

High-Quality Download Workflow

Step 1: Install PO Token Provider (One-time Setup)

Step 2: Download with Best Quality

Step 3: Verify Download Quality

Alternative: Browser Cookies Method

Common Tasks

Audio-Only Download (Run this yourself)

Custom Output Directory (Run this yourself)

Download with Subtitles (Run this yourself)

Playlist Download (Run this yourself)

Convert WebM to MP4 (Run this yourself)

Troubleshooting Quick Reference

Only 360p Available (Format 18)

Sign in to Confirm You’re Not a Bot

Only Images Available / Requested Format Not Available

nsig Extraction Failed

SSL EOF / Fragment Errors

Slow Downloads or Network Errors

PO Token Warning (Harmless)

Bundled Script Reference

scripts/download_video.py

Quality Expectations