video-download

用途

video-download 用于从 YouTube、TikTok、抖音、Bilibili、Instagram、小红书等 1000 多个平台下载视频，保存为本地 MP4 文件。它自动处理格式选择、平台前缀去重、TikTok cookie 回退，以及抖音/TikTok 的浏览器回退。

主要能力

• 支持单视频下载与批量下载。
• 自动提取带平台前缀的视频 ID，例如 yt-dQw4w9WgXcQ、tk-7571284267028729101、bili-BV1bx4k6zE6D、vid-aHR0cHM6Ly93d3。
• 保存到 resources/references/<video_id>.mp4。
• 若文件已存在则跳过下载（去重）。
• TikTok 下载失败时自动使用 --cookies-from-browser chrome 重试。
• 清理中断下载产生的零字节残留文件。
• 针对抖音/TikTok 提供基于 agent-browser + GreenVideo 的一步式浏览器回退脚本。

使用方式

前置要求：

yt-dlp --version # 必需。安装：brew install yt-dlp（macOS）或 pip install yt-dlp

可选（用于抖音/TikTok 回退）：

• 全局安装 agent-browser（npm install -g agent-browser）
• 安装 Chrome for Testing（agent-browser install）

单视频下载：

bash ${CLAUDE_SKILL_DIR}/scripts/download-video.sh '<URL>'

下载到自定义目录：

bash ${CLAUDE_SKILL_DIR}/scripts/download-video.sh '<URL>' 'path/to/output'

批量下载：

for URL in '<URL1>' '<URL2>' '<URL3>'; do bash ${CLAUDE_SKILL_DIR}/scripts/download-video.sh "$URL" done

脚本输出含义：

• ALREADY_EXISTS: <path>：文件已下载，跳过。
• DOWNLOADED: <path>：下载成功。
• FAILED: <message>：下载失败（退出码 1）。

抖音/TikTok 回退：

当 yt-dlp 对抖音或 TikTok URL 失败时（常见于 403 错误或区域限制内容），使用一步式浏览器回退：

bash ${CLAUDE_SKILL_DIR}/scripts/download-fallback.sh '<douyin-or-tiktok-url>' 'output-dir'

该脚本将完整的 agent-browser + GreenVideo 流程封装为单条命令（打开 → 粘贴 URL → 解析 → 提取视频 URL → 下载 → 关闭）。

手动回退步骤（若回退脚本不可用）：

1. 打开 GreenVideo：

agent-browser open "https://greenvideo.cc/en/"

1. 粘贴 URL 并解析：

agent-browser snapshot agent-browser fill <input-ref> "<video-url>" agent-browser click <start-button-ref>

1. 等待 5 秒后提取视频 URL：

agent-browser eval " (function() { const nuxtData = window.NUXT; if (!nuxtData) return 'ERROR: No Nuxt data found'; const str = JSON.stringify(nuxtData); const mp4Match = str.match(/https?:[^\"]*(?:mp4|video|play|aweme|douyinvod|bilivideo)[^\"]{0,500}/g); if (mp4Match && mp4Match.length > 0) return mp4Match[0]; return 'ERROR: No video URL found in Nuxt state'; })() "

1. 下载并清理：

curl -L -o ~/Downloads/<filename>.mp4 "<extracted-video-url>" agent-browser close

视频 ID 逻辑

• YouTube：watch?v=、shorts/、embed/、youtu.be/ → 11 位 ID，例如 yt-dQw4w9WgXcQ。
• TikTok：URL 中 15 位以上数字 ID，例如 tk-7571284267028729101。
• Bilibili：BV id（av 转换为 BV）；番剧/课程使用 ep/ss id，例如 bili-BV1bx4k6zE6D。
• 其他：URL 的 Base64url 前 16 个字符，例如 vid-aHR0cHM6Ly93d3。

下载后操作

下载成功后，用户可能希望：

• 添加到 Renoise：使用 Renoise 的 upload_files 工具上传，作为生成时的参考。
• 分析：上传后，用 Renoise 的 analyze_media 工具提取脚本、风格或节奏。

下载完成后可向用户建议这些选项。

适用场景

• 需要将多平台视频保存为本地 MP4 文件。
• 需要批量下载视频。
• 需要将视频上传到 Renoise 作为生成参考或进行媒体分析。
• 抖音/TikTok 因 403 或区域限制导致 yt-dlp 失败时，需要浏览器回退方案。

限制

• 依赖 yt-dlp，需预先安装。
• 抖音/TikTok 回退需要 agent-browser 与 Chrome for Testing。
• 视频超过 200M 限制时会被 --max-filesize 跳过，需手动使用 -f 'best[height<=720]' 下载。
• GreenVideo 提取的视频 URL 过期较快，需立即下载。
• 解析失败时需检查 URL 是否有效且可公开访问。

故障排查

• HTTP Error 403（TikTok/抖音）：脚本自动使用 cookies 重试；若仍失败，使用回退脚本。
• --max-filesize skipped：视频超过 200M 限制，手动使用 -f 'best[height<=720]' 下载。
• is not a valid URL：确保 URL 用单引号包裹。
• Requested formats are incompatible：yt-dlp 自动转码，无需操作。
• GreenVideo 解析失败：检查 URL 是否有效且可公开访问。
• Nuxt state 中无视频 URL：尝试点击下载按钮并检查 <video> 元素。
• GreenVideo 下载失败（403）：视频 URL 过期较快，需立即提取并下载。