claude-video：让 Claude 真正"看懂"视频的多模态插件

一、痛点场景：AI 看见了标题，却看不见画面

2026年，Claude 已经能读网页、写代码、分析文档，但你如果丢给它一个 YouTube 链接，它能做的不过是根据标题猜测内容，或者调用一个没有字幕的转录 API——那种转录通常漏掉了画面中 90% 的信息：PPT 上的一行小字、演示者的手势切换、屏幕截图里的 bug 弹窗。

这不是 Claude 的问题，而是 多模态能力的落地缺口。当视频成为知识传播、教程、演示的主流载体时，AI 如果只能处理文字，就相当于一个读过 1000 本书却从未看过一张图片的学者——知识结构完整，但认知严重残缺。

claude-video 正是填补这个缺口的工具。它给 Claude 装上了一双"眼睛"，让 AI 不再靠猜测来理解视频内容。

二、项目起源：一位 AI YouTuber 的实战工具

claude-video 由 Brad Bonanno（@bradbonanno）开发，他是一位专注于 AI 工具应用的 YouTube 内容创作者，同时在 Solaris Automation 公司帮助企业构建 AI 操作系统解决方案。

作为 AI 领域的内容创作者，Brad 每天都要处理大量视频：分析竞品发布会的演示、分析病毒视频的开场钩子、把长视频课程转化为可搜索的笔记。传统的做法是手工播放、手工截图、手工转录——重复性极高，效率极低。

他最初只是想给自己做一个提效工具：在 Claude Code 里敲一个命令，就能自动下载视频、提取关键帧、抓取字幕，然后把完整信息交给 Claude 分析。这个工具经过内部打磨后，于 2026 年 4 月开源，迅速在开发者社区传播。2026年7月，项目登顶 GitHub Trending Python 榜单，引发广泛关注。

三、核心功能：一条命令，视频全部分解

claude-video 的使用方式极为简洁。在 Claude Code（或 Claude.ai）里粘贴一行命令：

/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?

Claude 会自动完成以下步骤：下载视频 → 提取关键帧 → 获取字幕 → 读取每一帧图像 → 综合分析并回答。

这背后的完整流程如下：

第一步：字幕优先策略（节省 token）

工具首先通过 yt-dlp 检查视频是否有字幕轨道。若有，优先使用原生字幕（YouTube 自动字幕或上传者手动添加的字幕），完全无需付费 API。这一步在有字幕的情况下只需约 4.5 秒，零 token 开销。

第二步：按需下载视频

若需要画面帧，或视频无字幕，则下载视频的最低质量版本（仅音频用于 Whisper 转录），避免浪费带宽。49 分钟的 720p 视频下载约 76 MB，需时约 37 秒。

第三步：智能抽帧（帧预算机制）

这是 claude-video 最核心的技术决策——按视频时长动态分配帧数，而非固定帧率：

视频时长	默认帧预算	设计意图
≤30 秒	~30 帧	密集覆盖，关键帧全覆盖
30秒–1分钟	~40 帧	保持密度
1–3 分钟	~60 帧	舒适覆盖
3–10 分钟	~80 帧	稀疏扫描
>10 分钟	100 帧（上限）	触发警告，建议聚焦重跑

抽帧策略有四档可选：

efficient（高效模式）：仅提取 I-frame（关键帧），速度最快（约 0.5 秒），但可能遗漏场景切变。适合快速粗扫。
balanced（平衡模式）：基于场景切变检测（scene-change detection），自动寻找镜头切换点，优先保留内容变化的帧。默认选项。
token-burner（烧 token 模式）：取消帧数上限，保留所有场景切变帧。适合超长视频或需要完整覆盖的场景。
transcript（纯字幕模式）：不提取任何帧，仅用字幕。免费、极速（~4.5秒），适合已知有字幕的长视频。

所有帧模式下均有帧去重机制：将每帧缩放到 16×16 灰度缩略图，计算与上一保留帧的像素亮度差异。若差异 ≤2.0（极低阈值），判定为近重复帧并丢弃。这解决了静态屏幕录制（PPT 长时间不动）或淡入淡出导致的帧冗余问题，避免浪费 token。

第四步：Whisper 转录（兜底方案）

若视频无字幕，自动提取音频（16kHz 64kbps 单声道 MP3，约 480KB/分钟），调用 Whisper API 转写为带时间戳的文本。

Whisper 后端支持两套方案：

Groq API（推荐）：运行 whisper-large-v3，速度快、费用低，Groq 免费额度充足
OpenAI Whisper API（备用）：标准定价，兼容性更好

由于音频被切成 ~480KB/分钟的极小片段，即使 60 分钟视频也能在 25MB API 上传限制内分块处理。整个转录过程完全用 Python 标准库实现，无需 pip install groq 或 pip install openai。

