yt-dlp

• 下载 YouTube 视频（含 4K/8K、HDR）
• 下载 Bilibili 视频（自动登录）
• 下载社交媒体视频（Twitter、Instagram、TikTok）
• 批量下载播放列表/频道视频
• 提取音频（制作播客、音乐收藏）
• 下载视频字幕（用于翻译、学习）

• 格式智能选择: 自动选择最佳质量（视频+音频或仅视频）
• 字幕处理: 自动下载可用字幕（支持多语言）
• 播放列表支持: 批量下载，支持断点续传
• 元数据保留: 保存标题、上传时间、描述等信息
• 模板化命名: 自定义文件名格式（避免乱码）
• 代理支持: 支持 HTTP/SOCKS 代理
• 速度限制: 可控制下载速度，避免被限流

基础用法

```bash

# 直接下载视频（最佳质量）

yt-dlp "https://www.youtube.com/watch?v=VIDEO_ID"

# 下载到指定目录

yt-dlp -o "Downloads/%(title)s.%(ext)s" "URL"

# 仅下载音频（最佳质量 MP3）

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

# 下载字幕

yt-dlp --write-subs --sub-langs all "URL"

```

高级选项

```bash

# 选择特定质量

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

# 下载播放列表

yt-dlp -o "%(playlist_index)s-%(title)s.%(ext)s" "PLAYLIST_URL"

# 批量下载（从文件读取 URL）

yt-dlp -a urls.txt

# 限制下载速度（避免被封）

yt-dlp --limit-rate 1M "URL"

# 使用代理

yt-dlp --proxy http://127.0.0.1:7890 "URL"

# 下载后不合并（保留分离的视频/音频）

yt-dlp --keep-video "URL"

```

常用输出模板

```bash

# 保留原视频标题

-o "%(title)s.%(ext)s"

# 包含上传者信息

-o "%(uploader)s/%(title)s.%(ext)s"

# 包含上传日期

-o "%(upload_date)s-%(title)s.%(ext)s"

# 播放列表序号

-o "%(playlist_index)s-%(title)s.%(ext)s"

# 完整元数据（用于整理）

-o "%(uploader)s/%(upload_date)s-%(title)s-[%(id)s].%(ext)s"

```

当用户提供视频链接时，AI 应按以下流程处理：

0. 前置检查：FFmpeg 依赖检测

重要: FFmpeg 是 yt-dlp 的必需依赖，必须在执行下载前检测并确保已安装。

检测步骤:

1. 检测 FFmpeg 是否已安装:

```bash

# macOS/Linux

ffmpeg -version

# Windows

ffmpeg -version

```

1. 如果已安装: 显示版本信息，继续执行下一步

```

✅ FFmpeg 已安装: ffmpeg version N-xxxxx

```

1. 如果未安装: 立即停止，提示用户安装

根据操作系统提供安装指令:

- macOS:

```bash

# 使用 Homebrew

brew install ffmpeg

# 或使用 MacPorts

sudo port install ffmpeg

```

- Linux (Ubuntu/Debian):

```bash

sudo apt update

sudo apt install ffmpeg

```

- Linux (Arch/Manjaro):

```bash

sudo pacman -S ffmpeg

```

- Linux (Fedora):

```bash

sudo dnf install ffmpeg

```

- Windows:

```bash

# 使用 Scoop

scoop install ffmpeg

# 使用 Chocolatey

choco install ffmpeg

# 或从官网下载: https://ffmpeg.org/download.html

```

- 验证安装:

```bash

ffmpeg -version

```

1. 安装后验证: 重新执行检测命令，确认成功后才继续

AI 应遵守的规则:

• ❌ 如果 FFmpeg 未安装，绝不执行 yt-dlp 下载命令
• ✅ 必须明确告知用户为什么需要 FFmpeg（视频/音频合并、格式转换）
• ✅ 提供与用户操作系统匹配的安装命令
• ✅ 等待用户确认安装完成后才继续

1. 识别需求

询问用户（如果未明确说明）：

• 是否需要音频还是视频？
• 需要什么质量（1080p/4K/最佳）？
• 是否需要字幕？
• 是否需要元数据（缩略图、描述、info.json）？

2. 构建命令

根据需求自动生成 yt-dlp 命令：

• 自动检测网站类型
• 选择最佳格式选项
• 添加必要的参数
• 输出文件名模板

3. 执行下载

在用户的下载目录执行命令：

• Windows: %USERPROFILE%/Downloads
• macOS: ~/Downloads
• Linux: ~/Downloads

