youtube-downloader

YouTube 视频下载器（yt-dlp）

使用 yt-dlp 下载 YouTube 和其他 1000 多个网站上的视频。

描述

一款基于 yt-dlp 的强大视频下载工具，支持 YouTube、Bilibili、Twitter/X、TikTok 和许多其他平台。功能包括格式选择、提取音频、下载字幕、支持播放列表以及保留元数据。

使用时机

用户在以下情况下，请使用此工具：

• 提供 YouTube URL 并希望下载视频
• 提到“download video”“下载视频”或“save video from YouTube”
• 想从视频中提取音频（MP3）
• 需要下载播放列表或频道内容
• 想要视频的字幕/说明文字
• 要求从受支持的网站下载视频（Bilibili、Twitter、TikTok 等）

功能

• 多平台支持：YouTube、Bilibili、Twitter/X、TikTok、Vimeo 以及 1000 多个网站
• 格式选择：选择视频画质（1080p、720p、4K）或仅下载音频
• 提取音频：将音频提取为 MP3、M4A 或其他格式
• 下载字幕：自动下载多种语言的字幕
• 支持播放列表：下载整个播放列表或频道内容
• 保留元数据：保存视频信息、缩略图和描述
• 断点续传：继续未完成的下载
• 进度显示：实时显示下载进度

用法

基本语法

python scripts/download_video.py "VIDEO_URL" [OPTIONS]

常见场景

下载单个视频（最佳画质）：

python scripts/download_video.py "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

下载指定画质的视频：

python scripts/download_video.py "https://www.youtube.com/watch?v=VIDEO_ID" -f 1080

仅提取音频（MP3）：

python scripts/download_video.py "https://www.youtube.com/watch?v=VIDEO_ID" --audio-only

下载字幕：

python scripts/download_video.py "https://www.youtube.com/watch?v=VIDEO_ID" --subtitles

下载播放列表：

python scripts/download_video.py "https://www.youtube.com/playlist?list=PLAYLIST_ID" --playlist

从播放列表下载 N 个视频：

python scripts/download_video.py "https://www.youtube.com/playlist?list=PLAYLIST_ID" --playlist -n 5

指定输出目录：

python scripts/download_video.py "URL" -o /path/to/output

参数

参数	描述	默认值
url	视频/播放列表 URL（必填）	-
-o, --output	输出目录	当前目录
-f, --format	视频画质：best、1080、720、480、360	best
--audio-only	仅提取音频（MP3）	False
--subtitles	下载字幕	False
--sub-lang	字幕语言	en,zh-Hans
--playlist	启用播放列表下载	False
-n, --count	从播放列表下载的视频数量	全部
--metadata	保存视频元数据 JSON	True
--thumbnail	下载缩略图	False
--cookies	Cookie 文件路径（用于有年龄限制的内容）	None

依赖项

# Install yt-dlp
pip install yt-dlp --break-system-packages

# For audio extraction (optional)
# macOS
brew install ffmpeg

# Ubuntu/Debian
apt-get install ffmpeg

输出结构

单个视频

OutputDir/
├── Video Title [VIDEO_ID].mp4     # Video file
├── Video Title [VIDEO_ID].json    # Metadata (if --metadata)
├── Video Title [VIDEO_ID].jpg     # Thumbnail (if --thumbnail)
└── Video Title [VIDEO_ID].en.vtt  # Subtitles (if --subtitles)

播放列表

OutputDir/
└── PlaylistName/
    ├── playlist_info.json
    ├── 001 - Video Title.mp4
    ├── 001 - Video Title.json
    ├── 002 - Another Video.mp4
    └── ...

元数据示例

{
  "title": "Video Title",
  "uploader": "Channel Name",
  "upload_date": "2024-01-15",
  "duration": 300,
  "view_count": 1000000,
  "description": "Video description...",
  "tags": ["tag1", "tag2"],
  "video_file": "Video Title [VIDEO_ID].mp4"
}

Claude 集成

用户请求下载视频时：

1. 阅读工具文档：

   view("/mnt/skills/user/youtube-downloader/SKILL.md")
   

2. 安装依赖项（如有需要）：

   pip install yt-dlp --break-system-packages
   

3. 执行下载：

   python /mnt/skills/user/youtube-downloader/scripts/download_video.py \
     "USER_URL" -o /mnt/user-data/outputs
   

4. 向用户提供文件：

   present_files(["/mnt/user-data/outputs/..."])
   

支持的平台

主要平台

• YouTube：视频、Shorts、播放列表、频道、直播
• Bilibili：视频、剧集（可能需要 Cookie）
• Twitter/X：含视频的推文
• TikTok：视频（可能需要 Cookie）
• Vimeo：视频
• Twitch：点播视频、片段

完整列表

yt-dlp 支持 1000 多个网站。运行 yt-dlp --list-extractors 查看完整列表。

常见问题

问：遇到有年龄限制的视频怎么办？ 答：使用 --cookies 并提供导出的浏览器 Cookie：--cookies cookies.txt

问：所需格式不可用怎么办？ 答：部分视频可能不提供所有画质选项。脚本会自动选择最佳可用画质。

问：下载速度很慢怎么办？ 答：这通常是服务器端限速导致的。可以考虑使用 VPN 或稍后重试。

问：需要登录才能下载私密视频怎么办？ 答：登录后从浏览器导出 Cookie，然后使用 --cookies。

问：提取音频失败怎么办？ 答：安装 ffmpeg：brew install ffmpeg（macOS）或 apt install ffmpeg（Linux）

对话示例

用户：“帮我下载这个 YouTube 视频: https://www.youtube.com/watch?v=dQw4w9WgXcQ”

Claude：

# Install yt-dlp
pip install yt-dlp --break-system-packages

# Download video
python /mnt/skills/user/youtube-downloader/scripts/download_video.py \
  "https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -o /mnt/user-data/outputs

# Present files
present_files([...])

---

用户：“下载这个 YouTube 视频的音频，我只要 MP3”

Claude：

python /mnt/skills/user/youtube-downloader/scripts/download_video.py \
  "VIDEO_URL" \
  --audio-only \
  -o /mnt/user-data/outputs

---

用户：“Download this playlist, but only the first 5 videos”

Claude：

python /mnt/skills/user/youtube-downloader/scripts/download_video.py \
  "PLAYLIST_URL" \
  --playlist -n 5 \
  -o /mnt/user-data/outputs

工作原理

工作流

1. URL 解析：检测平台和内容类型（视频/播放列表）
2. 格式选择：根据用户偏好确定最佳可用格式
3. 下载：流式下载视频/音频，并显示进度
4. 后期处理：提取音频（如有需要），嵌入字幕
5. 元数据：将视频信息保存为 JSON

实现原理

此工具对 yt-dlp 进行了封装，并采用合理的默认设置：

• 自动选择最佳画质的格式
• 规范化文件名
• 下载失败时重试
• 显示进度和预计剩余时间

限制

• 某些网站可能需要身份验证（Cookie）
• 年龄限制内容需要浏览器 Cookie
• 下载速度取决于源服务器
• 某些受 DRM 保护的内容无法下载
• 直播流只能在结束后下载（VOD）

法律声明

此工具仅供个人使用。请遵守：

• YouTube 服务条款
• 所在司法辖区的版权法
• 内容创作者的权利

仅下载您有权访问的内容。请勿重新分发受版权保护的材料。

版本历史

v1.0（当前）

• 首次发布，封装 yt-dlp
• 支持视频、音频、字幕和播放列表
• 保留元数据和缩略图
• 支持多个平台

参考资料

• yt-dlp GitHub
• yt-dlp 文档
• 支持的网站