第五步：帧 + 字幕交给 Claude

最终，工具将帧路径（含时间戳标记）和格式化后的字幕打印给 Claude，Claude 通过内置的 Read 工具逐帧读取图像，然后将视觉信息与音频文本综合，生成真正"基于画面内容"的回答。

四、典型使用场景

场景1：竞品分析
粘贴竞品发布会视频 URL，询问"他们的开场钩子是什么？与去年相比有哪些变化？"——Claude 逐帧分析画面构图、演示者表情变化、PPT 内容，输出结构化的竞品分析报告，而不仅仅是视频标题的摘要。

场景2：Bug 诊断
同事发来一段录屏，说"这里出了问题"。用 /watch bug-repro.mov what's going wrong? 丢给 Claude——它能定位到具体出错帧，描述屏幕上发生了什么，甚至在 UI 还未弹出错误提示时就发现异常操作。

场景3：视频笔记化
将系列课程视频批量跑一遍，每个视频输出摘要笔记。频道变成可搜索的笔记库，无需逐一播放拖进度条。

场景4：去伪存真
面对 10 分钟的"革命性产品发布"视频，直接问"skip the hype，告诉我实际上新在哪里"——Claude 提取关键帧和字幕，剥去营销话术，直击产品实质。

五、架构解析：插件化设计的精妙之处

claude-video 并非一个独立应用，而是一个 Agent Skill（技能插件），遵循 Agent Skills 标准接口，可以部署到 Claude Code、Codex、Cursor、Copilot、Gemini CLI 等 50+ AI 编程/对话平台。

项目结构如下：

skills/watch/
├── SKILL.md              # 跨平台技能合约，定义 /watch 命令接口
└── scripts/
    ├── watch.py          # 入口编排：下载→帧→字幕→报告
    ├── download.py        # yt-dlp 封装 + 字幕抓取
    ├── frames.py         # ffmpeg 封装 + 场景检测 + 去重 + 抽帧
    ├── transcribe.py     # VTT 解析 + 滚动字幕去重
    ├── whisper.py         # Groq/OpenAI Whisper API 客户端（纯标准库）
    ├── config.py          # ~/.config/watch/.env 配置管理
    └── setup.py          # 首次运行引导：依赖检测 + API key 脚手架

关键设计亮点：

纯标准库依赖：whisper.py 中所有 HTTP 请求均使用 urllib.request，JSON 解析用 json，无需任何第三方 pip 包。这使得安装极为轻量，降低了与不同 Python 环境的兼容风险。
setup.py 的静默优先策略：首次运行检查（--check）在一切正常时完全静默（零输出，exit 0），只有发现问题才介入引导。这保证了 AI Agent 的对话流畅性，不会被"安装成功"的提示打断思路。
帧抽帧算法：frames.py 使用 ffmpeg 的场景切变检测（scdetect 逻辑等价实现），通过两轮解码：第一轮找场景切变点，第二轮在切变区间内均匀采样，始终保证首帧和末帧必保留。
跨平台路径兼容：download.py 对 Windows/macOS/Linux 的路径格式做了适配，is_url() 函数处理了以 - 开头的本地路径不会被误判为 URL 的边界情况。

六、安装与上手：零配置即用

claude-video 支持多种安装方式，对普通用户最友好的是：

Claude Code 用户（推荐）：

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

然后直接 /watch <url> 使用。

其他 Agent 平台：

npx skills add bradautomates/claude-video -g   # 全局安装

claude.ai 网页版： 下载最新 release 中的 watch.skill 文件，在 Settings → Capabilities → Skills 中上传。

首次运行，setup.py 会自动检测 ffmpeg 和 yt-dlp 是否安装：

macOS：自动执行 brew install ffmpeg yt-dlp
Linux：打印 apt / dnf / pipx 安装命令
Windows：打印 winget / pip 命令

API key（Whisper 用）非必须——有字幕的视频完全免费。只有本地文件或无字幕视频才需要 Groq 或 OpenAI key，首次运行会自动引导生成 ~/.config/watch/.env 配置文件。

七、争议与局限：不回避的问题

Token 成本问题：长视频场景切变模式下，token-burner 可能提取数百帧，每帧约 197 个 token（512px 宽度下）。10 分钟无字幕视频若开启全帧模式，可能消耗数十千 token。这需要用户主动管理帧预算。

长视频准确性问题：超过 10 分钟的视频在 balanced 模式（100 帧上限）下，帧密度变稀，工具会打印"sparse scan"警告并建议用户用 --start/--end 参数聚焦特定片段。这是诚实的工程权衡，而非 bug。

