youtube-downloader

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

YouTube Downloader

YouTube 下载工具

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

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

使用PO令牌提供商或浏览器Cookie下载YouTube视频（最高4K分辨率）
下载带认证头的HLS流
处理受保护内容并排查常见下载故障

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.

假设用户为非技术人员，不要要求他们运行命令。自行执行所有操作并使用通俗易懂的语言汇报进度。除非用户询问，否则不要提及工具相关内容。

默认流程：

若未提供URL，向用户索要。
获取视频元数据（标题/上传者/时长/缩略图）并确认是否符合用户需求。
- 若yt-dlp被“确认你不是机器人”拦截，退而使用YouTube oEmbed获取标题/上传者/缩略图（时长可能未知）。
提供简单选项（视频/仅音频、画质、字幕、保存位置）。
若用户未指定，则按合理默认值执行：
- 以最佳画质下载视频
- 合并输出为MP4格式
- 仅下载单个视频（不下载播放列表）
下载完成后，告知用户最终文件路径、文件大小以及分辨率（若为视频）。

以用户友好的方式提供选项：

“以最佳画质下载视频（默认）”
“仅下载音频（MP3格式）”
“选择画质：1080p / 720p / 480p / 360p”
“包含字幕（若有）”
“保存到下载文件夹（默认）还是指定其他文件夹？”

若有缩略图则始终展示：

若元数据包含缩略图URL，使用Markdown图片语法插入：
```
![Thumbnail](URL)
```
。

执行额外操作前需确认：

下载播放列表前需确认（文件可能较大）。
若依赖项缺失，安装/升级前需确认。
提取浏览器Cookie前需确认。
若使用Cookie，在面向用户的回复中绝不要提及Cookie数量或原始Cookie详情，应说“使用你的Chrome登录会话”。
若需要验证，自动设置本地PO令牌助手（无需用户操作）。若Docker缺失或运行失败，不要尝试安装Docker，转而使用基于浏览器的PO令牌提供商。

法律/安全提示（简洁版）：

仅当用户拥有下载内容的权利或许可时才可继续操作。

回复模板（使用通俗易懂的语言，不要命令）：

![Thumbnail](THUMBNAIL_URL)

标题：……
频道：……
时长：……

我可以为你提供以下帮助：
1) 下载视频（最佳画质，MP4格式）
2) 仅下载音频（MP3格式）
3) 选择特定画质（1080p/720p/480p/360p）
4) 包含字幕（若有）

要保存到哪里？（默认：下载文件夹）

若用户说“直接下载”：

按默认值执行，下载完成后确认。
- 若被403错误拦截，自动设置验证助手并重试。

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.

遵循此流程以避免常见故障和混淆：

在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或分片错误，视为代理/网络问题。尝试使用渐进式格式和/或更稳定的代理重试。

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.
If Docker-based provider fails (common in China), automatically fall back to the browser-based WPC provider (it may briefly open a browser window).
If the WPC provider is used, keep the browser window open until download starts. If the browser fails to launch, set the Chrome path explicitly.
If the PO Token provider times out, restart it once and retry.
If a system proxy is configured, pass it into the provider container. If the proxy points to 127.0.0.1/localhost, rewrite it to
```
host.docker.internal
```
for Docker.

