介绍
# yt-dlp Video Downloader
使用 yt-dlp 从数千个网站下载视频。
## 先决条件
下载前，请验证依赖项是否已安装：
```bash # Check yt-dlp which yt-dlp || echo "yt-dlp not installed. Install with: pip install yt-dlp"
# Check ffmpeg (required for audio extraction and format merging) which ffmpeg || echo "ffmpeg not installed. Install with: brew install ffmpeg" ```
如果未安装，请先安装它们： ```bash pip install yt-dlp brew install ffmpeg # macOS ```
## 快速开始
### 基础下载（最佳画质）
```bash yt-dlp -P "~/Downloads/yt-dlp" "VIDEO_URL" ```
### YouTube 下载（推荐 - 使用 cookies）
YouTube 经常因 403 错误阻止直接下载。务必使用浏览器 cookies 下载 YouTube 视频：
```bash yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "YOUTUBE_URL" ```
支持的浏览器：`chrome`, `firefox`, `safari`, `edge`, `brave`, `opera`
### 自定义输出路径下载
```bash yt-dlp -P "/path/to/save" -o "%(title)s.%(ext)s" "VIDEO_URL" ```
## 常见任务
### 1. 下载视频（默认 - 最佳画质）
```bash yt-dlp -P "~/Downloads/yt-dlp" "VIDEO_URL" ```
### 2. 仅提取音频 (MP3)
```bash yt-dlp -P "~/Downloads/yt-dlp" -x --audio-format mp3 "VIDEO_URL" ```
### 3. 下载字幕
```bash yt-dlp -P "~/Downloads/yt-dlp" --write-subs --sub-langs all "VIDEO_URL" ```
### 4. 下载指定画质
**720p:** ```bash yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo[height<=720]+bestaudio/best[height<=720]" "VIDEO_URL" ```
**1080p:** ```bash yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" "VIDEO_URL" ```
**最佳可用画质:** ```bash yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo+bestaudio/best" "VIDEO_URL" ```
### 5. 列出可用格式（下载前）
```bash yt-dlp -F "VIDEO_URL" ```
然后通过 ID 下载特定格式： ```bash yt-dlp -P "~/Downloads/yt-dlp" -f FORMAT_ID "VIDEO_URL" ```
### 6. 下载播放列表
```bash # Download entire playlist yt-dlp -P "~/Downloads/yt-dlp" -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "PLAYLIST_URL"
# Download specific range (e.g., items 1-5) yt-dlp -P "~/Downloads/yt-dlp" -I 1:5 "PLAYLIST_URL" ```
### 7. 下载缩略图
```bash yt-dlp -P "~/Downloads/yt-dlp" --write-thumbnail "VIDEO_URL" ```
## 工作流程
当用户提供视频 URL 时：
1. **识别平台**： - YouTube/YouTube Music → **务必使用 `--cookies-from-browser chrome`** - 其他网站 → 先尝试不使用 cookies
2. **询问用户需求**（如果未指定）： - 仅下载视频？ - 仅提取音频？ - 需要字幕？ - 指定画质？
3. 根据需求**构建命令**
4. 使用 Shell 工具执行下载，设置 `required_permissions: ["all", "network"]`
5. **处理错误**： - 403 Forbidden → 使用 `--cookies-from-browser` 重试 - 连接问题 → yt-dlp 会自动恢复，直接重试即可 - 格式不可用 → 使用 `-F` 列出格式，然后选择
6. **报告结果** - 文件位置和任何错误
## 示例交互
用户：“帮我下载这个视频 https://www.youtube.com/watch?v=xxx”
回复： ```bash # YouTube - use cookies to avoid 403 errors yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "https://www.youtube.com/watch?v=xxx" ```
用户：“下载这个视频的音频 https://www.bilibili.com/video/xxx”
回复： ```bash # Bilibili - extracting audio as MP3 yt-dlp -P "~/Downloads/yt-dlp" -x --audio-format mp3 "https://www.bilibili.com/video/xxx" ```
用户：“下载这个 Twitter 视频 https://twitter.com/xxx/status/123”
回复： ```bash # Twitter/X - direct download usually works yt-dlp -P "~/Downloads/yt-dlp" "https://twitter.com/xxx/status/123" ```
## 支持的网站
yt-dlp 支持数千个网站，包括： - YouTube, YouTube Music - Bilibili (B站) - Twitter/X - TikTok, Douyin (抖音) - Vimeo - Twitch - 以及更多...
完整列表：https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md
## 故障排除
### 常见错误与解决方案
| 错误 | 原因 | 解决方案 | |-------|-------|----------| | HTTP 403 Forbidden | YouTube 阻止未认证的请求 | 使用 `--cookies-from-browser chrome` | | Video unavailable | 地区限制或私密视频 | 使用 cookies 或 VPN | | Download interrupted | 网络问题 | 重试 - yt-dlp 会自动恢复 | | Format not available | 请求的格式不存在 | 使用 `-F` 列出格式 |
### 错误：“yt-dlp: command not found” ```bash pip install yt-dlp ```
### 错误：“ffmpeg not found”（用于音频提取） ```bash brew install ffmpeg # macOS ```
### 错误：HTTP 403 Forbidden (YouTube)
这是最常见的 YouTube 错误。**YouTube 下载务必使用 cookies：**
```bash # Recommended approach for YouTube yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "YOUTUBE_URL" ```
支持的浏览器：`chrome`, `firefox`, `safari`, `edge`, `brave`, `opera`
### 错误：视频不可用或地区限制 ```bash # Try with cookies from browser yt-dlp --cookies-from-browser chrome "VIDEO_URL"
# Or use a specific format yt-dlp -F "VIDEO_URL" # List formats first yt-dlp -f FORMAT_ID "VIDEO_URL" ```
### 错误：下载持续失败 ```bash # Update yt-dlp to latest version pip install -U yt-dlp
# Force IPv4 (sometimes helps with connection issues) yt-dlp -4 "VIDEO_URL" ```
### 最佳实践
1. **YouTube 下载**：务必使用 `--cookies-from-browser chrome` 2. **大文件**：yt-dlp 会自动恢复，如果中断直接重试即可 3. **保持 yt-dlp 更新**：`pip install -U yt-dlp` 4. **先检查格式**：如果不确定，下载前使用 `-F`