本地 Whisper 的演进：GitHub PR 中已有人在推进本地 Whisper 后端（whisper.cpp / mlx），未来可在 macOS 上利用 Metal GPU 加速实现完全离线的语音转写，脱离 API 依赖。这将是重要的能力补全。

版权与隐私：自动下载和分析视频内容需遵守各平台服务条款，YouTube 视频分析供个人学习研究使用通常无问题，但批量爬取或商业应用需自行评估法律风险。

八、行业意义与增长曲线

claude-video 的出现代表了 AI Agent 工具生态的一个趋势：从"能做什么"到"能感知什么"的能力延伸。当 AI Agent 能读取网页、运行脚本、操作文件之后，视觉感知（视频帧）成为最后一个缺口。

项目自 2026 年 4 月底创建，到 7 月初已积累近 6000+ stars，在 GitHub Trending Python 榜单登顶。其增长主要来自：

Claude Code 用户群的自然扩散（Claude Code 本身有数十万用户）
AI 内容创作者社区的分享与教程视频
被纳入多个"必备 Claude Code 插件"推荐列表

作为 Agent Skills 生态的一部分，claude-video 的插件化设计意味着它可以随着底层 Agent 平台的能力升级而自动受益——当 Claude 原生支持视频理解时，这一插件的价值将演变为更高效的专用工作流编排工具。

技术规格

指标	值
主要语言	Python
最低依赖	ffmpeg、yt-dlp、Python 3.8+
Whisper	Groq API（推荐）或 OpenAI API
许可证	MIT
支持平台	Claude Code、Codex、Cursor、Copilot、Gemini CLI 等 50+
帧处理	ffmpeg（I-frame / scene-change / uniform 三种模式）
Token 估算	每帧约 197 token（512px 宽）
无字幕视频处理	自动切换 Whisper API 转录

项目地址：https://github.com/bradautomates/claude-video
作者：Brad Bonanno (@bradbonanno)
Star History 由 star-history.com 提供

Brad Bonanno

图1：claude-video 作者 Brad Bonanno 头像

claude-video：让 Claude 真正"看懂"视频的多模态插件

一、痛点场景：AI 看见了标题，却看不见画面

claude-video 正是填补这个缺口的工具。它给 Claude 装上了一双"眼睛"，让 AI 不再靠猜测来理解视频内容。

二、项目起源：一位 AI YouTuber 的实战工具

三、核心功能：一条命令，视频全部分解

claude-video 的使用方式极为简洁。在 Claude Code（或 Claude.ai）里粘贴一行命令：

/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?

Claude 会自动完成以下步骤：下载视频 → 提取关键帧 → 获取字幕 → 读取每一帧图像 → 综合分析并回答。

这背后的完整流程如下：

第一步：字幕优先策略（节省 token）

第二步：按需下载视频

若需要画面帧，或视频无字幕，则下载视频的最低质量版本（仅音频用于 Whisper 转录），避免浪费带宽。49 分钟的 720p 视频下载约 76 MB，需时约 37 秒。

第三步：智能抽帧（帧预算机制）

这是 claude-video 最核心的技术决策——按视频时长动态分配帧数，而非固定帧率：

视频时长	默认帧预算	设计意图
≤30 秒	~30 帧	密集覆盖，关键帧全覆盖
30秒–1分钟	~40 帧	保持密度
1–3 分钟	~60 帧	舒适覆盖
3–10 分钟	~80 帧	稀疏扫描
>10 分钟	100 帧（上限）	触发警告，建议聚焦重跑

抽帧策略有四档可选：

efficient（高效模式）：仅提取 I-frame（关键帧），速度最快（约 0.5 秒），但可能遗漏场景切变。适合快速粗扫。
balanced（平衡模式）：基于场景切变检测（scene-change detection），自动寻找镜头切换点，优先保留内容变化的帧。默认选项。
token-burner（烧 token 模式）：取消帧数上限，保留所有场景切变帧。适合超长视频或需要完整覆盖的场景。
transcript（纯字幕模式）：不提取任何帧，仅用字幕。免费、极速（~4.5秒），适合已知有字幕的长视频。

第四步：Whisper 转录（兜底方案）

若视频无字幕，自动提取音频（16kHz 64kbps 单声道 MP3，约 480KB/分钟），调用 Whisper API 转写为带时间戳的文本。

Whisper 后端支持两套方案：

Groq API（推荐）：运行 whisper-large-v3，速度快、费用低，Groq 免费额度充足
OpenAI Whisper API（备用）：标准定价，兼容性更好

第五步：帧 + 字幕交给 Claude

四、典型使用场景

场景3：视频笔记化
将系列课程视频批量跑一遍，每个视频输出摘要笔记。频道变成可搜索的笔记库，无需逐一播放拖进度条。

五、架构解析：插件化设计的精妙之处

