Claude 能读网页、能跑脚本、能翻仓库，但有一件事它开箱做不到——看视频。你贴个 YouTube 链接，它要么靠标题猜内容，要么拉一份字幕，而字幕漏掉了画面上 90% 的信息。claude-video 这个项目就是来补这一刀的：一条 /watch 命令，把下载、抽帧、转写全打包，最后把每一帧当图片喂给 Claude，让它真正"看见"画面。
一、它是什么
claude-video（github.com/bradautomates/claude-video）是一个开源的 Agent Skill，GitHub 星 14204（截至 2026-08-06，实时变动），fork 1363，主语言 Python，MIT 许可证，2026 年 4 月 24 日创建，最近一次 push 2026 年 7 月 1 日。本周位列 GitHub 周榜第 20，周增长 3359 星。官方一句话定位：Give Claude the ability to watch any video——/watch 负责下载视频、抽取帧、转写音频，再把这一切交给 Claude。
它的形态不是独立 App，而是一个 Skill：在 Claude Code 里是插件，在 Codex/Cursor/Copilot/Gemini CLI 等 50 多个 Agent Skills host 里是全局技能。底层依赖 yt-dlp（下载 + 抓原生字幕）、ffmpeg（抽帧）、可选的 Whisper（无字幕时转写），作者 Brad Bonanno 把这套链路封进一个自包含的 skills/watch/ 目录，装一次就能跨 host 用。
二、解决什么痛点
核心痛点就一句：Claude 原生不能直接看视频。
你给 Claude 一个 YouTube 链接，它没法"看"。最好的情况是视频有字幕，Claude 拉一份 transcript 来读——但字幕只记录了"说出来的话"，画面里出现的 UI、代码、图表、PPT、操作演示、表情，全丢了。README 里说得很直白：transcript "missing 90% of what's on screen"。
这导致几个真实场景卡住：
- 分析别人的内容结构。想拆解一个爆款视频的开场 hook、节奏、转场，只读字幕读不出"第 3 秒画面突然切到产品特写"这种信息。
- 从录屏里定位 bug。同事发来一段屏幕录像说"这里崩了"，你没法让 AI 直接看录像找问题出现在第几帧。
- 快速总结长视频。2x 速看一遍还是要花时间，想让 AI 帮你压缩成笔记，但它只能基于字幕压缩，漏掉画面演示。
- 过滤更新视频里的水分。一场"game-changer"发布会有十分钟寒暄和吹嘘，你只想知道到底新增了什么，字幕没法告诉你"这一帧才是新功能演示"。
/watch 解决的方式是：把视频拆成 Claude 能消化的两种模态——帧（图片）+ 字幕（文本），然后让 Claude 像看图说话一样真正"看"完再回答。
三、核心机制：/watch 怎么工作
README 把 /watch 的链路拆成 6 步，本质是一条"下载 → 抽帧 → 转写 → 交给 Claude"的流水线：
- 你贴视频 + 提问。URL（任何 yt-dlp 支持的源：YouTube、Loom、TikTok、X、Instagram 等几百个）或本地路径（
.mp4、.mov、.mkv、.webm）。 - yt-dlp 先查字幕。
transcript模式下，有字幕的 URL 直接返回，不下载视频。需要音频时才下载，且只下载必要部分。 - ffmpeg 按指定 detail 抽帧。
efficient只解码关键帧（接近秒出）；balanced/token-burner优先取场景切换帧，不够再退化为按时长均匀采样。JPEG 默认 512px 宽，限高 1998px 以兼容 Claude Read。 - 字幕来自两处之一。优先用 yt-dlp 拉原生字幕（手动或自动生成，免费、即时、精度尚可）；没字幕时回退到 Whisper——抽一段 mono 16kHz 64kbps mp3（约 480KB/分钟），发给 Groq 的
whisper-large-v3（首选，更便宜更快）或 OpenAI 的whisper-1。 - 帧 + 字幕一起交给 Claude。脚本把帧路径（带
t=MM:SS标记）和时间戳字幕打印出来，Claude 并行Read每一帧——JPEG 在它的上下文里直接作为图片渲染。 - Claude 基于真正看到的画面和听到的字幕作答。不是"根据描述"或"根据标题"，而是像看过视频的人一样回答。最后清理临时目录（除非你要追问）。
关键设计在帧预算。每帧都是图片，图片 token 烧得快，所以脚本有一套 auto-fps 逻辑，避免在 30 分钟视频上做稀疏扫描、反而把上下文预算烧光：
| 时长 | 默认帧预算 | 效果 |
|---|---|---|
| ≤30 秒 | ~30 帧 | 密集，几乎每个关键时刻都有 |
| 30 秒 - 1 分钟 | ~40 帧 | 仍然密集 |
| 1 - 3 分钟 | ~60 帧 | 够用 |
| 3 - 10 分钟 | ~80 帧 | 稀疏但能看 |
| >10 分钟 | 100 帧（封顶模式） | 触发"sparse scan"警告，建议改用 --start/--end 聚焦 |
另一个省 token 的设计是帧去重。屏幕录像里一张幻灯片停 90 秒，会抽出十几张几乎一样的帧，每张都按独立图片计费。去重默认开启（--no-dedup 可关）：把每帧缩成 16×16 灰度缩略图，算与"上一个保留帧"的平均绝对差，差值 ≤2.0 就丢掉。比"上一帧"而不是"前一张"，能抓住缓慢渐变。balanced 的帧预算上限在去重之后才生效，保证预算花在"不同的画面"上。
四、三分钟上手
Claude Code（推荐，marketplace 自动更新）：
/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-videoCodex / Cursor / Copilot / Gemini CLI 等 50+ host：
npx skills add bradautomates/claude-video -g-g 全局装（~/.codex/skills、~/.cursor/skills 等），去掉则只装到当前项目。
首次运行：第一次 /watch 时，scripts/setup.py --check 会检查 ffmpeg/yt-dlp 是否在 PATH、是否设了 Whisper key，没装就引导你装——macOS 自动 brew install，Linux/Windows 打印 apt/dnf/winget/pip 的确切命令。检查是 100ms 内的查询，不影响后续使用。
装完直接用：
/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?
/watch https://www.tiktok.com/@user/video/123 summarize this
/watch ~/Movies/screen-recording.mp4 when does the UI break?聚焦某一段（帧更密、token 更省）：
/watch https://youtu.be/abc --start 2:15 --end 2:45
/watch video.mp4 --start 50 --end 60
/watch "$URL" --start 1:12:00 # 从 1h12m 到结尾要不要 API Key：大多数公开视频有原生字幕，免费就能跑。只有当视频真的没字幕轨（本地文件、部分 TikTok/Vimeo、个别无字幕 YouTube）才需要 Whisper 回退，这时去 Groq Console 拿个 GROQ_API_KEY（首选）或 OpenAI 拿 OPENAI_API_KEY，写进 ~/.config/watch/.env。想完全不用 Whisper，加 --no-whisper 只看帧。文档里用 sk-xxx 这类占位，别提交真 key。
常用调节参数：
| 参数 | 作用 |
|---|---|
--detail transcript|efficient|balanced|token-burner | 速度/精度拨盘，见下表 |
--start / --end | 聚焦时间段，帧更密 |
--timestamps T1,T2,… | 在指定时间点强制抓帧 |
--max-frames N | 压低帧上限，省 token |
--resolution 1024 | 加宽到 1024px，看清幻灯片/终端/代码 |
--no-whisper | 不转写，只看帧 |
--no-dedup | 保留近似重复帧 |
四种 detail 模式实测对比（README 给的真实数据，源是一个 49:08 的 YouTube 录屏，1280×720，英文自动字幕）：
| 模式 | 引擎 | 帧数 | 上限 | 抽帧耗时 | 估算图片 token |
|---|---|---|---|---|---|
transcript | 无（仅字幕） | 0 | - | ~4.5s（一次 yt-dlp，不下载） | 0（约 26.6k 文本 token） |
efficient | 关键帧 | 50 | 50 | ~0.5s | ~9.8k |
balanced | 场景切换 | 100 | 100 | ~20.9s | ~19.7k |
token-burner | 场景切换 | 116 | 不封顶 | ~21.0s | ~22.8k |
efficient 是速度档（只重建关键帧，比场景模式快约 40 倍）；token-burner 只在超过上限后才和 balanced 分叉——这段视频有 116 个切换点，balanced 采样到 100，token-burner 全保留。
五、适合谁 + 踩坑
适合的人：
- 做内容拆解的人。拆爆款 hook、广告创意、竞品发布会、播客开场，"怎么讲的"和"讲了什么"一样重要时。
- 从录屏排 bug 的开发者。同事甩来一段"这里崩了"的屏幕录像，让 Claude 看完直接指出问题帧和原因。
- 要把长视频/课程变成笔记的人。一个频道或一门课跑一遍
/watch summarize this to a note，几小时视频变成可检索的笔记集。 - 想过滤发布会水分的人。
what's actually new - skip the hype一句话把十分钟吹嘘砍成几条实质更新。
踩坑点：
- 长视频 token 消耗。这是最大的坑。帧是图片，图片 token 烧得快。
balanced默认 100 帧封顶，超过 10 分钟的视频帧会变稀疏，脚本会打"sparse scan"警告。要么用--start/--end聚焦关键段，要么--detail token-burner解除封顶（但 token 涨得更猛）。--resolution 1024会让单帧 token 翻约 4 倍，看清终端代码时才开。 - ffmpeg / yt-dlp 依赖。这俩是硬依赖，没装跑不起来。macOS 首次运行自动
brew install；Linux/Windows 只打印命令，得自己跑一遍。claude.ai 网页端用还要先在 Capabilities 里开"Code execution and file creation"，因为 skill 要 shell 出去调 ffmpeg。 - 转写精度。原生字幕是"免费、即时、精度尚可"，自动字幕可能错。Whisper 回退更准但要花钱花时间。完全无字幕的视频（部分 TikTok、个别 Vimeo、本地文件）只能走 Whisper，没 key 就
--no-whisper只看帧。 - Whisper key 配置。
~/.config/watch/.env要0600权限，GROQ_API_KEY（首选）或OPENAI_API_KEY。用sk-xxx这类占位，别提交真 key。 - 静态画面的去重误判。去重阈值 2.0 很低、按亮度差算，能保留一行代码 diff、终端滚一行、不同色块幻灯片。但如果两帧结构差异大但亮度接近，理论上有被误丢的可能——觉得漏了细节就
--no-dedup全保留。
六、和替代方案比
只陈述能核实的事实，不编造竞品。
| 方案 | 能看画面 | 能读字幕 | 需要人工 | 备注 |
|---|---|---|---|---|
| Claude 原生（不装 /watch） | 否 | 部分（拉得到才有） | 低 | README 原话：transcript "missing 90% of what's on screen" |
| 手动 scrub + 截图 + 粘贴 | 是 | 手动抄 | 高 | 能做，但慢，且 Claude 拿到的是零散截图无时间线 |
| 纯 yt-dlp 拉字幕 | 否 | 是 | 低 | 只有文本，画面信息全丢 |
claude-video /watch | 是 | 是 | 低 | 帧带 t=MM:SS 时间戳，Claude 并行 Read 每帧 |
/watch 的差异化在于把"帧（图片）+ 字幕（文本）+ 时间戳"三件套一起喂给 Claude，让它的回答同时基于画面和音频，而不是只读字幕猜画面。它不是替代 yt-dlp 或 Whisper，而是把这两者加上 ffmpeg 抽帧，编排成一条 Claude 能直接消费的链路。
看法
claude-video 命中的是一个被低估的缺口：大家都说大模型多模态，但 Claude Code 这类编码 agent 日常"看视频"这件事一直没人系统解决。14204 星、周榜第 20 说明这个点踩准了——开发者确实需要让 AI 看录屏排 bug、看发布会提取更新、看竞品视频拆结构。
它的工程取舍很克制：不自己造下载器/转写器，全押在 yt-dlp + ffmpeg + Whisper 这套成熟工具链上，自己只做"帧预算 + 去重 + detail 模式"这套 token 经济学，以及把结果编排成 Claude 能 Read 的格式。这种"不重复造轮子、只补缺口"的定位，是它能用 MIT 协议、纯 Python stdlib 维持轻量的原因。
门槛也有：长视频的 token 成本要自己管，ffmpeg/yt-dlp 要装，无字幕视频要配 Whisper key。但比起手动 scrub 截图，这条链路一旦跑通，省下的是真正看视频的时间。
参考来源
- claude-video GitHub 仓库：https://github.com/bradautomates/claude-video
- README（/watch 机制、安装、用法、detail 模式实测数据、帧预算表）：https://github.com/bradautomates/claude-video/blob/main/README.md
- Agent Skills（npx skills CLI、支持的 host 列表）：https://agentskills.io
- Groq Console（Whisper key）：https://console.groq.com/keys
- 星数/fork/语言/许可证/创建时间/push 时间依据 GitHub API（2026-08-06 核实，14204 stars，实时变动）
- 周榜排名与周增长（第 20、+3359）依据 GitHub 周榜（2026-08-06）