Claude Code 让 AI 真正「看懂」视频：从字幕提取到多帧画面理解的完整技术拆解

本文由 莫潇羽@源码七号站（www.fuyuan7.com）撰写，转载请注明出处。

快速摘要

AI 编程助手能读网页、能跑代码、能分析文档，但很长一段时间里，它们面对视频内容时几乎是个"睁眼瞎"——只能扒拉字幕猜大意，画面里真正发生了什么，模型完全不知道。2026 年，GitHub 上一个叫 claude-video 的开源项目改变了这个局面：它把视频拆成"关键帧画面 + 带时间戳的音频文字"，一起喂给 Claude 多模态模型，让 AI 的回答建立在"看到和听到"的基础上，而不只是猜。本文从 Agent Skill 的底层机制讲起，把整套流程拆开揉碎——ffmpeg 场景感知抽帧、帧去重算法、Token 预算管控、Whisper 兜底转录——每个环节都配合实操命令和对比表格，读完你也能在自己的 Claude Code 里跑起来。

想看完整拆解，往下翻。

聊一个我最近折腾了大半个月的东西。

事情起因很简单：我在 B 站收藏了一堆技术分享视频，每个动辄四五十分钟。说实话，真没时间一个一个从头看到尾。哪怕 2 倍速开着，眼睛盯久了也累。

我就想：能不能让 AI 帮我看？

于是我把一个 B 站视频的链接丢给了 Claude Code，问它"这个视频讲了什么"。

结果很失望。它只能告诉我视频标题、简介，顶多抓取到一段残缺不全的自动字幕。然后开始"根据标题推测"，编了一大段听起来很有道理、但和视频实际内容八竿子打不着的总结。

这不是 Claude 的问题。这是几乎所有大语言模型面对视频内容的通病。

你想想：模型本质上处理的是文本和图片。你丢给它一个视频链接，它拿到的只是一行 URL 字符串。它能做的，就是去抓取这个链接对应的网页标题、描述和字幕——如果有的话。至于视频画面里发生了什么？人物做了什么动作？背景是什么环境？屏幕录制里鼠标点到了哪里？——模型一概不知。

这个局限其实挺要命的。因为很多视频真正有价值的信息，压根不在语音里。

比如你看一个前端开发的录屏教程：讲师嘴上说着"这里我们调整一下样式"，但真正关键的是画面——CSS 代码怎么写、浏览器 DevTools 里改了什么属性、布局效果怎么变的。字幕只能告诉你"他在调样式"，但画面才能告诉你"他调了什么、怎么调的"。

再看一个产品发布的演示视频：演讲者可能说了一大堆"颠覆式创新""划时代的体验"，但真正的功能变更和 UI 改动，全在屏幕上。光读字幕，你根本分不清哪些是营销话术，哪些是实实在在的更新。

还有一个更现实的场景：你同事发来一段屏幕录制，说"你帮我看看这里是不是有 Bug"——但他没告诉你 Bug 在几分几秒。你难道真把整段录屏看一遍？

这些场景，单靠"字幕提取"或者"语音转文字"是搞不定的。你必须让 AI 同时看到画面。

AI 为什么一直「看不懂」视频

这个问题本质上是一个"模态转换"的困境。

大语言模型的输入模态，最早只有文本。后来 OpenAI 的 GPT-4V、Anthropic 的 Claude 3 系列、Google 的 Gemini 陆续加入了"视觉理解"能力——模型可以直接"读图"，把图片内容转成内部的视觉表征，再和文本一起推理。

这已经很厉害了。你把一张截图丢给 Claude，它能准确描述截图里的 UI 布局、代码片段、甚至是图表里的数据。

但视频不一样。

视频是多模态信息的复合体：画面（视觉帧）在时间轴上连续变化，音频（语音/环境音）和画面同步播放。一段 10 分钟的视频，按 30fps 算就是 18000 帧画面。把每一帧当图片丢给模型？先不说 Token 成本爆炸，模型上下文窗口也塞不下。

于是，市面上的绝大多数"AI 视频分析工具"，走了一条取巧的路线：它们只处理音频，把语音转成文字，然后让大模型基于纯文本来总结。

