yt-dlp-downloader

name	yt-dlp-downloader
description	Download videos/audio from YouTube, Bilibili, and 1000+ sites using yt-dlp. Always ask preferences before downloading.

yt-dlp Video Downloader

Download videos/audio from YouTube, Bilibili, Twitter, TikTok, and 1000+ platforms using yt-dlp.

MANDATORY WORKFLOW (每次必问)

当用户提供视频链接时，必须先问以下问题再执行下载：

1. 下载模式 (必问)

• 视频 - 下载视频+音频（合并）
• 音频 - 仅提取音频
• 都下载 - 下载视频并同时提取音频（保留视频）

2. 质量选择 (必问)

• 最佳 - 不限制（可能很大）
• 1080p - 1080p或更低（默认推荐）
• 720p - 720p或更低
• 480p - 480p或更低

3. 格式选择 (必问)

• 视频容器：mp4（默认）/ mkv / webm
• 音频格式：mp3（默认）/ m4a

4. 保存路径 (必问)

• 默认：/Users/wsxwj/Downloads/video-download
• 桌面：/Users/wsxwj/Desktop
• 自定义：用户指定的完整路径

5. 播放速度 (可选)

• 原速 (默认)
• 倍速 (如 1.25x, 1.5x, 2.0x) - 注意：需要重新编码，处理时间较长

6. 可选项 (根据需要问)

• 要文字内容/转录？→ 先探字幕(见「字幕下载」)：--list-subs 有原生/自动字幕就直接下并转 srt,别急着下音频做 ASR
• 播放列表处理？（全部/指定范围/单个视频）
• 需要登录？（B站高清/私密视频）

默认值总结

• 模式：视频
• 质量：1080p封顶
• 视频容器：mp4
• 音频格式：mp3
• 播放速度：原速 (1.0x)
• 输出目录：/Users/wsxwj/Downloads/video-download
• 文件名：%(title)s [%(id)s].%(ext)s（保留中文）

命令构建模板

质量映射

# 最佳质量（不限制）
-f "bestvideo+bestaudio/best"

# 1080p封顶（默认推荐）
-f "bestvideo[height<=1080]+bestaudio/best[height<=1080]/best"

# 720p封顶
-f "bestvideo[height<=720]+bestaudio/best[height<=720]/best"

# 480p封顶
-f "bestvideo[height<=480]+bestaudio/best[height<=480]/best"

模式 1: 视频（合并）

mkdir -p "OUTPUT_DIR"
yt-dlp \
  QUALITY_FORMAT \
  --merge-output-format mp4 \
  -P "OUTPUT_DIR" \
  -o "%(title)s [%(id)s].%(ext)s" \
  "VIDEO_URL"

实际示例（默认1080p + mp4 + 默认目录）：

mkdir -p "/Users/wsxwj/Downloads/video-download"
yt-dlp \
  -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]/best" \
  --merge-output-format mp4 \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(title)s [%(id)s].%(ext)s" \
  "https://www.bilibili.com/video/BV1SC6TBqEF9/"

模式 2: 音频（仅提取）

mkdir -p "OUTPUT_DIR"
yt-dlp \
  -x --audio-format mp3 --audio-quality 0 \
  -P "OUTPUT_DIR" \
  -o "%(title)s [%(id)s].%(ext)s" \
  "VIDEO_URL"

实际示例（mp3 + 默认目录）：

mkdir -p "/Users/wsxwj/Downloads/video-download"
yt-dlp \
  -x --audio-format mp3 --audio-quality 0 \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(title)s [%(id)s].%(ext)s" \
  "https://www.bilibili.com/video/BV1SC6TBqEF9/"

模式 3: 都下载（视频+音频）

mkdir -p "OUTPUT_DIR"
yt-dlp \
  QUALITY_FORMAT \
  --merge-output-format mp4 \
  -x --audio-format mp3 --audio-quality 0 \
  --keep-video \
  -P "OUTPUT_DIR" \
  -o "%(title)s [%(id)s].%(ext)s" \
  "VIDEO_URL"

实际示例：

mkdir -p "/Users/wsxwj/Downloads/video-download"
yt-dlp \
  -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]/best" \
  --merge-output-format mp4 \
  -x --audio-format mp3 --audio-quality 0 \
  --keep-video \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(title)s [%(id)s].%(ext)s" \
  "https://www.bilibili.com/video/BV1SC6TBqEF9/"

倍速下载 (特殊功能)

若用户选择倍速（例如 1.25x），需要添加 --postprocessor-args 参数调用 ffmpeg 进行转码。

公式：

• 视频滤镜：setpts=1/SPEED*PTS
• 音频滤镜：atempo=SPEED

1.25x 倍速示例：

yt-dlp \
  -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]/best" \
  --merge-output-format mp4 \
  --postprocessor-args "ffmpeg:-filter:v setpts=0.8*PTS -filter:a atempo=1.25" \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(title)s_1.25x [%(id)s].%(ext)s" \
  "VIDEO_URL"

2.0x 倍速示例：

yt-dlp \
  -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]/best" \
  --merge-output-format mp4 \
  --postprocessor-args "ffmpeg:-filter:v setpts=0.5*PTS -filter:a atempo=2.0" \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(title)s_2.0x [%(id)s].%(ext)s" \
  "VIDEO_URL"

