runningz1 Yt-dlp
何时不使用:
- 下载普通文件（使用 wget/curl）
- 播放视频（使用 mpv/vlc 等播放器）
- 纯视频转码编辑（直接使用 FFmpeg）
- 简单的 YouTube 下载（已有 GUI 工具如 4K Video Downloader）
本 skill 采用 Router Pattern，SKILL.md 作为导航中心，详细内容分布在：
workflows/- 完整工作流（下载、格式选择、开发）references/- 核心架构、API 文档、最佳实践scripts/- 实用脚本工具templates/- 代码模板和配置示例assets/- 架构图和流程图
yt-dlp-skill/
├── SKILL.md (你在这里)
├── workflows/
│ ├── basic-download.md # 基础下载流程
│ ├── format-selection.md # 格式选择工作流
│ ├── authentication.md # 认证处理流程
│ ├── xhs-download.md # 小红书下载实战案例
│ └── extractor-development.md # 提取器开发指南
├── references/
│ ├── architecture.md # 核心架构说明
│ ├── format-selector.md # 格式选择语法
│ ├── postprocessors.md # 后处理器参考
│ └── extractor-guide.md # 提取器开发指南
├── scripts/
│ ├── batch-download.py # 批量下载脚本
│ ├── format-analyzer.py # 格式分析工具
│ └── cookie-extractor.py # Cookies 提取工具
├── templates/
│ ├── extractor-template.py # 提取器模板
│ ├── config-template.conf # 配置文件模板
│ └── python-api-template.py # Python API 模板
└── assets/
└── architecture-diagram.txt # 架构图
基础下载（30秒）
# 安装
pip install yt-dlp
# 下载视频（最佳质量）
yt-dlp "https://www.youtube.com/watch?v=VIDEO_ID"
# 只下载音频
yt-dlp -x --audio-format mp3 "URL"
# 选择格式
yt-dlp -f "bestvideo[height<=1080]+bestaudio" "URL"
Python API（1分钟）
import yt_dlp
# 下载
ydl_opts = {'outtmpl': '%(title)s.%(ext)s'}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
ydl.download(['VIDEO_URL'])
# 只获取信息
ydl_opts = {'quiet': True}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
info = ydl.extract_info('URL', download=False)
print(info['title'])
使用类工作流
- 基础下载 - 从零开始下载第一个视频
- 格式选择 - 理解和使用强大的格式选择语法
- 认证处理 - 处理登录、cookies、API 密钥
- 小红书下载实战 - 小红书视频完整下载案例（含元数据、封面）
开发类工作流
- 提取器开发 - 为新网站编写提取器
- 后处理器开发 - 扩展后处理功能
- 调试技巧 - 调试和问题排查
推荐路径: 基础下载 → 格式选择 → 认证处理 → 提取器开发
核心概念
- 架构设计 - 提取器系统、下载器、后处理器
- 格式选择器 - 完整的格式选择语法和示例
- 后处理器参考 - 内置后处理器详解
开发指南
- 提取器开发指南 - 编写自定义提取器
- API 参考 - Python API 完整文档
- 最佳实践 - 性能优化和安全建议
故障排查
- 常见问题 - 错误和解决方案
- 已知限制 - 平台特定限制
实用脚本工具（位于 scripts/）：
batch-download.py- 从文件批量下载 URLformat-analyzer.py- 分析视频可用格式cookie-extractor.py- 从浏览器提取 cookiesplaylist-tools.py- 播放列表管理工具
运行 python scripts/<script-name>.py --help 查看详细用法。
提取器 (Extractors)
每个网站有独立的提取器类，继承自 InfoExtractor：
class MySiteIE(InfoExtractor):
_VALID_URL = r'https?://(?:www\.)?mysite\.com/watch/(?P<id>[^/]+)'
def _real_extract(self, url):
# 提取视频信息的逻辑
video_id = self._match_id(url)
webpage = self._download_webpage(url, video_id)
# ... 返回 info_dict
位置：yt_dlp/extractor/*.py
格式选择 (Format Selection)
强大的格式选择语言：
# 基础
-f best # 最佳质量
-f "bestvideo+bestaudio" # 最佳视频+音频
# 过滤
-f "bestvideo[height<=1080]" # 不高于 1080p
-f "mp4" # 只要 MP4
# 排序
-S "res:1080,fmt:mp4,size" # 按分辨率、格式、大小排序
后处理器 (Postprocessors)
链式处理流程：
ydl_opts = {
'format': 'bestvideo+bestaudio',
'outtmpl': '%(title)s.%(ext)s',
'postprocessors': [
{'key': 'FFmpegVideoConvertor', 'preferedformat': 'mp4'},
{'key': 'FFmpegMetadata'},
{'key': 'EmbedThumbnail'},
]
}
问题 1: FFmpeg 相关错误
症状: ffmpeg not found, postprocessor 失败
解决方案:
- Windows: 从 https://ffmpeg.org 下载并添加到 PATH
- Linux:
sudo apt install ffmpeg - macOS:
brew install ffmpeg
问题 2: 格式合并失败
症状: WARNING: Requested formats are incompatible for merge
解决方案:
yt-dlp --merge-output-format mp4 "URL"
# 或
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]" "URL"
问题 3: Geo-restricted 内容
解决方案:
yt-dlp --proxy socks5://127.0.0.1:1080 "URL"
问题 4: 登录后才能访问的内容
解决方案:
yt-dlp --cookies-from-browser chrome "URL"
# 或使用 cookies.txt
yt-dlp --cookies cookies.txt "URL"
问题 5: YouTube 限速
解决方案:
# 使用 aria2 外部下载器
yt-dlp --external-downloader aria2 --external-downloader-args "-x 8 -k 1M" "URL"
# 或限制速率避免被封
yt-dlp --limit-rate 1M "URL"
- 能够下载各类网站的视频/音频
- 理解并使用格式选择语法
- 能够处理字幕、元数据和认证
- 能够导航和理解 yt-dlp 源代码
- 能够解决常见下载问题
- 能够编写简单的自定义提取器
- 能够在 Python 项目中集成 yt-dlp