说白了，就是把视频当播客听。

这种方式在某些场景下够用——比如你只是想快速了解一个对谈类视频的核心观点，主讲人嘴里说的确实就是核心信息。但换个场景立马暴露短板：

• 画面信息密度高的视频：代码演示、UI 操作录屏、绘画教程、体育比赛分析——画面才是主角，语音只是辅助；
• 非语言内容：视频里出现了一个图表、一段文字提示、一个表情变化——这些东西不会出现在字幕里；
• 视觉节奏和风格：爆款视频的开场钩子、转场节奏、色彩搭配——这些信息只有画面能传达。

莫潇羽@源码七号站在实际折腾中就踩过这个坑。之前想分析一个技术博主的高播放量视频，搞清楚他的内容结构和剪辑节奏。字幕只能告诉我他讲了什么话题，但画面才能告诉我——他前 3 秒用了什么视觉钩子？字幕卡出现的时间和位置？B-roll 素材的切换频率是多少？这些信息对理解"为什么这个视频数据好"至关重要，但纯文字分析完全拿不到。

所以问题的核心就很清楚了：要给 AI 真正的视频理解能力，不能只做音频转文字。必须让模型同时看到画面、听到声音、理解时间线。三样缺一不可。

这就是 claude-video 这个项目试图解决的事情。它不是第一个尝试这个方向的工具，但它抓住了关键点：不要把视频当作一个整体丢给模型，而是把它拆解成模型能理解的最小单元——关键帧图片 + 带时间戳的文字稿——然后让模型基于这些材料做综合推理。

这种思路，用一句大白话概括就是：模型不一定要原生支持视频输入，但你可以把视频预处理成模型认识的东西。 就像你不会直接把一个 .docx 文件丢给只会读纯文本的老程序——你先把它转成 TXT，程序就认识了。对 AI 来说，视频转"图片序列 + 文字脚本"，也是同样的道理。

claude-video 是什么：给 AI 装上「眼睛」

claude-video 是开发者 Brad Bonanno 在 2026 年发布的一个开源 Agent Skill 项目，托管在 GitHub 上（仓库地址：bradautomates/claude-video），采用 MIT 协议开源。截至我写这篇文章时，项目已经拿了超过 8300 个 Star，在 GitHub Trending Python 榜单上一度单周新增 4300+ 星，热度非常高。

那它到底能干什么？一句话概括：你在 Claude Code 里敲 /watch 命令，后面跟一个视频链接或本地文件路径，Claude 就能"看"这个视频，然后回答你关于视频内容的任何问题。

它支持的东西挺全：

合规提示：文中提及的境外视频平台和 AI 模型服务，仅用于技术原理的学习研究。境外模型使用需遵守国内网络与内容管理相关规定，部分境外网站及服务在中国大陆可能无法直接访问。本文重点关注技术实现思路，文中所有操作请确保在合规框架内进行。

安装方式简单到令人发指——你甚至不需要手动 clone 仓库。在 Claude Code 里敲一行命令就行：

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

如果是 Codex、Cursor、Copilot 或其他 Agent 宿主环境，也能一行搞定（-g 表示全局安装，所有项目都能用）：

npx skills add bradautomates/claude-video -g

装完之后，你就可以用 /watch 命令了。比如：

/watch https://example.com/video 这个视频的核心观点是什么？
/watch ~/Movies/demo.mp4 界面上从哪一秒开始出现报错？

第一次运行的时候，项目会自动检测你的系统里有没有 ffmpeg 和 yt-dlp 这两个依赖。macOS 上它会走 Homebrew 自动安装；Linux 和 Windows 上会打印对应的安装命令，比如 apt install ffmpeg 或 winget install ffmpeg，你复制粘贴跑一下就行。

如果视频本身有字幕，到这里就能直接用了——零成本。只有当视频没有字幕、需要走语音转录的时候，你才需要配置 Whisper API Key。项目支持 Groq 的 whisper-large-v3（更便宜更快）和 OpenAI 的 whisper-1 两种后端，配置文件写在 ~/.config/watch/.env 里，格式很简单：