注意：倍速处理需要重新编码整个视频，下载完成后会占用大量 CPU 资源进行转换，耗时较长。建议告知用户。

批量下载

从文本文件批量下载

创建 urls.txt（一行一个URL）：

cat > urls.txt << 'EOF'
https://www.youtube.com/watch?v=VIDEO1
https://www.bilibili.com/video/BV1xxx
https://www.youtube.com/watch?v=VIDEO2
EOF

# 批量下载
yt-dlp \
  -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]/best" \
  --merge-output-format mp4 \
  -a urls.txt \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(title)s [%(id)s].%(ext)s"

跳过已下载的视频

yt-dlp \
  --download-archive downloaded.txt \
  -a urls.txt \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(title)s [%(id)s].%(ext)s"

直接多个URL

yt-dlp \
  -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]/best" \
  --merge-output-format mp4 \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(title)s [%(id)s].%(ext)s" \
  "URL1" "URL2" "URL3"

播放列表下载

整个播放列表

yt-dlp \
  -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]/best" \
  --merge-output-format mp4 \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(playlist)s/%(playlist_index)s - %(title)s [%(id)s].%(ext)s" \
  "PLAYLIST_URL"

播放列表范围

# 前10个视频
yt-dlp --playlist-end 10 "PLAYLIST_URL"

# 第5到第15个
yt-dlp --playlist-start 5 --playlist-end 15 "PLAYLIST_URL"

字幕下载

需要文字内容时优先走字幕：字幕又快又准、省算力，扒不到再交给 ASR（本技能不做 ASR，转录见 social-clip）。先探测有无字幕，再决定下字幕还是回退：

# 先探测：列出该视频有哪些字幕轨（不下视频）
yt-dlp --list-subs --skip-download "VIDEO_URL"
#   "Available subtitles"          = 作者上传的原生字幕（首选）
#   "Available automatic captions" = 平台自动生成字幕（次选，中文常有错）
# 两块都空 → 无字幕，需转录的走 ASR（见 social-clip 技能）

# 有字幕 → 只下字幕转 srt（原生+自动都拿，不下视频）
yt-dlp \
  --skip-download --write-subs --write-auto-subs --sub-langs "zh-Hans,zh,en" \
  --convert-subs srt \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(title)s [%(id)s].%(ext)s" \
  "VIDEO_URL"

# 自动生成字幕（中文优先，然后英文）
yt-dlp \
  --write-auto-sub --sub-langs "zh-Hans,zh,en" \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(title)s [%(id)s].%(ext)s" \
  "VIDEO_URL"

# 嵌入字幕到视频
yt-dlp \
  --write-sub --embed-subs --sub-langs "zh-Hans,zh,en" \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(title)s [%(id)s].%(ext)s" \
  "VIDEO_URL"

B站特殊处理

需要登录获取高清

# 从Chrome导入cookies
yt-dlp --cookies-from-browser chrome "BILIBILI_URL"

# 或指定cookies文件
yt-dlp --cookies cookies.txt "BILIBILI_URL"

查看可用格式

yt-dlp -F "VIDEO_URL"

故障排除

问题1: "No video formats found"

# 尝试best格式
yt-dlp -f best "VIDEO_URL"

# 或列出所有可用格式
yt-dlp -F "VIDEO_URL"

问题2: 下载慢或失败

# 限速避免封禁
yt-dlp --limit-rate 1M "VIDEO_URL"

# 使用代理
yt-dlp --proxy "http://proxy.example.com:8080" "VIDEO_URL"

问题3: 文件名过长或特殊字符

# 启用Windows文件名兼容
yt-dlp --windows-filenames "VIDEO_URL"

# 或限制文件名长度
yt-dlp --trim-filenames 100 "VIDEO_URL"

验证输出路径（不下载）

在真正下载前，验证输出路径是否正确：

yt-dlp \
  --simulate --get-filename \
  -P "/Users/wsxwj/Downloads/video-download" \
  -o "%(title)s [%(id)s].%(ext)s" \
  "VIDEO_URL"

这会打印出最终文件路径，但不会真正下载。

输出模板变量

• %(title)s - 视频标题
• %(id)s - 视频ID
• %(ext)s - 文件扩展名
• %(uploader)s - 上传者
• %(upload_date)s - 上传日期 (YYYYMMDD)
• %(playlist)s - 播放列表名称
• %(playlist_index)s - 在播放列表中的位置

安装/更新 yt-dlp

# 检查是否安装
which yt-dlp && yt-dlp --version

# 安装（macOS/Linux）
pip install yt-dlp

# 或使用brew（macOS）
brew install yt-dlp

# 更新到最新版
pip install -U yt-dlp

支持的平台

• 视频: YouTube, Vimeo, Dailymotion, Twitch
• 社交: Twitter/X, TikTok, Instagram, Facebook
• 中国: Bilibili, Youku, iQiyi, Douyin
• 直播: Twitch Live, YouTube Live, Bilibili Live
• 教育: Coursera, Udemy, Khan Academy
• 1000+ 其他平台

查看所有支持的网站：

yt-dlp --list-extractors

重要提示

• 尊重版权和服务条款
• 某些平台可能限制自动下载
• 大文件下载前检查磁盘空间
• 批量下载建议先测试少量URL
• 使用 --download-archive 避免重复下载