Claude-video 详细部署教程

1. 项目简介

Claude-video 是一个 Claude Code 插件，通过 /watch 命令让 Claude 获得“观看”视频的能力。它会自动下载视频、提取关键帧、转录音频，然后将帧图像与带时间戳的转录文本一起交给 Claude 进行多模态分析。

核心特性：

多平台支持：支持 YouTube、Loom 以及本地视频文件
字幕优先策略：优先使用视频原生字幕，可避免下载视频和提取帧的开销
场景感知抽帧：通过 FFmpeg 检测场景变化，仅保留视觉内容发生变化的帧
多种详细模式：提供 transcript、efficient、balanced、token-burner 四种帧提取模式
Token 预算管理：根据视频时长自动调整帧数量，避免 Token 消耗失控

技术架构（七步流水线）：

text

视频 URL / 本地路径
    ↓ [1] yt-dlp 检查字幕
    ↓ [2] 有字幕则直接使用，跳过下载
    ↓ [3] 无字幕则下载视频，通过 FFmpeg 提取帧
    ↓ [4] MAD 去重算法，场景变化感知
    ↓ [5] 帧采样，适配 Token 预算
    ↓ [6] Whisper 转录（如无字幕）
    ↓ [7] Claude 分析，清理临时文件

系统要求：

根据官方文档，部署需要满足以下条件：

Python 3.9+
FFmpeg 和 yt-dlp（必需）
Node.js 20+（用于 Agent Skills CLI 安装方式）
Whisper API Key（可选，仅用于无字幕视频）

2. 安装方式

Claude-video 支持多种 AI Agent 宿主环境，安装方式各不相同。

2.1 Claude Code 安装（推荐）

在 Claude Code 中依次执行以下命令：

# 添加插件市场
/plugin marketplace add bradautomates/claude-video

# 安装 watch 插件
/plugin install watch@claude-video

更新插件：

1	/plugin update watch@claude-video

2.2 Codex / Cursor / Copilot / Gemini CLI 安装

这些宿主环境可通过 Agent Skills CLI 统一安装：

1	npx skills add bradautomates/claude-video -g

参数说明：

-g：全局安装（安装到 ~/.codex/skills 或 ~/.cursor/skills 等目录）；去掉此参数则安装到当前项目
-a, --agent <names...>：指定目标宿主，例如 -a codex -a cursor
-l, --list：列出仓库中的技能而不安装
--copy：复制文件而非创建符号链接（适用于不支持符号链接的文件系统）

更新技能：

1	npx skills update watch -g

2.3 claude.ai 网页版安装

从最新 Release 下载 watch.skill 文件
进入 Settings → Capabilities → Skills
点击 + 按钮，将文件拖入

重要：需先在 Capabilities 中启用 “Code execution and file creation”，因为该技能需要调用 ffmpeg 和 yt-dlp。

2.4 手动安装（开发者）

适合需要修改源码或调试的场景：

git clone https://github.com/bradautomates/claude-video.git

# 创建符号链接到宿主的技能目录
ln -s "$(pwd)/claude-video/skills/watch" ~/.claude/skills/watch
# 或者 ~/.codex/skills/watch

符号链接的好处是安装目录与工作树保持同步，修改源码后无需重新安装。

如需为 claude.ai 构建 .skill 捆绑包：

1 2	bash skills/watch/scripts/build-skill.sh # 产物位于 dist/watch.skill

3. 首次运行与依赖配置

3.1 自动依赖检查

首次调用 /watch 时，技能会自动运行 scripts/setup.py --check 进行环境检查。如果缺少 ffmpeg、yt-dlp 或未设置 Whisper API Key，它会引导你完成修复：

macOS：自动运行 brew install ffmpeg yt-dlp
Linux：打印 apt / dnf / pipx 安装命令
Windows：打印 winget / pip 安装命令
API Key：自动创建 ~/.config/watch/.env 文件（权限 0600），包含 GROQ_API_KEY 和 OPENAI_API_KEY 的占位符

3.2 手动安装依赖

如果需要手动安装依赖：

macOS：

1	brew install ffmpeg yt-dlp

Ubuntu / Debian：

1 2	sudo apt install ffmpeg pipx install yt-dlp

Windows：

1 2	winget install Gyan.FFmpeg pip install yt-dlp

3.3 Whisper API Key 配置（可选）

