我们平时排查问题的时候，经常会扔给Agent一段日志让它分析具体原因以及给出具体的修复方案，但是用户反馈一个问题的时候可能并不会提供太多的信息，他们大多只会扔给你一个录制过的视频，然后问你咋回事，我们都知道，在本地的Agent会话里,如果你的电脑里面没有装任何特殊的工具，那么直接粘贴一个视频文件或链接,Agent是看不见的，或者看不全，那么如何才能让Agent学会看视频呢，这里就推荐一个Skill--claude-video.
一、这是什么
claude-video 是一个 Claude Code 的技能(Skill)插件,它的核心价值在于:让Claude能够看到视频内容,并基于视频画面和音频内容回答你的提问,而不是凭空想象。
- Claude Code : 通过
/watch命令直接使用 - 其他宿主: Codex、Cursor、Copilot、Gemini CLI 等 50+ 支持 Skills 的工具均可使用
- claude.ai 网页版 : 通过上传
watch.skill文件启用
仓库地址: github.com/bradautomat...
二、工作原理
当你在 /watch 后跟上视频链接或本地文件,整个流程分为四步:
1. 抓取字幕(优先免费通道)
使用 yt-dlp 检查视频是否自带字幕(原生字幕,YouTube 等平台通常都有,完全免费)。
2. 无字幕则转写(Whisper)
如果视频没有原生字幕,则使用 Whisper 将音频转写成文字,后端支持:
- Groq(推荐,便宜且快)
- OpenAI
如果完全不需要转写,可以用 --no-whisper 关闭。
3. 抽取视频帧(ffmpeg)
使用 ffmpeg 按你选择的详细程度模式 提取关键帧,并默认对近似帧进行去重,避免浪费 token。
4. 交给 Claude 分析
将抽取的画面帧(Claude 会把每一帧作为图片来 Read)+ 带时间戳的字幕 一起交给 Claude,由其综合画面与音频给出答案。因此回答严格基于实际看到和听到的内容,不会凭空捏造。
三、支持的平台与文件
在线视频链接 ------ 支持但不限于:
| 平台 |
|---|
| YouTube |
| TikTok |
| Loom |
| Vimeo |
| X(Twitter) |
......(yt-dlp 支持的所有平台) |
本地文件 ------ 常见视频格式均可:
| 格式 |
|---|
.mp4 |
.mov |
.mkv |
.webm |
四、详细程度模式
通过 --detail 参数控制抽帧密度,四种模式从省 token 到吃 token 依次递增:
| 模式 | 抽帧策略 | 帧数上限 | 说明 |
|---|---|---|---|
transcript |
不抽帧 | 0 | 只基于字幕回答,最省 |
efficient |
关键帧 | ~50 帧 | 快速、省 token |
balanced |
场景切换帧 | 100 帧 | 默认模式,均衡 |
token-burner |
场景切换帧 | 无上限 | 精细分析,token 消耗大 |
帧去重默认开启,会丢弃近似帧;如需保留全部可用
--no-dedup。
五、成本说明
| 环节 | 是否收费 |
|---|---|
抓取字幕(yt-dlp) |
免费 |
| 视频下载 | 免费 |
| Whisper 转写(无字幕时) | 收费,但走 Groq 非常便宜;OpenAI 按官方标准定价 |
省钱技巧:
- 优先选择有原生字幕的视频(大部分 YouTube 视频都有)→ 全程免费
- 只需要文字信息时,用
--detail transcript模式 - 完全不想花钱转写,加
--no-whisper
六、安装方法
安装方式取决于你使用的宿主工具:
方式一:Claude Code
在 Claude Code 会话中依次执行:
bash
/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video方式二:其他宿主(Codex / Cursor / Copilot / Gemini CLI 等)
bash
npx skills add bradautomates/claude-video -g
-g表示全局安装- 如果文件系统不支持软链接,改用
--copy参数
方式三:claude.ai 网页版
- 从仓库最新 Release 页面下载
watch.skill文件 - 进入 Settings → Capabilities → Skills →
+上传 - 确保已开启 "Code execution and file creation" 权限
方式四:手动 / 开发模式
将仓库克隆到本地,然后把 skills/watch 目录软链接到宿主工具的 skills 目录即可:
bash
git clone https://github.com/bradautomates/claude-video.git
# 把 skills/watch 符号链接到你宿主工具的 skills 目录整个安装过程我试下来时间比较长，主要是ffmpeg的brew源不稳定，下载速度比较慢，总共花了大概一个小时
七、前提条件与配置
1. 系统依赖
首次运行 会自动执行 scripts/setup.py --check 来检查并准备依赖:
- macOS : 通过
brew自动安装ffmpeg和yt-dlp - Linux / Windows: 会打印对应的安装命令,按提示手动安装即可
2. API 密钥(仅无字幕视频需要)
所有密钥存放在 ~/.config/watch/.env(权限 0600):
bash
GROQ_API_KEY=你的_groq密钥 # 推荐
# 或
OPENAI_API_KEY=你的_openai密钥只有当视频没有原生字幕需要 Whisper 转写时,才用得到密钥。
八、使用方法
基本语法:
bash
/watch <视频链接|本地文件路径> <你的问题>常见示例
bash
# 问 YouTube 视频第 30 秒发生了什么
/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?
# 分析本地录屏,找 UI 出问题的时刻
/watch ~/Movies/screen-recording.mp4 when does the UI break?
# 只截取指定时间段分析
/watch https://youtu.be/abc --start 2:15 --end 2:45
# 指定抽帧分辨率
/watch video.mp4 --resolution 1024九、常用参数一览
| 参数 | 作用 |
|---|---|
--detail |
详细度模式:transcript / efficient / balanced / token-burner |
--start / --end |
只分析指定时间段 |
--timestamps |
输出带时间戳 |
--max-frames |
限制最大帧数 |
--resolution |
抽帧分辨率 |
--fps |
抽帧频率 |
--whisper groq openai |
指定 Whisper 后端 |
--no-whisper |
禁用语音转写 |
--no-dedup |
关闭帧去重 |
--out-dir |
指定输出目录 |
十、三种抽帧方案横向对比
其实如果只是要完成抽帧这个需求的话，除了claude-video还可以使用其他两种方案，一个是AVFoundation + swiftc，另一个是Python + PyAV，至于如何选择，下面做了一个比较，方便我们针对不同需求场景做选择
| 方案 | 抽帧引擎 | 联网取视频 | 附加能力 |
|---|---|---|---|
| claude-video(ffmpeg + yt-dlp) | ffmpeg(内核 = libav) | yt-dlp(下载/抓字幕,这是它的王牌) | Whisper 转写、转码、剪辑、滤镜等 |
| Python + PyAV | PyAV(同一内核 libav 的 Python 封装) | 不支持 | 易于嵌进代码,可配合 PIL 做图像处理 |
| AVFoundation + swiftc | macOS 系统框架 | 不支持 | 仅限 Apple 生态,精确取单帧 |
关键点:ffmpeg 和 PyAV 是同一个解码内核(libav),抽帧能力天然互斥;yt-dlp 本身不抽帧,它只是"下载器"------但它下载完的本地视频,上面三种引擎都能接着抽帧。所以三者实质是两种抽帧引擎(ffmpeg/PyAV 同一内核 + AVFoundation 独立内核)× 一个下载器(yt-dlp)的组合关系。
再看一下能力
| 能力维度 | AVFoundation + swiftc | Python + PyAV | claude-video(ffmpeg + yt-dlp) |
|---|---|---|---|
| 指定时间点抽帧精度 | 帧级(容差可设 0) | 帧级(需跳到关键帧再解码) | 帧级 |
| 编解码器覆盖 | 最窄(不支持 VP9/AV1/.webm/.mkv) | 全(继承 ffmpeg) | 全 |
| 竖屏视频旋转处理 | 自动 | 需手动补几行代码 | 自动 |
| 批量抽 30~60 帧 | 快 | 快 | 快,且命令行最简短 |
| YouTube / TikTok 链接 → 本地视频 | 不支持 | 不支持 | 支持 |
| 抽帧之外的媒体能力(转码/滤镜/混流) | 弱 | 中(要写代码) | 强 |
| 依赖 / 可移植性 | 仅 macOS + Xcode 命令行工具 | 仅 Python + 预编译 wheel,三平台 | 静态二进制,三平台 |
| 适合角色 | 单机精确取单帧 | 代码里嵌入抽帧 / 无编译环境 | 命令行全能 + 完整"链接→分析"闭环 |
场景怎么选
- 从在线链接(YouTube/TikTok)完整分析一个视频:claude-video 完胜------只有它具备下载环节,另外两种引擎连视频本体都拿不到。
- 只看"抽帧引擎":claude-video = PyAV > AVFoundation。前两者同一内核、编解码最全;AVFoundation 编解码面有明显短板,且锁死 macOS。
- 只求对本地录屏精确取几帧:三者打平,但 AVFoundation 获取成本最高(需编译 + Xcode),杀鸡用牛刀。
- 跨平台、无编译环境、逻辑嵌进代码:PyAV 最优。
- 一把命令行搞定"下载 + 取帧 + 转码 + 滤镜":claude-video 是唯一全能答案。
一句话结论:
论全能(尤其联网取视频)claude-video 最强;论跨平台嵌入 PyAV 最灵活;AVFoundation 只剩"Apple 生态内零额外依赖精确取帧"这一个价值点。
最后
我觉得这个Skill，对于那些已经对自己项目很熟悉的，一看到反馈视频就知道问题根因的人，那么就没必要装，毕竟Agent看视频也是要花token的，但是对于目前这个AI时代，端与端的边界逐渐淡化，每个人多多少少都会接手一些自己不熟悉的项目，会接触一些自己没法快速handle的问题，这种情况，我觉得电脑里面装一个类似于claude-video这样的Skill，还是会起到一些帮助的