# 二选一，推荐 Groq（便宜）
WHISPER_PROVIDER=groq
GROQ_API_KEY=gsk_xxxxxxxxxxxx

# 或者用 OpenAI
WHISPER_PROVIDER=openai
OPENAI_API_KEY=sk-xxxxxxxxxxxx

整体来看，这个项目的设计哲学很清晰：零配置起步，按需付费，先免费后增值。 能用免费字幕就不用付费 Whisper，能用关键帧就不用全帧扫描，能去重就不浪费 Token。每一个设计决策都在帮用户省钱。

但话说回来，一个 "/watch 命令" 为什么能有这么大能量？它背后到底是什么机制在工作？要理解这一点，我们得先搞清楚一个更基础的问题：Agent Skill 到底是什么东西。

Agent Skill 机制原理：AI 的「技能包」是怎么工作的

讲 claude-video 的技术实现之前，有必要先聊聊它运行的"底座"——Claude Code 的 Agent Skill 机制。因为你只有理解了 Skill 是怎么被加载、怎么被调用的，才能真正明白 /watch 命令为什么能"凭空"给 Claude 增加视频分析能力。

Skill 的本质：一个标准化的文件目录

别看"Skill"这个名字很高级，拆开来看，它在文件系统层面就是一个目录，里面通常包含这几样东西：

skills/watch/
├── SKILL.md          ← 核心指令：告诉 Claude 这个技能怎么用
├── AGENTS.md         ← 元数据：技能的触发条件、适用场景
├── scripts/          ← 可执行脚本：Python/Shell，处理具体逻辑
└── references/       ← 参考文件：按需加载的补充文档

其中 SKILL.md 是最核心的。它本质上是一段精心编写的 Prompt，用 Markdown 格式写成，里面定义了：这个 Skill 叫什么名字、什么情况下触发、接受什么参数、每一步怎么执行、有哪些约束条件。

当 Claude Code 启动时，它会扫描项目目录下 .claude/skills/ 和全局安装路径里的所有 Skill，把每个 Skill 的"元数据摘要"预加载到上下文中。这时候 Claude 只是知道"我有这些技能可用"，但并不会把每个 Skill 的完整指令全部塞进上下文——否则 10 个 Skill 每个 2000 字，光 Prompt 就 20000 Token 了。

渐进式披露：用到时才加载全文

这里涉及一个非常关键的设计思想，叫渐进式披露（Progressive Disclosure）。

用大白话说就是：Claude 先看"技能目录"（元数据），判断用户的需求和哪个 Skill 匹配；判断命中之后，才去读取那个 Skill 的完整 SKILL.md 指令，把里面的规则作为本次任务的行为依据。

实测数据显示，这套架构在处理长链条业务流程时，能将上下文 Token 消耗降低 60% 到 80%，同时显著提升指令遵循准确率。

我画个流程图帮你理解：

flowchart TD
    A[用户输入 /watch 视频链接] --> B[Claude 读取已注册 Skill 元数据]
    B --> C{匹配到 watch Skill?}
    C -->|是| D[读取 SKILL.md 完整指令]
    C -->|否| E[按普通对话模式处理]
    D --> F[按 SKILL.md 定义的流程执行脚本]
    F --> G[调用 yt-dlp 下载/获取字幕]
    G --> H[调用 ffmpeg 抽帧]
    H --> I[必要时调用 Whisper 转录]
    I --> J[将帧图片 + 文字稿交给 Claude]
    J --> K[Claude 基于多模态理解回答用户]
    K --> L[清理临时文件，返回结果]

这就是为什么 /watch 能工作的根本原因。它不是 Claude 原生支持的功能，而是通过 Skill 机制"外挂"上去的。Claude 本体的能力是读文本 + 读图片 + 推理，Skill 负责把"视频"这个 Claude 不认识的东西，转换成它认识的"图片 + 文字"。

Skill 和 MCP 是什么关系

聊 Skill 的时候经常会顺带提到 MCP（Model Context Protocol）。两者都是扩展 AI 能力的机制，但定位不同：

