一天一个开源项目

开源项目第190期：claude-video — 给 Claude 装上「眼睛」看视频，一条命令分析 YouTube/Loom/本地视频，字幕优先零下载、场景感知帧去重、Token 预算自动管理

Brad Bonanno 出品的 Claude Code 技能插件，通过 /watch 命令让 Claude 分析任意视频。7 步流水线：yt-dlp 下载→ffmpeg 提取帧→Whisper 转录→送入 Claude 上下文。字幕优先优化（有字幕直接用，零下载）、16×16 缩略图 MAD 算法帧去重、按视频时长自动调整帧预算。四档精度模式：transcript/efficient/balanced/token-burner。支持 Claude Code、Codex、Cursor、Copilot、Gemini CLI 等 50+ Agent 宿主。15.2k Stars，MIT。

·约 7 分钟阅读·AI Tools
open-sourceclaude-codeskillvideo-analysisyt-dlpffmpegwhispermultimodaltoken-optimizationAI-agent

引言

"Claude 能读代码、能分析图片，唯独看不了视频——直到这个工具出现。"

这是「每日一个开源项目」系列的第 190 篇。今天的项目是 claude-video —— Brad Bonanno（Solaris Automation）开源的 Claude 技能插件，核心命令是 /watch，让 Claude 真正能"看"视频并回答关于视频内容的任何问题。

/watch https://youtube.com/watch?v=xxx  这个演讲的核心论点是什么？
/watch bug-repro.mov  视频里发生了什么错误？
/watch 产品Demo.mp4  提取所有功能点并整理成列表

15,200 颗 Star，MIT 许可。

你会学到什么

  • 7 步视频分析流水线的技术设计
  • 字幕优先策略：为什么这个设计决策大幅降低成本
  • 帧去重的 MAD 算法：16×16 缩略图如何捕捉慢速渐变
  • Token 预算自动管理：按视频时长动态调整帧数
  • 四档精度模式和参数控制
  • 在 Claude Code 和其他 Agent 宿主上的安装方式

前提知识

  • 用过 Claude Code 或类似 AI 编程 Agent
  • 了解基本的视频概念（帧、转录）
  • 不需要了解 Python 或 ffmpeg

问题背景

Claude 支持图片输入，但原生不支持视频。视频文件太大，不能直接塞进上下文；就算能塞，没有转录文本的纯帧序列也会损失大量信息。

现有的"让 AI 看视频"方案通常是：全量下载 → 固定 fps 均匀采样 → 全部帧送给模型。这种方案有三个问题：

  • 浪费 Token：一段静止画面会产生大量重复帧，每帧都占 Token
  • 忽略音频：没有转录文本，演讲内容、对白、说明全部丢失
  • 成本不可控：50 分钟视频固定 fps 采样可能产生数百张图片

claude-video 的方案在每个环节都有针对性的优化。

7 步流水线

视频 URL / 本地路径
    ↓ [1] yt-dlp 尝试获取字幕
    ↓ [2] 有字幕？直接用，跳过下载
    ↓ [3] 无字幕？下载视频，ffmpeg 提取帧
    ↓ [4] MAD 算法去重，场景变化感知
    ↓ [5] Whisper 转录音频（Groq 优先）
    ↓ [6] 帧 + 转录文本送入 Claude 上下文
    ↓ [7] Claude 回答，清理临时文件

关键优化 1：字幕优先，零下载

很多视频平台（YouTube 尤其如此）有原生字幕或 CC 字幕。yt-dlp 在下载视频之前会先尝试获取字幕文件。

如果获取到了字幕：

  • 不下载视频，不提取帧，不调用 Whisper
  • 解析 VTT 字幕文件，直接作为转录文本
  • 整个流程从 37 秒（下载 76MB 视频）缩短到 4.5 秒

一段 49 分钟的 YouTube 视频，transcript 模式只需 4.5 秒，Token 消耗接近零。

关键优化 2：场景感知帧提取

不是按固定 fps 均匀采样，而是检测场景变化——只在画面内容真正发生变化时才取帧。

技术实现：

  1. ffmpeg 先输出原始帧序列
  2. 每帧缩至 16×16 灰度缩略图（标准库实现，不需要 Pillow 等额外依赖）
  3. 计算当前帧与上一个被保留帧的平均绝对差值（MAD，0~255）
  4. MAD ≤ 2.0：认为是近重复帧，丢弃
  5. 帧预算上限在去重之后才生效

有一个设计细节值得注意：和"上一个保留帧"比，而不是和"上一帧"比。

这个区别处理的是慢速渐变：

帧A → 帧B → 帧C → 帧D（场景完全切换）
 
