claude-video 实战教程：如何让 Claude 看懂任意视频

七牛云行业应用

110人浏览 · 2026-07-13 10:30:11

七牛云行业应用 · 2026-07-13 10:30:11 发布

claude-video 是开发者 bradautomates 发布的开源 Agent Skill，2026 年上线后迅速成为 GitHub Trending Python 榜单本周涨星最快的项目（单周新增 7800+ 星），核心能力是让 Claude 具备"观看"视频的能力——通过下载视频、抽取关键帧、生成时间戳转录文本，再把这些素材交给 Claude 逐帧阅读，从而基于画面和音频给出有依据的回答，而不是仅凭标题或残缺字幕去猜测视频内容。项目采用 /watch 命令形式,支持 YouTube、TikTok、Loom、Vimeo 等平台链接及本地视频文件，内置帧预算控制、场景感知抽帧、近重复帧去重和多档画质模式，可在 Claude Code、Codex、Cursor 等 50 多种 Agent 宿主环境中安装使用。目前最新版本为 v0.2.0（2026-07-01 发布），MIT 协议开源，仓库总星数超过 7800。

在这里插入图片描述

claude-video 是什么

claude-video 是一个 Agent Skill（智能体技能包），本质上是一段 Python 脚本 + 一份 SKILL.md 说明文件的组合，作用是补上 AI 编程助手长期缺失的一项能力：直接"看"视频。此前 Claude 处理视频链接时，只能依赖视频标题或不完整的字幕做推测，画面里发生了什么完全是黑盒。claude-video 通过 yt-dlp 下载视频、ffmpeg 抽取帧、字幕或 Whisper 转录音频，把处理后的图片和文字一起交给 Claude 阅读，让它的回答建立在"看到的画面"和"听到的音频"之上。

项目在 GitHub Trending Python（本周榜）上以单周 +4353 星的涨幅排名第一，反映出开发者对"给 AI 一双眼睛看视频"这个需求的真实热度。

核心功能与工作原理

claude-video 的处理流程分六步：

接收视频与问题：支持 URL（YouTube、TikTok、Loom、X、Instagram 等 yt-dlp 支持的数百个站点）或本地路径（.mp4、.mov、.mkv、.webm）
优先读字幕：yt-dlp 先检查视频是否自带字幕，transcript 模式下命中字幕即可直接返回,不需要下载视频本体
按需抽帧：ffmpeg 根据选定的 detail 档位抽取画面帧
生成转录文本：字幕缺失时，脚本会截取音频（单声道 16kHz、64kbps，约 480KB/分钟）送入 Whisper 转录
帧与文本一起喂给 Claude：脚本输出带时间戳的帧文件路径和转录文本，Claude 并行读取每一帧图片
清理：处理完成后自动清理临时工作目录

快速上手：安装与调用

Claude Code 安装（推荐，支持自动更新）：

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

Codex / Cursor / Copilot / Gemini CLI 等 50+ 宿主环境安装：

npx skills add bradautomates/claude-video -g

-g 表示全局安装（安装到用户级目录，如 ~/.codex/skills），跨项目可用；去掉该参数则只安装到当前项目。

首次运行 /watch 时，脚本会自动检测本机是否装有 ffmpeg 和 yt-dlp：macOS 上通过 brew 自动安装，Linux/Windows 会打印对应的 apt/dnf/winget 安装命令。若视频没有现成字幕,还需要配置 Whisper API Key（Groq 或 OpenAI 二选一,配置文件写在 ~/.config/watch/.env）。

基本调用示例：

/watch https://youtu.be/dQw4w9WgXcQ 30秒的地方发生了什么？
/watch ~/Movies/screen-recording.mp4 界面是从哪里开始出问题的？

只看某个时间段（更省 token）：

/watch https://youtu.be/abc --start 2:15 --end 2:45

四种画质档位怎么选

claude-video 提供 --detail 参数控制帧提取的精细度，本质是在速度、token 成本和视觉还原度之间做权衡：

档位	引擎	帧数上限	适用场景
transcript	无（仅字幕）	0	只关心讲了什么，不关心画面细节
efficient	关键帧抽取	50	快速浏览，抽取速度最快（约 0.5 秒）
balanced	场景切换检测	100	兼顾画面覆盖度和 token 成本
token-burner	场景切换检测	不限	需要完整还原每一次画面切换

项目官方给出的实测数据（针对一段 49 分 08 秒的 720p 视频）：efficient 档位抽取仅耗时约 0.5 秒、产出约 9800 image tokens；balanced 耗时约 20.9 秒、产出约 19700 tokens；token-burner 完整保留全部 116 次场景切换，耗时约 21 秒、产出约 22800 tokens。日常排查问题或看长视频摘要，efficient 或 balanced 通常够用；只有需要逐帧还原的场合才需要 token-burner。

帧去重：为什么静态画面不会浪费 token

screen recording 场景中，一张幻灯片可能停留 90 秒，如果每一帧都单独计费,token 消耗会非常离谱。claude-video 默认开启去重逻辑：

用一次 ffmpeg 调用把每帧缩成 16×16 的灰度缩略图
计算当前帧与"上一张被保留的帧"之间的平均像素亮度差异
差异低于阈值（默认 2.0）则判定为近重复帧，直接丢弃

关键细节是比较对象是"上一张被保留的帧"而非"上一帧"，这样才能捕捉到缓慢渐变但逐帧差异很小的画面变化。该逻辑可用 --no-dedup 关闭。

在这里插入图片描述

典型使用场景

拆解爆款视频结构：/watch <视频链接> 开头用了什么钩子 ，分析同行内容的开场手法、节奏设计
从录屏定位 Bug：同事发来一段屏幕录制，/watch bug-repro.mov 哪里出问题了，Claude 直接定位到出错的那一帧并描述现象
长视频快速摘要：/watch <长视频> 总结一下，跳过逐帧看完的时间成本
过滤营销话术：/watch <发布会视频> 真正的新功能是什么，跳过营销话术，把十分钟的"划时代""颠覆性"过滤成几条实质更新

常见问题

claude-video 需要付费吗？
下载和读取自带字幕的视频完全免费，只需要本地装好 yt-dlp 和 ffmpeg。只有当视频没有字幕、需要走 Whisper 转录时才产生调用成本，推荐用 Groq 的 whisper-large-v3（更便宜更快），也支持 OpenAI 的 whisper-1。

支持哪些视频平台？
理论上支持 yt-dlp 支持的全部站点（数百个），常用的有 YouTube、TikTok、Loom、Vimeo、X、Instagram，本地视频文件（.mp4、.mov、.mkv、.webm）同样支持。

长视频会不会消耗特别多 token？
项目内置自动帧预算控制：视频越长，单位时间分配到的帧数越少（比如 30 秒以内视频约给 30 帧，10 分钟以上视频封顶约 100 帧），配合去重逻辑避免在静态画面上浪费预算。如果只关心某个片段，用 --start/--end 聚焦局部时间段是更省 token 的做法。

能不能只要文字不要画面？
可以，--detail transcript 模式完全跳过抽帧，只走字幕/转录文本，是四档画质里成本最低的选项。

参考资料与延伸阅读

claude-video 的完整安装方式、参数说明和实测数据可查阅项目 GitHub 仓库（v0.2.0，MIT 协议）。如果所在环境需要接入国内可直接访问的多模型服务来配合类似的音视频处理流程，可以参考七牛云智能多媒体服务 Dora 的零运维音视频转码与智能识别方案。项目仍在快速迭代中，帧预算算法和画质档位的具体参数可能随版本更新调整，实际使用前建议以仓库最新 README 为准。