yt-dlp 视频下载 Skill

基于 yt-dlp 的专业视频下载工具，支持 YouTube、Bilibili、Twitter、Instagram 等 1000+ 网站。

适用场景

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

核心特性

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

使用方式

基础用法

# 直接下载视频（最佳质量）
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"

高级选项

# 选择特定质量
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"

常用输出模板

# 保留原视频标题
-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 辅助工作流

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

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

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

检测步骤:

1. 检测 FFmpeg 是否已安装:

   # macOS/Linux
   ffmpeg -version
   
   # Windows
   ffmpeg -version
   

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

   ✅ FFmpeg 已安装: ffmpeg version N-xxxxx
   

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

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

   • macOS:

     # 使用 Homebrew
     brew install ffmpeg
     
     # 或使用 MacPorts
     sudo port install ffmpeg
     

   • Linux (Ubuntu/Debian):

     sudo apt update
     sudo apt install ffmpeg
     

   • Linux (Arch/Manjaro):

     sudo pacman -S ffmpeg
     

   • Linux (Fedora):

     sudo dnf install ffmpeg
     

   • Windows:

     # 使用 Scoop
     scoop install ffmpeg
     
     # 使用 Chocolatey
     choco install ffmpeg
     
     # 或从官网下载: https://ffmpeg.org/download.html
     

   • 验证安装:

     ffmpeg -version
     

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

AI 应遵守的规则:

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

1. 识别需求

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

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

2. 构建命令

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

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

3. 执行下载

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

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

4. 验证结果

检查下载文件：

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

常用场景命令

YouTube 高清视频

# 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 视频

# 需要 cookie（登录后导出）
yt-dlp --cookies cookies.txt \
  -o "%(title)s.%(ext)s" "URL"

# 下载弹幕（需要专用脚本）
yt-dlp --write-info-json "URL"

播客/音频提取

# 最佳质量 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"

字幕下载

# 下载所有可用字幕
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"

格式选择语法

# 格式选择代码
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

常见网站支持

配置文件

全局配置

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

# 默认输出目录
-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:

# 项目特定配置
-o ./videos/%(title)s.%(ext)s
--cookies cookies.txt
--download-archive downloaded.txt

最佳实践

1. 网络稳定性

# 使用 aria2 作为下载器（支持断点续传）
yt-dlp --external-downloader aria2 \
  --external-downloader-args "-x 8 -k 1M" "URL"

# 重试机制
yt-dlp --retries 10 --fragment-retries 10 "URL"

2. 避免被封

# 限制速度
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. 元数据保留

# 保存所有元数据
yt-dlp --write-info-json --write-description \
  --write-thumbnail --embed-subs "URL"

# 下载为 mkv（支持所有元数据）
yt-dlp --merge-output-format mkv "URL"

4. 批量处理

# 从文件读取 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: 使用以下任一方法：

# 方法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: 常见解决方案：

# 使用 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:

# 从当前开始下载
yt-dlp "URL"

# 从直播开始时下载（需要录制）
yt-dlp --live-from-start "URL"

# 等待直播开始
yt-dlp --wait-for-video "URL"

技术细节

依赖项

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

安装

# 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. 注意事项（可能的错误）

示例：

## 下载 YouTube 视频（1080p）

**命令说明**: 下载 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"

播放列表过滤

# 仅下载前 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"

信息提取

# 仅查看可用格式（不下载）
yt-dlp --list-formats "URL"

# 查看 JSON 信息
yt-dlp --dump-json "URL"

# 查看播放列表信息
yt-dlp --flat-playlist --print "%(title)s" "PLAYLIST_URL"

参考资源

• 官方文档
• 格式选择语法
• 支持网站列表
• Wiki

许可证

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

贡献

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

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