• MCP：偏向实时数据连接。比如连接数据库、调用 API、读写文件系统。它像一个"外接设备驱动程序"；
• Skill：偏向流程编排 + 领域知识注入。它定义了一套完整的"遇到某类任务时该怎么做"的 SOP。

在 claude-video 这个项目里，两者其实有配合：Skill 定义了"视频分析"这个任务的处理流程和参数约束，而脚本里调用 yt-dlp、ffmpeg 这些外部工具的具体执行，走的是 Bash 命令——这又和 MCP 的工具调用机制协同工作。

把这个关系理清楚，我们再去看 claude-video 的六步处理管道，就会觉得顺理成章了。

核心流程拆解：从视频链接到 AI 理解的六步管道

理解了 Skill 的加载机制之后，我们把镜头对准 claude-video 的 /watch 命令，看看当你在 Claude Code 里敲下 /watch https://example.com/video 总结一下 之后，背后到底发生了什么。

整个处理流程可以拆成六个步骤。每一步都做了明确的职责划分，缺一步都不行。

第一步：接收视频源与用户问题

/watch 命令接受两个核心输入：视频源（URL 或本地路径）和用户问题（可选，不写就默认做整体分析）。

视频源的类型决定了后续处理路径的选择：

• 如果是一个 URL（比如视频分享平台的链接），脚本会调用 yt-dlp 来解析。yt-dlp 是一个开源的命令行视频下载工具，支持数百个视频站点。它不仅能下载视频文件，还能提取元数据（标题、简介、上传时间）和字幕轨道信息；
• 如果是一个本地文件路径（比如 ~/Desktop/demo.mp4），脚本会直接用 ffprobe（ffmpeg 套件里的信息探测工具）检查文件格式、编码、时长等参数。

这里有一个值得注意的细节：项目会先只拿元数据和字幕，不着急下载视频本体。这为后面的"按需下载"策略埋下了伏笔。

第二步：优先读字幕

字幕是成本最低的信息源。如果视频本身自带字幕文件（很多平台会自动生成或由创作者上传），项目会直接用 yt-dlp 把字幕提出来——.vtt 或 .srt 格式都行——然后解析成带时间戳的纯文本。

字幕命中，就意味着不需要走 Whisper 语音转录。这是成本层面的关键分叉：

• 有字幕：零 API 调用成本，直接从字幕文件出文字稿；
• 没字幕：需要把音频下载下来，送到 Whisper 做语音转录，产生 API 调用费用。

字幕还有一个优势是准确性。人工上传的字幕通常比机器转录靠谱，尤其是涉及专业术语、中英混读、多人对话这些 Whisper 容易翻车的场景。

第三步：按需下载音频/视频

这里体现了项目设计上的克制。它不是一股脑把整个视频下载下来——50 分钟的高清视频可能有 2 到 3GB，下载慢不说，本地磁盘也扛不住。

它的逻辑是：

• 如果用户选了 transcript 模式（只要文字不要画面），而且视频有字幕：什么都不下载，直接从第二步出结果；
• 如果只需要音频（做 Whisper 转录用）：只下载音频轨道，单声道 16kHz、64kbps 的压缩规格，每分钟大约 480KB——一段 30 分钟的视频，音频文件才 14MB 左右；
• 如果需要抽帧分析画面：这时才下载视频本体，而且可以根据 --detail 参数选择分辨率（低画质省带宽，高画质看细节）。

从我实际上手的情况来看，这个设计在日常使用中带来的体验提升非常明显。想想看：你只是想快速了解一个长视频讲了什么，结果工具先花 5 分钟下载了 3GB 的文件，这体验是不是很差？claude-video 避免了这个问题。

第四步：ffmpeg 场景感知抽帧

这是整个流程里技术含量最高的一环。笼统地说，就是用 ffmpeg 从视频里按一定策略抽取画面帧。但具体怎么抽，学问很大。

项目提供了四种 --detail 档位，对应不同的抽帧引擎和策略，后面会有专门一章详细对比。这里先概括核心思路：

