Claude Video 中文教程：先用短视频核对字幕和关键帧
Claude Video 的 /watch 会用 yt-dlp 取字幕或下载视频，再由 ffmpeg 抽帧和音频。脚本把带时间戳的字幕与 JPEG 帧交给宿主代理。它不是连续逐帧观看，回答质量取决于字幕、采样范围、帧预算和宿主模型。
1. 选择安装方式
Claude Code 可使用插件市场：
/plugin marketplace add bradautomates/claude-video /plugin install watch@claude-video
Codex、Cursor 等 Agent Skills 宿主可用：
npx skills add bradautomates/claude-video -g
首次运行会检查 Python、ffmpeg 和 yt-dlp。macOS 脚本可能调用 Homebrew 安装缺失依赖；Linux 和 Windows 会打印对应命令。先阅读将执行的安装内容。
2. 不配置 Whisper，先看字幕路径
准备一段自己拥有的 20–30 秒视频，最好同时有对白和画面变化。第一次不要填 Groq 或 OpenAI key，让工具先尝试来源字幕。这样能清楚观察没有字幕时的行为，不会意外把音频交给第三方 API。
/watch ./demo.mp4 总结对白，并列出每个明显的画面变化
检查转录是否带时间戳，抽出的帧是否覆盖开头、关键动作和结尾。回答里没有出现的画面，应回到帧列表判断是采样遗漏还是模型理解错误。
3. 认识四档 detail
transcript 跳过常规帧；efficient 走快速关键帧，最多 50 帧；默认 balanced 做场景检测，最多 100 帧；token-burner 不设场景帧上限。图像 token 往往是主要成本，不熟悉素材时不要直接选最后一档。
4. 长视频先缩小时间窗
/watch https://example.com/video --start 02:10 --end 02:50 解释这段操作 /watch ./meeting.mp4 --timestamps 75,02:30 核对这两个时刻的画面
默认 capped 模式在超过约十分钟时会变成稀疏扫描。已知问题发生在某个区间，就用 start/end；字幕提到“看这里”时，用 timestamps 补取明确时刻，比提高全片帧数更省。
5. 决定是否允许 Whisper 回退
没有字幕时，工具可提取单声道音频并发送给 Groq 的 whisper-large-v3 或 OpenAI whisper-1。v0.2.0 会把超过 25 MB 的音频分块。启用前要确认视频所有者允许转录，并检查所选提供方的数据政策、区域和保留设置。
与 Gemini API 视频理解对比
Google Gemini API 官方支持直接提交视频：静态模式默认按 1 FPS 处理帧和音频，也提供按需浏览长视频的 agentic 模式。Claude Video 在本地用 yt-dlp 与 ffmpeg 预处理，再把选中的帧和字幕交给现有代理。需要托管原生视频输入可评估 Gemini API；需要能检查时间窗、帧文件和字幕来源的本地流程，可评估 Claude Video。
skills/watch/SKILL.md、CHANGELOG 与 v0.2.0 Release；没有安装 skill、ffmpeg 或 yt-dlp，没有下载、解码、转录或读取任何视频。这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
适合谁用
适合分析短演示、定位屏幕录制中的操作、从公开视频字幕与关键帧做摘要，或针对某个时间点提问。涉及受版权保护、私密或含人脸和账号信息的视频时，要先确认下载、转录、第三方 API 上传和保存临时文件的权限。
采用建议
Claude Video 的价值在于把字幕、帧选择和时间戳做成可见的预处理链。首次使用选自有短视频，核对实际帧与字幕后再处理长视频；对私密内容，应先弄清宿主代理和 Whisper 提供方会接收哪些数据。
原教程未展开的系统信息
核心功能
近重复帧过滤
默认把帧缩成 16×16 灰度图，以相邻差异过滤静止画面，节省图像 token。
架构与数据流
自包含的 skills/watch 目录保存 SKILL.md 和 Python 脚本。watch.py 调度 yt-dlp 下载或取字幕，ffmpeg 抽帧与音频，frames.py 处理场景采样和去重，Whisper 客户端做无字幕回退。脚本输出带时间标记的帧路径和转录，宿主代理再读取图像并组织回答。
核验与使用边界
优势与限制
优势
- 字幕与画面一起进入分析，不只依赖标题或转录
- 可按片段、时间点和最大帧数控制成本
- 近重复帧过滤减少静态画面浪费
限制
- 默认 balanced 在超过约 10 分钟的视频上会稀疏扫描
- 无字幕时使用 Whisper 会把音频发送给所选 API 提供方
- 下载视频受来源条款、登录状态、DRM 与版权限制
排错时先核对版本、运行环境和未覆盖范围。这里没有执行过的步骤不会写成实测结论。
常见问题
Claude Video v0.2.0 一定需要 Whisper API key 吗？
不一定。它先尝试用 yt-dlp 获取来源字幕；只有没有可用字幕且需要转录时，才需要 Groq 或 OpenAI 的 key。
分析十分钟以上视频应该选哪个 detail？
默认 balanced 会把最多 100 帧铺到全片，官方会提示稀疏扫描。已知关注片段时先用 start/end；只有接受更高图像 token 成本时才用 token-burner。
为什么静止画面会被 Claude Video 删除？
默认去重会比较缩小后的相邻帧，删除变化很小的画面，把有限帧预算留给不同场景。需要逐帧保留时可关闭去重。
Claude Video 会把本地视频上传到哪里？
帧由本地 ffmpeg 生成并交给宿主代理读取；若没有字幕并启用 Whisper 回退，提取的音频会发送给配置的 Groq 或 OpenAI 服务。具体数据处理还取决于宿主代理。