4. 验证结果

检查下载文件：

• 文件完整性
• 格式正确性
• 字幕存在性

YouTube 高清视频

```bash

# 1080p 视频 + 音频

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

-o "%(title)s.%(ext)s" "URL"

# 4K 视频

yt-dlp -f "bestvideo[height<=2160]+bestaudio/best[height<=2160]" \

-o "%(title)s.%(ext)s" "URL"

```

Bilibili 视频

```bash

# 需要 cookie（登录后导出）

yt-dlp --cookies cookies.txt \

-o "%(title)s.%(ext)s" "URL"

# 下载弹幕（需要专用脚本）

yt-dlp --write-info-json "URL"

```

播客/音频提取

```bash

# 最佳质量 MP3

yt-dlp -x --audio-format mp3 \

--audio-quality 0 \

-o "%(title)s.%(ext)s" "URL"

# 批量下载播客列表

yt-dlp -x --audio-format mp3 \

-o "%(playlist_index)s-%(title)s.%(ext)s" \

"PLAYLIST_URL"

```

字幕下载

```bash

# 下载所有可用字幕

yt-dlp --write-subs --sub-langs all \

--skip-download "URL"

# 下载内嵌字幕视频

yt-dlp --embed-subs --sub-langs en,zh "URL"

# 仅字幕（不下载视频）

yt-dlp --write-subs --skip-download "URL"

```

```bash

# 格式选择代码

bestvideo+bestaudio # 最佳视频+音频（分别下载后合并）

best # 最佳单文件（已合并）

worst # 最差质量（用于测试）

# 过滤器

bestvideo[height<=1080] # 最高 1080p

bestvideo[fps<=30] # 最高 30fps

bestvideo[filesize<500M] # 小于 500MB

bestvideo[acodec=opus] # 指定音频编码

# 组合

bestvideo[height<=1080]+bestaudio/best[height<=1080]

# 备选方案（从前到后尝试）

bestvideo+bestaudio/best

```

| 网站 | 支持情况 | 特殊说明 |

|------|---------|---------|

| YouTube | ✅ 完全支持 | 需要代理（某些地区） |

| Bilibili | ✅ 支持 | 需要 cookie |

| Twitter/X | ✅ 支持 | - |

| Instagram | ✅ 支持 | - |

| TikTok | ✅ 支持 | - |

| Vimeo | ✅ 支持 | - |

| Twitch | ✅ 支持 | - |

| Coursera | ✅ 支持 | 需要登录 |

| Netflix | ⚠️ 有限支持 | 需要特定工具 |

全局配置

创建 ~/.config/yt-dlp/config (Linux/macOS) 或 %APPDATA%\yt-dlp\config.txt (Windows):

```ini

# 默认输出目录

-o ~/Downloads/%(title)s.%(ext)s

# 默认格式

-f bestvideo+bestaudio/best

# 下载字幕

--write-subs

--sub-langs en,zh

# 限制并发

--concurrent-fragments 4

# 速度限制

--limit-rate 2M

```

项目级配置

在项目目录创建 yt-dlp.conf:

```ini

# 项目特定配置

-o ./videos/%(title)s.%(ext)s

--cookies cookies.txt

--download-archive downloaded.txt

```

1. 网络稳定性

```bash

# 使用 aria2 作为下载器（支持断点续传）

yt-dlp --external-downloader aria2 \

--external-downloader-args "-x 8 -k 1M" "URL"

# 重试机制

yt-dlp --retries 10 --fragment-retries 10 "URL"

```

2. 避免被封

```bash

# 限制速度

yt-dlp --limit-rate 1M "URL"

# 使用代理池

yt-dlp --proxy socks5://127.0.0.1:1080 "URL"

# 模拟浏览器

yt-dlp --user-agent "Mozilla/5.0..." "URL"

```

3. 元数据保留

```bash

# 保存所有元数据

yt-dlp --write-info-json --write-description \

--write-thumbnail --embed-subs "URL"

# 下载为 mkv（支持所有元数据）

yt-dlp --merge-output-format mkv "URL"

```

4. 批量处理

```bash

# 从文件读取 URL

yt-dlp -a urls.txt -o "%(title)s.%(ext)s"

# 批量下载播放列表（断点续传）

yt-dlp --download-archive archive.txt \

-o "%(title)s.%(ext)s" "PLAYLIST_URL"

```

Q: 下载速度慢？

A: 尝试以下方法：