帧A vs 帧B：MAD = 0.5（很相似，B 丢弃）
帧A vs 帧C：MAD = 1.0（还是相似，C 丢弃）
帧A vs 帧D：MAD = 8.0（变化显著，D 保留）

如果和"上一帧"比，帧 B、C、D 每帧只和前一帧比较，慢速淡出每步差值都很小，直到最后一帧才超阈值。和"上一个保留帧"比，累计差值会随时间增大，最终正确捕捉到场景切换。

Token 预算自动管理

帧数不是固定的，按视频时长自动调整：

视频时长默认帧预算
≤ 30 秒~30 帧
30 秒 ~ 1 分钟~40 帧
1 ~ 3 分钟~60 帧
3 ~ 10 分钟~80 帧
> 10 分钟100 帧（上限模式）

每帧的 Token 估算公式：(宽 × 高) / 750。默认 512px 宽的图片，每帧约 197 个 Token。100 帧 ≈ 约 20,000 Token 的视觉输入，加上转录文本，在可控范围内。

超过 10 分钟的视频触发"稀疏扫描"警告，提示用户用 --start/--end 聚焦到感兴趣的时间段。

四档精度模式

通过 --detail 参数控制：

模式帧数上限速度适合场景
transcript0 帧~4.5 秒演讲、播客、纯语音内容
efficient50 帧~0.5 秒快速预览，了解大概
balanced（默认）100 帧~21 秒日常使用均衡点
token-burner无上限~21 秒完整覆盖，不在乎成本
# 快速摘要一个演讲（只要字幕，不要帧）
/watch talk.mp4 --detail transcript  总结核心论点
 
# 快速扫一眼一个视频
/watch demo.mp4 --detail efficient  有什么功能？
 
# 分析 bug 录屏，需要完整帧信息
/watch bug.mov --detail token-burner  发生了什么错误？

聚焦模式

对长视频，可以只分析某个时间段，帧密度更高，成本更低：

# 只看 5:30 到 8:00 之间的内容
/watch lecture.mp4 --start 5:30 --end 8:00  这段讲了什么？
 
# 精确时间戳抓帧（适合分析特定截图）
/watch product.mp4 --timestamps 1:20,3:45,6:10  这三个时刻各显示了什么？
 
# 提高分辨率（读屏幕上的文字时需要）
/watch screen-recording.mov --resolution 1024  读取代码内容

支持的视频来源

通过 yt-dlp，支持 50+ 平台：YouTube、Loom、TikTok、X（Twitter）、Instagram、Bilibili、Vimeo 等。

也支持本地文件：.mp4、.mov、.mkv、.webm。

安装

Claude Code（最简单）：

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

Codex / Cursor / GitHub Copilot / Gemini CLI 等：

npx skills add bradautomates/claude-video -g

claude.ai 网页版： 下载 watch.skill 文件，在设置 → 功能 → 技能里上传。

首次运行自动检测并安装系统依赖：

  • macOS：通过 brew 自动安装 yt-dlp 和 ffmpeg
  • Linux：打印对应的 apt / dnf 命令
  • Windows：打印 winget 命令

API Key 配置

能力需要费用
下载 + 原生字幕无需 API key免费
Whisper 转录（首选）Groq API Key极低价，极快
Whisper 转录（备选）OpenAI API Key标准定价
禁用转录--no-whisper免费，仅帧

没有 Groq / OpenAI key 的情况下，用 --no-whisper 仍然可以分析视频画面内容，只是没有语音转录。

典型使用场景

竞品分析：

/watch 竞品产品Demo.mp4  列出所有功能点和界面设计特点

Bug 诊断：

/watch bug-repro.mov  描述错误发生的完整过程，界面上显示了什么

视频笔记：

/watch 培训视频.mp4 --detail balanced  提取关键知识点，整理成带时间戳的笔记

内容去水分：

/watch 广告视频.mp4 --detail transcript  去掉营销用语，提取实质信息

项目地址与资源

总结

claude-video 的技术设计体现了一个好的工程判断：在每个环节找到最低成本的路径，而不是暴力解决问题。

字幕优先把最常见场景（有字幕的 YouTube 视频）的成本压到接近零；MAD 帧去重消除了静止画面的冗余 Token；按时长动态调整帧预算让短视频密集覆盖、长视频不超限。这三个优化叠加起来，使得它的实际 Token 消耗比"固定 fps 采样"方案低一个数量级。

15,200 Stars 的增长速度说明"让 AI 看视频"是一个真实需求，而不是 demo 项目。支持 50+ Agent 宿主的多平台设计，也说明作者认真考虑过生态兼容性。

探索 PrimeSkills —— 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。

← 返回博客列表