项目结构如下：

skills/watch/
├── SKILL.md              # 跨平台技能合约，定义 /watch 命令接口
└── scripts/
    ├── watch.py          # 入口编排：下载→帧→字幕→报告
    ├── download.py        # yt-dlp 封装 + 字幕抓取
    ├── frames.py         # ffmpeg 封装 + 场景检测 + 去重 + 抽帧
    ├── transcribe.py     # VTT 解析 + 滚动字幕去重
    ├── whisper.py         # Groq/OpenAI Whisper API 客户端（纯标准库）
    ├── config.py          # ~/.config/watch/.env 配置管理
    └── setup.py          # 首次运行引导：依赖检测 + API key 脚手架

关键设计亮点：

纯标准库依赖：whisper.py 中所有 HTTP 请求均使用 urllib.request，JSON 解析用 json，无需任何第三方 pip 包。这使得安装极为轻量，降低了与不同 Python 环境的兼容风险。
setup.py 的静默优先策略：首次运行检查（--check）在一切正常时完全静默（零输出，exit 0），只有发现问题才介入引导。这保证了 AI Agent 的对话流畅性，不会被"安装成功"的提示打断思路。
帧抽帧算法：frames.py 使用 ffmpeg 的场景切变检测（scdetect 逻辑等价实现），通过两轮解码：第一轮找场景切变点，第二轮在切变区间内均匀采样，始终保证首帧和末帧必保留。
跨平台路径兼容：download.py 对 Windows/macOS/Linux 的路径格式做了适配，is_url() 函数处理了以 - 开头的本地路径不会被误判为 URL 的边界情况。

六、安装与上手：零配置即用

claude-video 支持多种安装方式，对普通用户最友好的是：

Claude Code 用户（推荐）：

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

然后直接 /watch <url> 使用。

其他 Agent 平台：

npx skills add bradautomates/claude-video -g   # 全局安装

claude.ai 网页版： 下载最新 release 中的 watch.skill 文件，在 Settings → Capabilities → Skills 中上传。

首次运行，setup.py 会自动检测 ffmpeg 和 yt-dlp 是否安装：

macOS：自动执行 brew install ffmpeg yt-dlp
Linux：打印 apt / dnf / pipx 安装命令
Windows：打印 winget / pip 命令

七、争议与局限：不回避的问题

八、行业意义与增长曲线

项目自 2026 年 4 月底创建，到 7 月初已积累近 6000+ stars，在 GitHub Trending Python 榜单登顶。其增长主要来自：

Claude Code 用户群的自然扩散（Claude Code 本身有数十万用户）
AI 内容创作者社区的分享与教程视频
被纳入多个"必备 Claude Code 插件"推荐列表

技术规格

指标	值
主要语言	Python
最低依赖	ffmpeg、yt-dlp、Python 3.8+
Whisper	Groq API（推荐）或 OpenAI API
许可证	MIT
支持平台	Claude Code、Codex、Cursor、Copilot、Gemini CLI 等 50+
帧处理	ffmpeg（I-frame / scene-change / uniform 三种模式）
Token 估算	每帧约 197 token（512px 宽）
无字幕视频处理	自动切换 Whisper API 转录

项目地址：https://github.com/bradautomates/claude-video
作者：Brad Bonanno (@bradbonanno)
Star History 由 star-history.com 提供

Brad Bonanno

图1：claude-video 作者 Brad Bonanno 头像

claude-video

社区活跃度

claude-video：让 Claude 真正"看懂"视频的多模态插件

一、痛点场景：AI 看见了标题，却看不见画面

二、项目起源：一位 AI YouTuber 的实战工具

三、核心功能：一条命令，视频全部分解

第一步：字幕优先策略（节省 token）

第二步：按需下载视频

第三步：智能抽帧（帧预算机制）

第四步：Whisper 转录（兜底方案）

第五步：帧 + 字幕交给 Claude

四、典型使用场景

五、架构解析：插件化设计的精妙之处

六、安装与上手：零配置即用

七、争议与局限：不回避的问题

八、行业意义与增长曲线

技术规格

社区活跃度

claude-video：让 Claude 真正"看懂"视频的多模态插件

一、痛点场景：AI 看见了标题，却看不见画面

二、项目起源：一位 AI YouTuber 的实战工具

三、核心功能：一条命令，视频全部分解

第一步：字幕优先策略（节省 token）

第二步：按需下载视频

第三步：智能抽帧（帧预算机制）

第四步：Whisper 转录（兜底方案）

第五步：帧 + 字幕交给 Claude

四、典型使用场景

五、架构解析：插件化设计的精妙之处

六、安装与上手：零配置即用

七、争议与局限：不回避的问题

八、行业意义与增长曲线

技术规格