• efficient（高效）：只抽关键帧（I 帧）。关键帧是视频编码中自带完整画面信息的帧，不需要参考前后帧就能独立解码。抽取速度极快（一段 49 分钟视频约 0.5 秒），但帧数较少；
• balanced（均衡）：基于场景切换检测。ffmpeg 内置的 scdet 滤镜会逐帧计算像素差异，当画面发生显著变化（镜头切换、场景转换）时才保留一帧。兼顾了画面覆盖度和 Token 成本；
• token-burner（全量）：同样基于场景切换检测，但不设帧数上限，尽可能保留每一次画面切换。适合需要逐帧回溯的精细分析场景；
• transcript（纯文字）：跳过抽帧步骤，完全不处理画面。

用哪种档位取决于你的需求。日常看个视频总结，efficient 或 balanced 绰绰有余；做爆款视频的帧级拆解才需要 token-burner。

第五步：无字幕时走 Whisper 转录

如果视频没有自带字幕，项目会把第四步中下载的音频（或从视频中提取的音频轨）送到 Whisper 做语音转录。

Whisper 是 OpenAI 开源的一个语音识别模型，支持近百种语言，对中文的识别效果相当不错。项目支持两种调用后端：

• Groq 的 whisper-large-v3：走 Groq 云端推理，速度快、价格低，是项目推荐的首选；
• OpenAI 的 whisper-1：走 OpenAI 官方 API，国内开发者可能更熟悉。

转录完成后会生成带时间戳的文字稿，和从字幕文件里解析出来的格式保持一致，方便 Claude 后续处理。

这里顺便提醒一句：Whisper 的转录虽然准确率不错，但遇到重口音、多人重叠对话、或者背景噪音很大的视频，还是会出现识别错误。对于关键信息，建议人工核对一下。

第六步：帧图片 + 文字稿一起交给 Claude

所有材料准备齐全之后——关键帧图片文件（带文件路径列表）+ 带时间戳的完整文字稿——脚本把它们打包成一个结构化的 Prompt，送给 Claude。

Claude 的多模态能力在这里发挥了关键作用：它把每一帧图片"读"进去，理解画面里的视觉信息（人物、文字、UI、图表、动作序列），同时把文字稿里的语音内容和时间戳对应起来。这样一来，Claude 回答问题时就能同时参考"看到了什么"和"听到了什么"。

第七步（收尾）：清理临时文件

处理完成后，脚本会自动清理所有下载的临时文件——视频、音频、抽取的帧图片。不会在你的硬盘上留一堆垃圾。

下面这个流程图把六步串起来，一目了然：

flowchart LR
    A[ 视频 URL / 本地文件] --> B{yt-dlp 解析}
    B --> C{有自带字幕?}
    C -->|有| D[ 提取字幕文字稿]
    C -->|无| E[ 按需下载音频/视频]
    E --> F[ Whisper 语音转录]
    D --> G{用户需要画面分析?}
    F --> G
    G -->|需要| H[ ffmpeg 场景感知抽帧]
    G -->|不需要 transcript| I[跳过抽帧]
    H --> J[ 帧图片 + 文字稿 → Claude 多模态推理]
    I --> J
    J --> K[ 生成回答 + 清理临时文件]

一个具体例子

说这么多理论，不如跑一个实际例子直观。我拿一段 6 分钟的本地视频做测试——内容是一个趣味技术分享，介绍图像处理中的某个开源项目。

在 Claude Code 里敲：

/watch ~/Videos/tech-talk.mp4 请基于这个视频整理成图文笔记

Claude Code 的返回过程如下：

1. 它先问了我两个澄清问题：帧密度要多少？要不要分析字幕？（因为第一次用，它在确认我的偏好）
2. 我选了 balanced 模式；
3. 脚本开始工作：yt-dlp 确认这是个本地文件不需要下载 → ffprobe 检测到视频时长为 6 分 12 秒 → ffmpeg 用场景检测抽了约 50 帧 → 视频自带字幕，提取后得到完整文字稿；
4. 约 30 秒后（主要是抽帧和上传图片的时间），Claude 开始输出；
5. 最终生成的图文笔记，内容逻辑比纯字幕总结顺畅很多——因为它能看到视频里的代码演示画面、架构图、甚至演讲者的手势。

