如何用最少的 Token 看懂长视频?claude-watch 帧预算机制完全解析
如何用最少的 Token 看懂长视频?claude-watch 帧预算机制完全解析
把一段长视频交给 AI 分析,真正的成本大头是视频帧——每一帧都是一张图,图像 Token 累积极快。claude-watch 是一个开源的 Claude 技能(Skill),它让 AI 真正"看懂"任意视频:自动下载视频、按场景切变抽取帧、获取带时间戳的字幕,并生成结构化的 report.md 报告。它控制 Token 花费的关键,就是内置的帧预算(frame budget)机制:按视频时长自动分配帧数,并设下 2 fps、100 帧两条硬上限,让 Token 开销不再随视频变长而失控。
下面带你完整拆解这套机制的设计思路和使用技巧。
一、为什么长视频是"Token 杀手"?先看懂成本结构 💸
Claude-watch 对一次观看的成本做了清晰拆解(见 SKILL.md 的 Token efficiency 章节):
| 成本项 | 量级 | 说明 |
|---|---|---|
| 视频帧(图像) | 50k - 80k tokens | 80 帧、512px 宽时的典型开销,成本主体 |
| 字幕文本 | 数千 tokens | 10 分钟视频的字幕很"便宜" |
| 分辨率提升 | 约 4 倍 | --resolution 1024 会让单帧图像 Token 翻约 4 倍 |
结论一目了然:想省 Token,核心就是控制帧的数量和尺寸。这正是 claude-watch 帧预算机制要解决的问题——用尽量少的帧,覆盖视频里最重要的画面。
二、帧预算核心:按时长分 5 档,帧数自动分配 ⚙️
当你完整扫描一个视频时,scripts/frames.py 中的 auto_fps() 会根据时长选择目标帧数,再反推出采样帧率:
| 视频时长 | 默认帧预算 | 覆盖效果 |
|---|---|---|
| ≤ 30 秒 | 12-30 帧 | 密集,几乎覆盖每个关键画面 |
| 30 秒 - 1 分钟 | 约 40 帧 | 依然密集 |
| 1 - 3 分钟 | 约 60 帧 | 舒适 |
| 3 - 10 分钟 | 约 80 帧 | 略稀疏但可用 |
| > 10 分钟 | 100 帧(上限) | 会打印"sparse scan"警告,建议聚焦重跑 |
三条硬性规则(定义见 scripts/frames.py 与 scripts/watch.py):
- 帧率上限 2 fps —— 即使时长公式算出更高,也会被钳制;
- 帧数上限 100 帧 —— 用
--max-frames还能手动调低(脚本默认 80 帧); - 超 10 分钟必警告 —— 脚本会明确提示你改用聚焦模式,而不是浪费 Token 做稀疏全扫。
这套逻辑的精髓在于:预算跟着时长走,短视频给足帧数保证精度,长视频封顶保住钱包。
三、场景切变采样:每个镜头只取 1 帧,Token 成本与时长解绑 ✂️
帧预算解决了"取多少帧",采样策略解决"取哪几帧"。完整扫描且未手动指定 --fps 时,claude-watch 默认启用场景切变采样(scripts/frames.py 的 extract_scene_change()):
- 利用 ffmpeg 的
select='gt(scene,0.3)'滤镜,在每次画面明显变化(硬切、叠化)时抓 1 帧; - 帧数取决于镜头切数,而不是视频时长 —— 一部 40 分钟但只有 60 个镜头的纪录片,也只花 60 帧的 Token,成本基本恒定;
- 每个切变点都会被捕获,不会漏掉转场画面;
- 智能兜底:如果检测到的场景少于 10 个(比如全程口播、录屏这类"静态"视频),会自动回退为均匀采样,避免"几乎没帧可用"。
💡 调试时可加
--no-scene-change强制均匀采样,但日常建议保持默认。
四、聚焦模式:只看你关心的片段,密度立刻翻倍 🔍
当你的问题针对某个具体时刻("2 分 30 秒发生了什么?""最后 30 秒呢?"),用 --start / --end 进入聚焦模式。此时切换为更密集的预算表(scripts/frames.py 的 auto_fps_focus()):
| 片段长度 | 帧预算 |
|---|---|
| ≤ 5 秒 | 2 fps(最多 10 帧) |
| 5 - 15 秒 | 2 fps(最多 30 帧) |
| 15 - 30 秒 | 约 2 fps(最多 60 帧) |
| 30 - 60 秒 | 约 1.3 fps(最多 80 帧) |
| 60 - 180 秒 | 约 0.6 fps(100 帧封顶) |
聚焦模式还有个隐藏福利:字幕会自动过滤到同一时间范围,时间戳保持为视频原始绝对时间。对超过 10 分钟的视频,"先全扫一遍定位 → 再聚焦重跑目标区段"往往比一次性稀疏扫描有用得多。
五、Hook 显微镜:把最贵的预算花在开场 10 秒 🎬
前 10 秒是决定观众去留的黄金时段,claude-watch 为它单独设了"显微镜"(scripts/hook.py):
- 对 0-10 秒以 2 fps 高密度重采一遍(约 20 帧);
- 同时用 Whisper 生成词级时间戳字幕,让报告能逐帧对齐"画面在变的那一刻,嘴里说的是哪个词";
- 总预算被锁在 25 帧以内,开销可控;
- 视频不足 30 秒时自动跳过(整个视频本来就是"开场");
- 不想要时可加
--no-hook-microscope跳过,省一次 Whisper 调用。
配合 scripts/pacing.py 输出的剪辑节奏指标(每分钟切数、平均/中位镜头时长),报告里的"Editorial profile"部分能直接给出这条视频的节奏指纹。
六、快速上手:安装 + 3 类命令搞定 🚀
第 1 步:安装(Claude Code 环境)
/plugin marketplace add taoufik123-collab/claude-watch
/plugin install watch@claude-watch
首次运行时会自动检查 ffmpeg / yt-dlp 依赖(macOS 走 brew 自动装,Linux/Windows 会打印对应安装命令),并引导配置 Whisper API Key(可选)。
第 2 步:观看视频
/watch https://youtu.be/dQw4w9WgXcQ 30秒处发生了什么?
/watch ~/Movies/screen-recording.mp4 界面哪里出了问题?
第 3 步:省 Token 的常用参数(入口在 scripts/watch.py)
| 参数 | 作用 |
|---|---|
--start 2:15 --end 2:45 |
只扫指定区段,聚焦模式预算更密 |
--max-frames 40 |
压低帧数上限,进一步收紧预算 |
--resolution 512 |
帧宽度,默认 512px;需读屏上文字时才升到 1024 |
--no-whisper |
关闭 Whisper 回退,无字幕时纯帧模式 |
--no-hook-microscope |
跳过 0-10 秒密集重采 |
七、实战清单:7 个习惯把 Token 花到刀刃上 ✅
- 10 分钟以内的视频精度最佳,先确认对方时长;
- 长视频别硬扫:先全扫定位,再用
--start/--end聚焦重跑目标区段; - 预算紧张就降帧:
--max-frames 40立竿见影; - 默认 512px 足够:只有需要读 PPT/代码屏时再上 1024(约 4 倍开销);
- 口播类视频可以
--no-whisper:字幕源免费且优先,纯口播有字幕时根本用不到付费转写; - 跟进提问不要重跑:同一会话内帧和字幕已在上下文里,直接追问即可(官方明确建议,见 SKILL.md);
- 善用
--intent:把"我想研究它的开头钩子"传给脚本,报告结构会更贴合你的目的,减少无效阅读。
小结 📌
claude-watch 的帧预算机制可以概括为一句话:帧数按时长分档、切变采样定去留、硬上限兜底、聚焦模式加密度、开场 10 秒单独加密。理解这五点之后,无论面对 30 秒的短视频还是 1 小时的讲座,你都能用可预测的 Token 成本,让 AI 真正"看过"视频再回答。
📂 核心模块速查:入口 scripts/watch.py · 帧预算与采样 scripts/frames.py · Hook 显微镜 scripts/hook.py · 剪辑节奏 scripts/pacing.py · 报告生成 scripts/report.py · 完整技能契约 SKILL.md