Video Downloader

Video Downloader

支持从多个视频平台下载视频到本地，基于 yt-dlp + 自研脚本实现。下载前先解析所有可下载档位让用户挑选，自动应用平台特定优化。

> 📘 新用户必读：完整安装 / 权限 / 路径配置见 [SETUP.md](./SETUP.md)。 > 📘 平台细节 / 错误处理速查：见 [references/platform-notes.md](./references/platform-notes.md)。

Step 0：环境自检（首次使用必做）

MISSING=()
for tool in yt-dlp ffmpeg; do
  command -v "$tool" >/dev/null 2>&1 || MISSING+=("$tool")
done
command -v aria2c >/dev/null 2>&1 || echo "ℹ️ aria2c 未装（可选，装了会快 10x）：brew install aria2"

if [[ ${#MISSING[@]} -gt 0 ]]; then
  echo "❌ 缺少必需工具: ${MISSING[*]}"
  echo "   请跑：brew install ${MISSING[*]}"
  exit 1
fi
echo "✅ 必需工具齐全；默认下载目录：$HOME/Downloads"

依赖缺失时引导用户去 [SETUP.md](./SETUP.md)。

核心流程

Step 1：识别下载请求并提取 URL

从用户消息中抽取第一个视频平台 URL。如果有多个 URL，逐个询问或批量处理。

Step 2：识别平台 + 检查依赖

which yt-dlp ffmpeg aria2c 2>&1

平台特定的登录态 / cookies / 特殊脚本逻辑见 [references/platform-notes.md](./references/platform-notes.md)。下面只列出影响交互的关键提示：

• B 站 → 必须提示用户"720P+ 需要登录态"
• 小红书 → 必须确认 URL 含 xsec_token；quality 模式必须提示"4K 需要 Chrome 匿名 session cookie"
• 抖音 / 快手 → download.sh 会自动委派到对应专用脚本，无需 Agent 操心
• 微博 → quality 模式可能下到 300+ MB 大文件，提前告知

Step 3：先探测，把档位给用户挑（必须做）

⚠️ 不要直接下载。必须先调 probe 拿到档位表，让用户自己选。

B 站 / 小红书 probe 前必须先问一句（默认 guest 只能看 480p / 720p）：

> 想要 1080p+ 高清吗？需要读 Chrome 登录态 cookies（首次会弹一次 macOS 钥匙串，点「始终允许」即永久免弹）。(1) 要高清 / (2) 不用，guest 就行

用户选 (1) → 命令前缀加 VDL_USE_CHROME=1；选 (2) 或其他平台 → 直接跑：

bash "/scripts/probe.sh" --human ""
# B 站 / 小红书要高清：
VDL_USE_CHROME=1 bash "/scripts/probe.sh" --human ""

把 probe 输出的档位表直接展示给用户，加一句推荐（兼容优先 = H.264 / 画质优先 = HEVC 或 AV1 / 速度优先 = 最低分辨率），然后问：

> 你想下载哪一档？(回复行号，或输入 quality / compat / speed 用预设规则)。保存位置默认 ~/Downloads，如需修改请告诉我目录。

Step 4：执行下载（按用户选择）

三种下载语法（任选一种）：

# 方式 A：用户挑了 probe 表里的行号（推荐 — 与 probe 强对齐）
bash "/scripts/download.sh" --format  "" [output_dir]

# 方式 B：用户输入了 quality/speed/compat 预设
bash "/scripts/download.sh"  "" [output_dir]

# 方式 C：高级用户直接传 yt-dlp -f 表达式
bash "/scripts/download.sh" --format-arg "" "" [output_dir]

参数：

• `：probe --human` 输出里的行号
• MODE：quality | speed | compat（预设规则，可跳过 probe）
• URL：视频链接
• output_dir：可选，默认 ~/Downloads

download.sh 已内嵌平台委派逻辑——抖音 / 快手会自动走对应的专用脚本。

三档预设语义（不调 probe 的快捷路径）

| 维度 | quality | speed | compat | |------|---------|-------|--------| | 格式选择 -f | bv*+ba/b | bv*[height ℹ️ B 站 / 小红书 quality 模式首次会触发 macOS 钥匙串弹窗（点「始终允许」即可），完整说明见 [SETUP.md`](./SETUP.md)。

Step 5：监控 + 汇报

后台执行 + 每 30s 轮询：

ls -lh ""/*.part 2>/dev/null
ps -p  >/dev/null && echo RUNNING || echo DONE

下载完成用 ffprobe 抓出分辨率 / 编码 / 大小，汇报给用户。

Step 6：兼容性自检（quality 模式）

如果 ffprobe 输出的视频编码是 vp9 / av01 / hevc，必须额外提醒：

> 这个文件是 `` 编码，部分播放器 / 移动端 / 网页可能无法直接播放（例如 macOS QuickTime / Windows 资源管理器缩略图 / Office 插入视频）。建议用现代播放器：macOS = IINA / VLC，Windows = PotPlayer / VLC / MPV，跨平台 = VLC / mpv / IINA。 > > 如果需要任意环境都能直接播放的文件，重选「兼容优先」模式下一遍（1080p H.264 + MP4）。

注意事项

1. 必须先问用户偏好，不要默认替用户选 quality / speed / compat
2. B 站链接必须额外提示登录态
3. 大文件下载用后台执行 + 轮询，不要阻塞对话
4. 下载到 ~/Downloads（除非用户指定）
5. 版权声明：仅协助下载用户有权访问的内容；不绕过付费墙、不下载受 DRM 保护的内容、不破解会员专享内容
6. 进度反馈：每 30–60 秒向用户汇报一次进度，避免长时间静默

支持文件

• references/platform-notes.md —— 各平台要点 + 错误处理速查
• references/format-reference.md —— 各平台编码 / format id / 容器选择速查
• scripts/probe.sh —— 链接解析（不下载），输出元数据 + 档位表
• scripts/download.sh —— 统一下载入口（自动平台识别 + 多线程 + 自动委派抖音 / 快手）
• scripts/_probe_format_ytdlp.py —— yt-dlp -J → 统一 probe JSON
• scripts/_probe_render_human.py —— probe JSON → 人类表格
• scripts/download-douyin.sh —— 抖音专用（绕开 yt-dlp 失效 extractor，走分享页 SSR）
• scripts/download-kuaishou.sh —— 快手专用（yt-dlp 无内置 extractor，走分享页 SSR）

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zyipeng
• Source: zyipeng/video-downloader
• License: MIT

Install and usage instructions live in the source repository linked above.