• 使用 --limit-rate 限制速度
• 使用代理 --proxy
• 切换格式选择（避免需要合并）
• 使用 --concurrent-fragments 增加并发

Q: 视频和音频分离？

A: 使用以下任一方法：

```bash

# 方法1：指定合并格式

yt-dlp -f "bestvideo+bestaudio" --merge-output-format mp4 "URL"

# 方法2：使用 FFmpeg 合并

yt-dlp -f bestvideo+bestaudio --keep-video "URL"

ffmpeg -i video.mp4 -i audio.m4v -c copy output.mp4

```

Q: 如何下载付费/会员内容？

A: 需要 cookie：

1. 使用浏览器插件导出 cookie（如 "Get cookies.txt"）
2. 使用 --cookies cookies.txt 参数
3. 注意：cookie 会过期，需要定期更新

Q: Bilibili 下载失败？

A: 常见解决方案：

```bash

# 使用 cookie

yt-dlp --cookies cookies.txt "URL"

# 使用 CNCore 提取器

yt-dlp --extractor-args "bilivideo:session_data=..." "URL"

# 参考：https://github.com/yt-dlp/yt-dlp/wiki/Installation

```

Q: 如何下载直播？

A:

```bash

# 从当前开始下载

yt-dlp "URL"

# 从直播开始时下载（需要录制）

yt-dlp --live-from-start "URL"

# 等待直播开始

yt-dlp --wait-for-video "URL"

```

依赖项

• FFmpeg: 必需（用于视频/音频合并、格式转换）
• Python 3.8+: 运行环境
• RAR (可选): 用于某些网站的下载

安装

```bash

# pip 安装

pip install yt-dlp

# 包管理器（推荐）

# macOS

brew install yt-dlp

# Linux (Arch)

pacman -S yt-dlp

# Windows (Scoop)

scoop install yt-dlp

# 更新

yt-dlp --update

```

AI 辅助检查清单

在生成下载命令前，确认：

• [ ] 网站是否受支持
• [ ] 是否需要 cookie/代理
• [ ] 用户需要的质量/格式
• [ ] 输出目录和文件名
• [ ] 是否需要字幕
• [ ] 是否需要元数据

AI 输出格式

生成的命令应包含：

1. 命令说明（做什么）
2. 完整命令（可复制粘贴）
3. 参数解释（为什么这样选择）
4. 预期结果（会得到什么文件）
5. 注意事项（可能的错误）

示例：

```markdown

命令说明: 下载 1080p 视频和最佳音频，自动合并为 MP4

完整命令:

```bash

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

-o "%(title)s.%(ext)s" \

"https://www.youtube.com/watch?v=dQw4w9WgXcQ"

```

参数解释:

• -f "bestvideo[height<=1080]+bestaudio": 选择最高 1080p 视频和最佳音频
• -o "%(title)s.%(ext)s": 文件名使用原视频标题
• 自动合并为单个 MP4 文件

预期结果: Downloads/Rick Astley - Never Gonna Give You Up.mp4

注意事项:

• 需要 FFmpeg 已安装
• 下载速度取决于网络和 YouTube 限制
• 如需 4K，将 1080 改为 2160

```

自定义提取器

```bash

# 使用特定提取器

yt-dlp --extractor-args "youtube:player_client=android" "URL"

# 跳过年龄验证

yt-dlp --extractor-args "youtube:player_client=ios" "URL"

```

播放列表过滤

```bash

# 仅下载前 10 个

yt-dlp --playlist-end 10 "PLAYLIST_URL"

# 下载特定范围

yt-dlp --playlist-start 5 --playlist-end 15 "PLAYLIST_URL"

# 反向播放列表

yt-dlp --playlist-reverse "PLAYLIST_URL"

# 随机顺序

yt-dlp --playlist-random "PLAYLIST_URL"

```

信息提取

```bash

# 仅查看可用格式（不下载）

yt-dlp --list-formats "URL"

# 查看 JSON 信息

yt-dlp --dump-json "URL"

# 查看播放列表信息

yt-dlp --flat-playlist --print "%(title)s" "PLAYLIST_URL"

```

• [官方文档](https://github.com/yt-dlp/yt-dlp)
• [格式选择语法](https://github.com/yt-dlp/yt-dlp#format-selection)
• [支持网站列表](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md)
• [Wiki](https://github.com/yt-dlp/yt-dlp/wiki)

MIT License - 自由使用、修改和分发

欢迎提交 Issue 和 Pull Request 改进此 Skill！

---

注意: 请遵守目标网站的服务条款和版权法律。仅下载您有权访问的内容。