运行
```
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，在Docker中重写为
```
host.docker.internal
```
。

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

当用户有以下需求时，应调用此技能：

请求下载YouTube视频或播放列表
希望从YouTube视频中提取音频
遇到yt-dlp下载故障或格式受限问题
需要格式选择或画质选项相关帮助
反馈仅能获取低画质（360p）格式
询问如何以特定画质（1080p、4K等）下载YouTube内容
需要将下载的WebM视频转换为MP4格式以提升兼容性
请求下载来自Mux、Vimeo或其他流媒体服务的HLS流（m3u8）
需要下载需认证头的受保护流

Prerequisites

前置条件

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

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

bash

which yt-dlp
yt-dlp --version

If not installed or outdated (< 2025.10.22):

bash

brew upgrade yt-dlp  # macOS

bash

which yt-dlp
yt-dlp --version

若未安装或版本过旧（<2025.10.22）：

bash

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.

pip install --upgrade yt-dlp # 跨平台


**重要提示**：过时的yt-dlp版本会导致nsig提取失败和格式缺失。

2. Check Current Quality Access (Run this yourself)

2. 检查当前画质访问权限（自行执行）

Before downloading, check available formats:

bash

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

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

下载前，检查可用格式：

bash

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

若仅显示格式18（360p）：需要设置PO令牌提供商以获取高画质访问权限。

High-Quality Download Workflow

高画质下载工作流

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

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

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

bash

undefined

要获取1080p/1440p/4K画质，需在yt-dlp的Python环境中安装PO令牌提供商插件：

bash

undefined

Find yt-dlp's Python path (interpreter used by yt-dlp)

找到yt-dlp的Python路径（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.

<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`。

Step 2: Download with Best Quality

步骤2：以最佳画质下载

Once PO token provider is installed:

bash

undefined

安装PO令牌提供商后：

bash

undefined

Download best quality up to 1080p

下载最高1080p的最佳画质

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

Download best available quality (4K if available)

下载可用的最佳画质（若有则为4K）

yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"

undefined

yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"

undefined

Step 3: Verify Download Quality

步骤3：验证下载画质

bash

undefined

bash

undefined

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

undefined

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

undefined

Alternative: Browser Cookies Method

替代方案：浏览器Cookie方法

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

bash

undefined

若PO令牌提供商设置存在问题，可使用浏览器Cookie：

bash

undefined

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).

yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"


**优势**：可访问年龄限制和会员专属内容。
**要求**：
- 必须在指定浏览器中登录YouTube。
- 浏览器和yt-dlp必须使用相同的IP/代理。
- 不要将Android客户端与Cookie配合使用（Android客户端不支持Cookie）。

Common Tasks

常见任务

Audio-Only Download (Run this yourself)

仅下载音频（自行执行）

Extract audio as MP3:

bash

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

提取音频为MP3格式：

bash

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

Custom Output Directory (Run this yourself)

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

bash

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

bash

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

Download with Subtitles (Run this yourself)

下载带字幕的视频（自行执行）

bash

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

bash

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

Playlist Download (Run this yourself)

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

bash

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

bash

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

Convert WebM to MP4 (Run this yourself)

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

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

bash

undefined

YouTube高画质下载通常使用WebM格式（VP9编码）。转换为MP4格式以提升兼容性：

bash

undefined

Check if ffmpeg is installed

检查ffmpeg是否已安装

which ffmpeg || brew install ffmpeg # macOS

Convert WebM to MP4 with good quality settings

使用优质设置将WebM转换为MP4

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.

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倍。

Troubleshooting Quick Reference

故障排查快速参考

Only 360p Available (Format 18)

仅360p可用（格式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

原因：缺失PO令牌提供商或yt-dlp版本过旧。

解决方案：

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

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.

原因：YouTube要求认证才能继续。

解决方案：

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

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.

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

解决方案：

验证PO令牌提供商在下载前已运行。
若使用WPC，保持浏览器窗口打开。
若使用Cookie，优先选择
```
web_safari
```
客户端并重试。

nsig Extraction Failed

nsig提取失败

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"

症状：

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 / Fragment Errors

SSL EOF / 分片错误

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.

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

解决方案：

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

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

针对中国用户或受限制代理环境：

网络条件可能导致下载缓慢
预留足够的完成时间
yt-dlp会自动重试临时故障

PO Token Warning (Harmless)

PO令牌警告（无害）

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.

WARNING: android client https formats require a GVS PO Token

操作：若下载成功可忽略。此提示表示无PO令牌时Android客户端的格式访问受限。

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:

bash

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)
```
--cookies-from-browser
```
- Load cookies from a browser (e.g., chrome, firefox)
```
--cookies-file
```
- Load cookies from a cookies.txt file
```
--player-client
```
- Use a specific YouTube player client (e.g., web_safari)
```
--auto-po-token
```
- Auto-start PO Token provider (default; uses Docker if available, otherwise switches to browser-based provider)
```
--no-auto-po-token
```
- Disable auto PO Token setup
```
--proxy
```
- Proxy URL for yt-dlp and the PO Token provider (e.g., http://127.0.0.1:1082)
```
--wpc-browser-path
```
- Browser executable path for WPC provider
```
-F, --list-formats
```
- List available formats
```
--merge-format
```
- Merge output container (e.g., mp4, mkv). Default: mp4
```
--playlist
```
- Allow playlist downloads (default: single video only)
```
--info
```
- Print title/uploader/duration/thumbnail and exit
```
--no-android-client
```
- Disable Android client fallback

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

使用此便捷包装器默认自动启动PO令牌提供商以实现高画质下载。自行使用此脚本并向用户汇报结果，无需要求用户运行命令。

基本用法：

bash

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令牌启用。

Quality Expectations

画质预期

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

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

HLS Stream Downloads (m3u8)

HLS流下载（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.

对于Mux、Vimeo等基于HLS的流媒体平台，优先使用ffmpeg。这些流通常需要认证头，yt-dlp可能无法正确处理。

Identifying HLS Streams

识别HLS流

HLS streams use

.m3u8

playlist files:

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

HLS流使用

.m3u8

播放列表文件：

主播放列表：列出多个画质选项
子播放列表：包含实际的视频/音频分片URL

Download Workflow

下载工作流

Step 1: Obtain the Stream URL

步骤1：获取流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")

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

打开浏览器开发者工具 → 网络标签
播放视频
筛选“m3u8”以找到播放列表URL
复制子播放列表URL（通常包含画质信息，例如“rendition.m3u8”）

Step 2: Identify Required Headers

步骤2：识别所需头信息

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.

许多CDN需要认证头：

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

查看网络标签以了解浏览器发送的头信息。

Step 3: Download with ffmpeg

步骤3：使用ffmpeg下载

Use ffmpeg with the

-headers

flag for protected streams:

bash

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:

bash

undefined

对于受保护的流，使用ffmpeg的

-headers

参数：

bash

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音频兼容性

常见头信息格式：

bash

undefined

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...'

undefined

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

undefined

Handling Separate Audio/Video Streams

处理分离的音视频流

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

Download audio stream:

bash

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

Download video stream:

bash

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

Merge streams:

bash

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

部分平台（如Mux）会分开传输音频和视频：

下载音频流：

bash

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

下载视频流：

bash

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

合并流：

bash

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

Troubleshooting HLS Downloads

HLS下载故障排查

403 Forbidden Errors

403禁止访问错误

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

原因：缺失或错误的认证头。

解决方案：

验证Referer头与视频来源网站一致
检查是否需要额外的头信息（Origin、User-Agent）
确保m3u8 URL包含浏览器中的所有查询参数

yt-dlp Stuck on Cookie Extraction

yt-dlp在Cookie提取时卡住

Symptom:

Extracting cookies from chrome

hangs indefinitely.

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

症状：

Extracting cookies from chrome

无限期挂起。

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

Protocol Not Whitelisted

协议未在白名单中

Error:

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

Solution: Add

-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy

错误：

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

解决方案：添加

-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

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

解决方案：

从浏览器开发者工具获取新的URL
获取URL后立即下载
寻找包含更新签名参数的子播放列表URL

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

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

扩展阅读

PO Token Setup: See
```
references/po-token-setup.md
```
for detailed installation and troubleshooting
yt-dlp Documentation: https://github.com/yt-dlp/yt-dlp
Format Selection Guide: https://github.com/yt-dlp/yt-dlp#format-selection

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