这个体验，和之前"丢个链接只能看字幕"相比，真的不是一个维度的东西。莫潇羽@源码七号站自己折腾下来，最直观的感受是：当 AI 能同时看到画面和听到声音，它给出的回答突然有了"在场感"。

抽帧策略详解：四种画质档位怎么选

上一章提到了四种 --detail 档位，但只是简单带过。这一章我们深入拆解每种档位的引擎原理、帧数上限、适用场景和实测性能，帮你搞清楚：我的场景到底该选哪个。

四种档位的对比总览

实测数据来源：项目官方对一段 49 分 08 秒 720p 视频的测试。不同视频的实际数值会有波动，但比例关系大致稳定。

下面逐个深挖。

transcript：只要文字，最快最省

transcript 模式最简单粗暴——完全不碰画面。它走的是"字幕 → 文字稿 → 交给 Claude"的最短路径。如果你只是想知道一个播客对谈讲了什么观点、一个新闻发布会宣布了什么政策、或者一个课程大致覆盖了哪些知识点，这个模式完全够用。

优点：零抽帧耗时、零 Image Token 消耗、速度最快。缺点：画面里发生了什么，AI 完全不知道。

实际使用中，我一般把 transcript 作为"初筛模式"——先快速过一遍，如果发现确实需要画面分析，再用 balanced 跑第二遍。

efficient：关键帧，极速但粗糙

efficient 走的是关键帧（I 帧）抽取路线。这里稍微解释一下视频编码的基础概念。

大多数视频不是每一帧都存完整画面的——那样文件会大得离谱。视频编码会把画面分成三种帧：

• I 帧（Intra frame，关键帧）：存完整画面，可以独立解码。类似 JPEG 图片；
• P 帧（Predicted frame，预测帧）：只存和前一帧的差异，需要参考前面的 I 帧或 P 帧才能还原；
• B 帧（Bi-directional predicted frame，双向预测帧）：参考前后帧还原，压缩率最高。

关键帧出现的频率由编码参数 GOP（Group of Pictures） 决定，通常是每 2 到 10 秒一个。efficient 模式直接跳过所有 P 帧和 B 帧，只保留 I 帧，所以帧数天然很少。

优点：极快。因为 ffmpeg 可以在不解码 P 帧和 B 帧的情况下直接定位 I 帧，省去了大量解码计算；缺点：I 帧的分布不由内容决定，可能恰好错过关键画面。比如一个视频在两次 I 帧之间发生了重要的场景切换，efficient 就拍不到。

适用场景：大体浏览、快速判断"这个视频值不值得细看"。

balanced：场景切换检测，日常首选

balanced 是项目的默认推荐档位，也是我日常用得最多的。它不再依赖编码层面的关键帧，而是在内容层面做场景切换检测。

原理是：ffmpeg 内置的 scdet（scene detection）滤镜会逐帧计算相邻两帧之间的像素差异。当差异超过预设阈值时，判定为"场景发生了变化"，触发一次截图。

这个策略的好处是——帧的分布由内容驱动，而不是编码参数驱动。重要画面不容易漏掉，静态画面不会多抽。

从上面的实测数据看：同样 49 分钟视频，balanced 比 efficient 多花约 20 秒处理时间，Image Token 多消耗约一倍，但画面覆盖度显著提升。对于大多数场景——技术分享、产品发布会、教程录屏——这个性价比最高。

token-burner：不设上限，逐帧还原

token-burner 和 balanced 使用同样的场景切换检测引擎，但去掉了帧数上限。它的定位是：当你需要尽可能完整地还原视频画面变化时使用。

比如分析一个 30 秒的短视频广告：镜头切换快、每个画面都是精心设计的。用 token-burner 可以捕获每一次切换，不会漏掉任何一帧。

但要注意：对于长视频，token-burner 可能会抽出大量帧，Token 消耗快速攀升。如果不是真的需要精细到帧级别的分析，日常用 balanced 就行。

