Claude视频自动化工具

/watch：让 Claude 真正"看懂"视频

/watch 是为 Claude 系列工具（Claude Code、Codex、Cursor、Copilot、Gemini CLI 等 50 多个 Agent Skills 宿主）打造的插件技能。粘贴一个视频链接或本地路径，Claude 会先取字幕、按需下载片段、抽取帧、并读取音轨文字，最终像真正看过视频一样回答问题。

典型用法

• 分析他人内容：/watch <视频链接> 它用了什么开场钩子？ —— Claude 拆解前几帧画面与开场文案，分析广告、播客、片头等内容的结构。
• 从视频定位 Bug：同事发来一段屏幕录制，/watch bug-repro.mov 哪里出错了？ 能直接定位出问题的帧并描述现象。
• 总结长视频：对长课程或发布会视频给出结构化摘要，免去 2x 速通。
• 剥离营销话术：从产品更新视频里筛出真正新增的功能。
• 把播放列表变笔记：批量生成每集的简短摘要，供后续检索。

工作流程

1. 接收 URL（YouTube、Loom、TikTok、X、Instagram、Vimeo 等数百种来源）或本地 .mp4/.mov/.mkv/.webm。
2. yt-dlp 优先获取原字幕；若字幕缺失或 Whisper 需要音轨，再做最小化下载。
3. ffmpeg 按指定细节档位抽取帧。默认 512 px 宽、最高 1998 px 高，适配 Claude Read。
4. 字幕优先取自原始字幕轨道；缺失时抽取 16 kHz 单声道 mp3 送 Whisper（优先 Groq whisper-large-v3，回退 OpenAI whisper-1）。
5. 将帧路径（带 t=MM:SS 标记）与带时间戳的转写文本交给 Claude，逐帧读取后作答。
6. 任务结束时输出临时目录，用户不追问则自动清理。

帧预算策略

视频时长	默认帧数	说明
≤30 秒	~30 帧	高密度
30 秒 – 1 分	~40 帧	较密
1 – 3 分	~60 帧	适中
3 – 10 分	~80 帧	稀疏但可用
>10 分	100 帧封顶	触发"sparse scan"提示，建议聚焦或切到 token-burner

聚焦模式下，--start / --end 指定的片段会更密集，每秒帧数上限 2 fps，可在不爆上下文的前提下回答"2:30 前后发生了什么"这类问题。

帧去重

帧选择（关键帧 / 场景切换 / 均匀采样）仍可能产出近似帧，例如屏幕录制中保持 90 秒的同一张幻灯片。默认开启 --dedup：

1. 用 ffmpeg 把每帧缩为 16×16 灰度缩略图（无图像库依赖）。
2. 与"上一张被保留的帧"做平均绝对差计算（0–255 灰度）。
3. 差值 ≤ 2.0 视为近似重复并丢弃，否则保留并更新参考帧。
4. 帧预算在去重后生效，确保预算花在"有差异的帧"上。

--no-dedup 可关闭该行为。日志行会以 6 selected from 14 candidates (… 8 near-duplicates dropped …) 形式报告压缩情况。

细节档位实测

针对一段 49:08、1280×720 的 YouTube 录屏：

档位	引擎	帧数	上限	抽取耗时	时间覆盖	估算图像 token
transcript	无（仅字幕）	0	—	~4.5 秒	全文	0（约 26.6k 文本 token）
efficient	关键帧	50	50	~0.5 秒	0:00→49:04	~9.8k
balanced	场景切换	100	100	~20.9 秒	0:00→48:38	~19.7k
token-burner	场景切换（不封顶）	116	无	~21.0 秒	0:00→48:38	~22.8k

• 图像 token 按 Anthropic (宽×高)/750 计算：默认 512px 宽时，720p 帧约 197 token/帧；--resolution 1024 大约 4 倍。
• 所有帧模式共用一条采样规则——先在全时长上枚举候选，再均匀抽样到上限并保证首尾帧被选中；档位差异仅在"候选来源"与"上限"。
• efficient 走关键帧快路径，比场景切换快约 40 倍，但低动态素材中可能比 balanced 帧更多——"高效"指的是抽取速度。
• token-burner 在超过 100 帧上限时才开始与 balanced 分离；高动态视频中可能触发 >250 帧的 token 警告。

安装方式

• Claude Code（推荐，支持 marketplace 自动更新）：

/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video

• Codex、Cursor、Copilot、Gemini CLI 等 50+ 宿主（通过 Agent Skills CLI）：

npx skills add bradautomates/claude-video -g
# -g 全局安装；不带则按项目安装

• claude.ai 网页版：从 Release 下载 watch.skill，进入 Settings → Capabilities → Skills 上传。先在 Capabilities 中开启"Code execution and file creation"。
• 手动/开发模式：git clone 后将 skills/watch 软链到宿主技能的目录。

更新：/plugin update watch@claude-video 或 npx skills update watch -g。

首次运行

首次调用 /watch 时，scripts/setup.py --check 会预检环境：

• 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 占位项。

后续运行是亚 100 ms 静默检查，不会拖慢调用。

密钥与能力

能力	依赖	成本
下载 + 原生字幕	yt-dlp + ffmpeg	免费
Whisper 回退（优先）	Groq whisper-large-v3	便宜、较快
Whisper 回退（备用）	OpenAI whisper-1	标准定价
关闭 Whisper	--no-whisper	免费（无字幕时仅靠帧）

大多数公开视频凭原生字幕就能用，只在本地文件、部分 TikTok/Vimeo、偶发的无字幕 YouTube 上才需 Whisper。

命令行参数

/watch <URL或本地路径> <问题>
/watch https://youtu.be/abc --start 2:15 --end 2:45      # 聚焦区间
/watch "$URL" --start 1:12:00                             # 从 1 小时 12 分到结尾

常用旋钮（传递给 scripts/watch.py）：

• --detail transcript|efficient|balanced|token-burner：保真度/速度档。
• --timestamps T1,T2,…：读取字幕后,针对提示词指定的瞬间抽取帧，--detail transcript 模式下成为唯一帧。
• --max-frames N：收紧帧数上限。
• --resolution W：升到 1024 px 适配幻灯片、终端、代码。
• --fps F：覆盖自动 fps（仍上限 2 fps）。
• --whisper groq|openai：强制指定后端。
• --no-whisper：关闭转写。
• --no-dedup：关闭帧去重。
• --out-dir DIR：自定义工作目录。

限制与默认值

• 长视频精度依赖细节档位：封顶档（efficient / balanced）超过 ~10 分钟会变稀，并打印"sparse scan"提示，建议改用聚焦区间或 token-burner（不封顶，每一帧场景切换都保留）。
• 细节是单一旋钮。默认 balanced：场景感知、上限 100 帧、最多 2 fps。也可在 ~/.config/watch/.env 中设置 WATCH_DETAIL 调整默认值。

仓库结构

```text skills/watch/ # 自包含技能单元，各安装器整体复制 ├── SKILL.md # 跨宿主契约 └── scripts/ ├── watch.py