字幕优先策略意味着大多数公开视频无需 Whisper API 即可处理。Whisper 仅在视频完全没有字幕轨道时才会启用（通常适用于本地文件、TikTok、部分 Vimeo 视频等）。

如需配置，编辑 ~/.config/watch/.env：

# 首选：Groq（更快、更便宜）
GROQ_API_KEY=your_groq_api_key

# 备选：OpenAI
OPENAI_API_KEY=your_openai_api_key

4. 使用指南

4.1 基本用法

# 分析 YouTube 视频
/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?

# 分析本地视频
/watch ~/Movies/screen-recording.mp4 when does the UI break?

# 分析 TikTok 视频
/watch https://www.tiktok.com/@user/video/123 summarize this

4.2 详细模式选择

Claude-video 提供四种帧提取模式：

模式	帧预算	说明
`transcript`	0 帧	仅字幕，最省 Token，速度最快
`efficient`	12 帧	速度优先，约 0.5 秒，比场景模式快约 40 倍
`balanced`	32 帧	默认模式，平衡速度与覆盖度
`token-burner`	96 帧	保留所有检测到的场景切换，适合高动态视频

4.3 时间范围限定

指定视频片段可减少 Token 消耗并提高分析精度：

# 只看 2:15 到 2:45 之间的内容
/watch https://youtu.be/abc --start 2:15 --end 2:45

# 从 1 小时 12 分钟开始看到结尾
/watch "$URL" --start 1:12:00

4.4 其他实用参数

参数	说明
`--max-frames N`	手动降低帧数上限，控制 Token 消耗
`--resolution W`	提高帧宽度至 1024px，用于读取屏幕文字、代码等
`--fps F`	覆盖自动 FPS 计算（硬上限仍为 2 fps）
`–whisper groq	openai`
`--no-whisper`	禁用转录，仅返回帧
`--out-dir DIR`	指定工作文件保存目录（默认自动生成临时目录）

5. 运行限制

使用本工具时需注意以下限制：

最佳精度时长：10 分钟以内。超过后脚本会打印“稀疏扫描”警告，建议使用 --start/--end 重新聚焦到关键片段
硬上限：2 fps 和 100 帧。帧数直接影响 Token 成本，脚本会强制执行此限制
Whisper 上传限制：25 MB（约 50 分钟单声道 16kHz 音频）。更长视频需要字幕或限定时间范围
不支持私有平台：需要登录的平台无法直接处理

6. 常见问题与解决方案

6.1 FFmpeg 版本兼容性错误

问题：在 FFmpeg 9.0 上运行时报错 Unrecognized option 'vsync'，帧提取失败。

原因：-vsync 选项在 FFmpeg 5.x 中已弃用，在 FFmpeg 9 中被移除。

解决方案：将 skills/watch/scripts/frames.py 中的 -vsync vfr 替换为 -fps_mode vfr（两处都需要修改）。

6.2 Windows 上 FFmpeg 抽帧失败

问题：即使 ffmpeg -version 检查通过，实际抽帧时仍报错。

解决方案：升级到最新版 FFmpeg。旧版 FFmpeg 虽然能通过版本检查，但实际抽帧时会遇到兼容性问题。

6.3 无字幕视频无法转录

问题：视频没有字幕轨道，且未配置 Whisper API Key。

解决方案：配置 GROQ_API_KEY（首选）或 OPENAI_API_KEY，或者使用 --no-whisper 仅分析画面。

6.4 长视频分析精度不足

问题：超过 10 分钟的视频，短促弹窗或高速操作一闪而过的瞬间可能被跳过。

解决方案：先使用 transcript 模式定位关键时间点，再使用 --start/--end 对特定片段重新提取帧。

7. 部署架构总结

宿主环境	安装方式	命令
Claude Code	插件市场	`/plugin marketplace add bradautomates/claude-video`
Codex / Cursor / Copilot	Agent Skills CLI	`npx skills add bradautomates/claude-video -g`
claude.ai 网页版	手动上传	下载 `watch.skill` 后在设置中导入
开发者	源码 + 符号链接	`git clone` 后创建符号链接

部署完成后，你只需在 AI Agent 中使用 /watch <视频地址> [问题] 即可让 Claude 真正“观看”并分析视频内容。该工具的核心价值在于将视频转化为 Claude 可理解的多模态输入（画面帧 + 带时间戳的转录文本），同时通过字幕优先策略和场景感知抽帧有效控制 Token 成本。