只看某个片段怎么操作

很多时候你不需要分析整段视频，只关心其中某个时间段。项目提供了 --start 和 --end 参数来指定时间范围：

# 只看 2 分 15 秒到 2 分 45 秒这 30 秒
/watch https://example.com/video --start 2:15 --end 2:45 这段时间讲了什么？

# 结合画质档位
/watch demo.mp4 --start 1:30 --end 3:00 --detail token-burner 逐帧分析这段画面

这招在做 Bug 定位时特别好用：同事告诉你"大概在 5 分钟左右出了问题"，你就用 --start 4:30 --end 5:30 把范围框出来，不去碰无关片段，省时省 Token。

我的选择经验

折腾了这么多种模式之后，我自己形成了三个档位的使用习惯：

• 日常使用 90% 的情况：balanced。覆盖面够、速度可接受、Token 成本合理；
• 快速初筛：transcript 或 efficient。几秒钟判定这个视频值不值得深入；
• 精细拆解：token-burner + --start/--end。把精力集中在真正需要逐帧分析的关键片段上。

这里没有绝对正确的选项，只有适合你当下场景的选项。多试几次，你很快就能形成自己的判断直觉。

帧去重技术：为什么静态画面不会吃掉你的 Token

抽帧策略解决了"怎么抽"的问题，但还有一个致命漏洞没堵上：相同的画面被重复抽取。

这个问题在屏幕录制类视频里特别严重。想象一个场景：讲师在讲 PPT，一页幻灯片停留了 90 秒。如果按场景切换检测来抽帧——由于画面一直没变，理论上不会触发多次截图。但如果用的是固定间隔抽帧（比如每 3 秒截一张），这 90 秒会产生 30 张几乎一模一样的图。

30 张相同的画面丢给 Claude，30 倍 Token 浪费。

claude-video 默认开启的去重逻辑就是解决这个问题的。

去重算法的工作流程

我把它的去重逻辑翻译成人话：

1. 缩略图化：用 ffmpeg 把每一帧缩成 16×16 像素的灰度缩略图。这个尺寸极小（256 个灰度值），但足以保留画面的亮度分布特征；
2. 逐帧比对：计算当前帧与"上一张被保留的帧"之间的平均像素亮度差异；
3. 阈值判定：差异低于阈值（默认 2.0，范围 0 到 255）就判定为"近重复帧"，直接丢弃；
4. 只保留有变化的帧：只有画面发生了足够明显的改变，才会被保留并送进后续流程。

用伪代码表示会更清晰：

# 帧去重算法的简化伪代码
THRESHOLD = 2.0  # 亮度差异阈值（0-255 范围）
THUMBNAIL_SIZE = (16, 16)  # 缩略图尺寸

def deduplicate_frames(frame_sequence):
    kept_frames = []
    last_kept_thumb = None

    for frame in frame_sequence:
        # 第一步：缩成 16×16 灰度图
        thumb = resize(frame, THUMBNAIL_SIZE).grayscale()

        if last_kept_thumb is None:
            # 第一帧，直接保留
            kept_frames.append(frame)
            last_kept_thumb = thumb
            continue

        # 第二步：计算平均像素亮度差异
        diff = mean_absolute_difference(thumb, last_kept_thumb)

        # 第三步：阈值判定
        if diff > THRESHOLD:
            # 画面变化足够大，保留
            kept_frames.append(frame)
            last_kept_thumb = thumb
        else:
            # 近重复帧，丢弃
            continue

    return kept_frames

一个关键的设计细节

注意第 2 步里比较的对象是"上一张被保留的帧"，而不是"上一帧"。

这个区别很微妙但很重要。假设一段画面在做极其缓慢的渐变（比如日出延时），每一帧和前一帧的差异都极小（0.1），但第 100 帧和第一帧的差异已经很显著了。如果跟"上一帧"比，每一帧都可能因为差异小于阈值而被丢弃——你永远抽不到第 100 帧。但如果跟"上一张被保留的帧"比——也就是第一帧——到了第 100 帧的时候，累积差异就会超过阈值，触发保留。

