claude-video-skill 让 Agent 真正看懂视频画面
Agent 拿到视频链接只能读字幕，看不到按钮怎么点、报错在哪秒出现。
- 核心问题：字幕里没有 UI、按钮点击时机、报错瞬间
- 解决方案：yt-dlp 拉字幕 + FFmpeg 抽帧，按时间点对齐
- 三档抽帧：快 50 帧 / 默认 100 帧（按镜头）/ 不限
- 抽帧硬限制：2 fps，>10 分钟视频短促变化会被跳过
- 时间戳定位：指定「2 分钟附近」重抽帧，画面更完整
- 集成方式：ClaudeCode 走插件市场，其余装成 agent skill
- 无字幕兜底：Groq / OpenAI Whisper（要 key）或本地 FunASR SenseVoice（免费离线）
- 当前版本：0.2.0，仅读不写不剪
Agent 看视频的硬伤：只有字幕，没有画面
平时给 Claude Code、Codex 发个视频链接，Agent 通常只能拉到标题和字幕。字幕是文字流——你想从 UI 教程视频里搞清楚「点完这个 按钮后 30 秒发生了什么」，或者从 debug 录屏里找「报错从哪一秒开始」，字幕全帮不上忙。
claude-video 这个 9K 星 开源工具就是解决这事的：把视频拆成「字幕 + 带时间戳的关键帧」，再交回 Agent 分析。
架构：yt-dlp + FFmpeg，字幕和画面按时间点对齐
两条流水线并行：
yt-dlp：负责拉字幕（YouTube 链接或本地视频都支持）FFmpeg：负责抽帧，按镜头变化保留关键画面，过滤长时间不变的重复帧
每张保留下来的图都带时间戳，再和同一时刻的字幕文本对齐——这样 Agent 拿到的是「画面 + 对白」的有时间线的素材，而不是「字幕 + 一堆没标时间的截图」。
三档抽帧模式
| 模式 | 帧数上限 | 适用场景 |
|---|---|---|
| 快速 | 50 帧 | 只想整理字幕，画面要得少 |
| 默认 | 100 帧 | 镜头切换驱动，节奏均匀 |
| 不限 | 无上限 | 操作密集、UI 变化快 |
抽得越密，喂给 Agent 的 token 越多。视频长就直接默认 100 帧；只想看字幕就把模式关掉，省点画面额度。
实战用法
在 Claude Code 里调用：
/watch https://youtube.com/watch?v=xxxx
后面跟具体问题，比如「只看开头 30 秒」「检查 2 分钟附近发生了什么」。
长视频分两步处理：先只读字幕定位关键时间点，再挑一小段重抽帧。这样画面比从头扫到尾完整得多，不会被 2 fps 上限稀释。
按钮、小字、静态页面变化不明显时，可以指定具体时间戳只截一帧——避免被通用抽帧策略漏掉。
三个必须知道的限制
限制 1：抽帧上限 2 fps
超过 10 分钟的视频，默认 100 帧要铺满整段。短促弹窗、高速操作一闪而过的瞬间可能被跳过。解决办法：长视频先按字幕定位，再局部重抽。
限制 2：仅读不写
claude-video 不会生成视频，也不会帮你剪时间线。本地脚本只负责下载、抽帧、整理字幕；分析是 Agent 的事。
限制 3：FFmpeg 版本坑（Windows）
Windows 上旧版 FFmpeg 能通过 ffmpeg -version 检查，但实际抽帧时会报错。换新版 FFmpeg 后同一段视频就能正常处理。
安装方式
| 客户端 | 安装路径 |
|---|---|
| Claude Code | /plugin marketplace add bradautomates/claude-video/plugin install watch@claude-video |
| Codex / Cursor / Copilot / Gemini CLI | npx skills add bradautomates/claude-video -g |
没有字幕的视频可以调 Groq 或 OpenAI Whisper 转写音频。敏感录屏要先确认能不能交给云端模型——客户录屏、内部会议这类内容转写前要过一遍合规。
没字幕、没 API key：本地 FunASR 兜底
Whisper 那条路要求 Groq 或 OpenAI 的 API key，临时没 key 就卡住。比如遇到 B 站视频三个字幕源全空：
bili_subtitle返回「该视频没有字幕」/watch的 yt-dlp 字幕通道也是no subtitles- mmx-cli 没有独立 ASR 命令（
speech synthesize是 TTS，music cover内部隐式 ASR 但不外暴）
最后走的是 Alibaba 的 FunASR + iic/SenseVoiceSmall——CPU 就能跑，模型 ~936MB 一次下载，离线、不烧钱、无需 API key。x86_64 Mac / CPU 实测：4 分 39 秒视频模型加载 + 转录合计约 95 秒（RTF 0.34），输出 1347 字中文原文。
三条路径怎么选
| 场景 | 走哪条 |
|---|---|
| 长期大量转写 | 配 Groq API key（cheaper, faster） |
| 客户录屏 / 内部会议，不能上云 | FunASR SenseVoice（本地推理，零外传） |
| 临时一两段试水 | FunASR 装一次以后零成本 |
两条必须知道的坑
SenseVoiceSmall 是小模型中文 ASR，会有同音字错误。比如「人月神话」被听成「人员神话」、「架构师」变「驾驶员」。写文章前必须回原视频人工核对一遍字幕原文，不要把识别错当视频原话直接搬到正文。
模型名必须用 iic/SenseVoiceSmall，不是 SenseVoiceSmall（404）或 paraformer-zh（触发 SeacoParaformer is not registered 报错）。
具体的依赖装法、踩坑表（numpy<2 必须在 torch 之前、macOS 上 --no-deps funasr、brew reinstall ffmpeg 修 libtiff）和转录脚本，已经写到 bilibili-video skill 的 Step 2.5 里。
References
- 9K星开源工具：让 Claude Code 和 Codex 真正看懂视频 —— AIlazy俊, 2026
- claude-video GitHub 仓库 —— bradautomates, 2026
- FunASR 官方仓库 —— Alibaba DAMO Academy