这个设计保证了缓慢但真实的画面变化不会被误判为静止。

什么时候需要关闭去重

如果你确实需要看到每一帧——哪怕是几乎一样的画面——可以用 --no-dedup 参数关闭去重：

/watch demo.mp4 --detail token-burner --no-dedup 保留所有帧，不去重

但说实话，这个参数我几乎没用到过。正常的视频分析场景，去重都是利大于弊的。

去重对 Token 成本的量化影响

我跑过一个对比测试：一段 15 分钟的技术分享录屏，其中大约 10 分钟是同一页 PPT。不开去重时，balanced 模式抽了 97 帧，其中 60+ 帧是同一页 PPT 的不同时刻——画面几乎完全一样。开启去重后，保留了 35 帧，Token 消耗从约 19000 降到约 7000，减少了 60% 以上的无效消耗。

这个数据因视频而异，但大致规律是：静态画面占比越高，去重的收益越大。如果你的使用场景以 PPT 课程、屏幕录制为主，去重是你省 Token 的最大帮手。

Token 预算管理：长短视频的智能适配

看过前面的章节你可能已经有了一个概念：视频分析这件事，Token 消耗是大头。一段 30 秒短视频可能只花几千 Token，但一段 50 分钟长视频随随便便就能烧掉几万 Token。

claude-video 在 Token 预算管控上做了不少自动化设计，目的是在不牺牲分析质量的前提下，把 Token 消耗压到合理范围。这一章我们来拆解它的 Token 管理策略，以及你可以怎么主动优化。

自动帧预算：视频越长，单位时间帧越少

这是项目内置的最核心的 Token 管控机制。它按照视频时长自动调整帧密度——简单说就是：短视频帧密，长视频帧疏。

具体的分配逻辑（以 balanced 模式为例）：

这个设计的逻辑很直白：一段 30 秒短视频，画面切换快，每一帧都可能承载关键信息，帧密度应该高；一段 1 小时的讲座，大部分时间是同一个机位对着同一个人，画面变化不大，100 帧已经足够覆盖所有重要画面切换。

注意：上面表格里的帧间隔是近似值，实际间隔由 ffmpeg 的场景检测结果决定——画面变化快的地方帧密，画面静止的地方帧疏。不是均匀等距的。

主动控制 Token 消耗的三个手段

除了依赖项目的自动预算管理，你也可以主动做三件事来进一步优化 Token 消耗：

第一，用 --start 和 --end 框定范围。

这可能是最直接有效的省钱手段。长视频不一定需要全量分析——你通常只关心某个片段。把时间窗口框出来，让脚本只处理你真正需要的那部分：

# 只看 10 到 15 分钟这个段落
/watch long-lecture.mp4 --start 10:00 --end 15:00 这部分讲了什么？

# 配合 efficient 模式做快速定位
/watch recording.mp4 --start 3:00 --end 3:30 --detail efficient 这个时间点有没有提到XX？

第二，理性选择画质档位。

绝大多数场景没必要用 token-burner。从我实践下来的经验看：

• 70% 的场景：balanced 足够；
• 25% 的场景：efficient 或 transcript 就够；
• 5% 的场景：才需要 token-burner。

别一上来就开最高档，先问自己"我真的需要看到每一帧吗？"

第三，利用字幕优先机制。

如果视频自带字幕，尽量走字幕路线而非 Whisper 转录。不仅省 API 调用费，字幕的文本量通常也比 Whisper 转录精简——Whisper 会把所有语音都转成文字，包括语气词、重复、口误，这些额外的 Token 对分析质量帮助不大。

不同时长视频的参考成本

这张表给你一个 Token 消耗的参考量级（基于 balanced 模式，720p 视频）：

这些数据是我自己跑了几十个视频后估算的近似值。不同视频（画面复杂度、字幕长度、场景切换频率）的实际消耗会有显著差异，但数量级大致如此。

一个省钱小技巧

如果你经常需要分析同一类视频（比如每天看技术分享），可以做一个"偏好预设"——在自己心里形成一个默认配置。