返回
发布于 2026-07-28 23:50 · 68 次阅读

claude-video：补齐Claude视频短板，一键让AI看懂任意视频

claude-video：补齐Claude视频短板，一键让AI看懂任意视频

一、项目背景：Claude原生无法理解视频的痛点

Claude拥有极强的文本、代码、图片解析能力，能读取网页、解析仓库、处理文档，但存在一个核心短板：原生不支持视频理解。
日常使用中，如果你直接丢一条YouTube、TikTok链接给Claude，它只能依靠页面标题、简介或残缺字幕推测内容，画面里的关键信息——代码演示、界面报错、PPT文字、镜头画面、产品操作流程都会完全丢失，回答经常脱离视频真实画面，参考价值极低。

开源项目 bradautomates/claude-video 正是为解决该痛点而生，由开发者Brad Bonanno打造，是一款面向Claude全生态的Agent Skill插件，提供统一/watch指令，让AI同时读取视频画面帧+时间轴字幕，真正做到“看完视频再回答”。
项目2026年上线后快速爆火，GitHub星标突破7000+，支持Claude Code、Cursor、Codex、Copilot、claude.ai网页端等50+AI开发环境，开源协议为MIT可自由商用、二次开发，当前最新稳定版v0.2.0（2026-07-01发布）。

二、核心工作原理：全自动视频预处理流水线

整个流程无需人工干预，执行/watch命令后自动完成7步处理，全程本地运行，仅转录环节可选调用第三方API

  1. 资源拉取：接收YouTube/TikTok/Loom/X/Instagram/Vimeo等数百平台链接，或本地mp4/mov/mkv视频文件；优先读取平台自带免费字幕，无字幕再下载视频素材。
  2. 视频下载：基于yt-dlp仅下载任务所需片段，不完整下载全视频，节省带宽与存储。
  3. 智能抽帧（ffmpeg驱动）

提供4档细节模式，自动控制帧数量平衡速度与Token消耗

  • transcript：仅字幕，0帧，极速免费，适合纯音频内容；
  • efficient：仅提取关键帧，上限50帧，0.5秒极速解析；
  • balanced（默认）：场景切换抽帧，上限100帧，兼顾画面完整度；
  • token-burner：无帧上限，完整捕捉所有镜头变化，适合精细分析。
  1. 帧去重优化：自动对比画面亮度差值，过滤长时间静止幻灯片、录屏重复画面，避免浪费图片Token，大幅降低模型开销。
  2. 音频转录：双方案兜底
  • 免费方案：平台原生字幕，带精准时间戳；
  • 付费兜底：提取16kHz单声道音频，调用Groq Whisper-Large-v3（低成本高速）或OpenAI Whisper-1生成字幕。
  1. 素材对齐：将每一帧画面、每一段字幕绑定统一时间戳，打包交付Claude。
  2. AI多模态解读：Claude并行读取所有帧图片+时序字幕，结合画面与音频信息输出答案，而非单纯文字猜测；执行结束自动清理临时缓存文件。

三、核心功能亮点

1. 全平台兼容，多环境一键安装

覆盖绝大多数主流AI开发客户端，四种部署方式按需选择

（1）Claude Code（推荐，支持自动更新）

/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video
# 更新插件
/plugin update watch@claude-video

（2）Cursor/Codex/Gemini CLI等50+Agent工具

# -g 全局安装，所有项目通用；移除-g仅当前项目生效
npx skills add bradautomates/claude-video -g
# 更新
npx skills update watch -g

（3）claude.ai网页端

  1. Releases页面下载watch.skill安装包；
  2. 网页设置 → Capabilities → Skills上传文件；
  3. 提前开启「代码执行与文件读写」权限（依赖ffmpeg、yt-dlp命令行工具）。

（4）开发者手动部署

git clone https://github.com/bradautomates/claude-video.git
# 软链接到对应工具技能目录
ln -s "$(pwd)/claude-video/skills/watch" ~/.claude/skills/watch

2. 零配置开箱即用，自动补全依赖

首次运行/watch自动检测本机ffmpeg、yt-dlp

  • macOS：自动调用Homebrew一键安装；
  • Linux：输出apt/dnf/pipx安装指令；
  • Windows：提供winget/pip部署命令；

仅无内置字幕的视频，才需要配置Groq/OpenAI密钥，写入~/.config/watch/.env，其余场景完全免费使用。

3. 精细化参数控制，灵活平衡成本与精度

基础通用指令示例

# 全局视频提问
/watch https://youtu.be/xxx 总结视频核心内容
/watch ./bug录屏.mov 视频中UI在哪一帧出现报错？
# 限定时间区间（高密度抽帧，减少无用画面）
/watch https://vimeo.com/xxx --start 01:30 --end 02:00 这段讲解了什么工具？
# 指定关键时间点单独提取画面
/watch 视频.mp4 --timestamps 10,30,1:20 这三个画面分别展示了什么？

常用调参标识

  • --detail：切换解析精度模式；
  • --resolution 1024：提升帧分辨率，适配代码、小字PPT识别；
  • --max-frames N：手动限制最大帧数量，控制Token开销；
  • --no-whisper：关闭语音转录，仅靠画面分析；
  • --no-dedup：关闭重复帧过滤，保留全部画面。

4. 智能Token预算机制，避免上下文溢出

工具内置时长-帧数量自动分配规则，防止长视频一次性消耗大量图片Token

视频时长默认帧上限适用场景
≤30秒~30帧短广告、演示片段
30秒-1分钟~40帧短视频、功能演示
1-3分钟~60帧产品短讲解
3-10分钟~80帧教程、发布会片段
>10分钟100帧（封顶）长课程、完整录屏

超过10分钟会提示「稀疏扫描」，推荐搭配--start/--end截取关键片段分析，兼顾精度与成本。

四、五大高频实用场景

1. 开发排查：录屏Bug自动诊断

研发、测试人员收到故障复现录屏，无需手动拖动进度条

/watch bug-record.mov 界面异常出现在哪个时间点，具体现象是什么？

Claude定位报错帧，描述界面元素、操作流程，快速定位前端/交互问题，大幅缩短调试时间。

2. 内容创作：竞品视频拆解分析

短视频、自媒体、广告从业者分析爆款脚本、发布会宣传内容

/watch 竞品爆款视频链接 视频前10秒用了什么开场钩子，整体结构如何设计？

自动剥离营销话术，提炼真实产品卖点、镜头节奏、文案逻辑。

3. 学习提效：长教程视频生成结构化笔记

几十分钟编程、技术分享视频，无需完整观看，一键输出可检索文档

/watch 技术教程链接 把视频知识点整理成分点笔记，标注关键操作时间点

批量处理课程播放列表，快速搭建知识库。

4. 素材解析：广告、直播、播客信息提取

分析直播回放、广告片、播客视频，提取工具清单、数据、核心观点；支持Loom工作录屏、Instagram短视频等小众平台。

5. 文档生产：发布会/更新视频提炼干货

过滤大量渲染、铺垫话术，只输出真实功能更新、技术参数、迭代改动，适合产品、运营快速整理资讯。

五、项目技术架构

仓库采用模块化解耦设计，核心能力全部收敛于skills/watch独立技能包，可直接复制部署，目录结构

claude-video/
├── skills/watch/          # 核心独立技能（所有安装器复制此目录）
│   ├── SKILL.md           # 跨平台统一技能契约
│   └── scripts/           # 完整执行脚本
│       ├── watch.py       # 入口主程序，调度全流程
│       ├── download.py    # yt-dlp视频下载封装
│       ├── frames.py      # ffmpeg抽帧、去重、分辨率处理
│       ├── transcribe.py  # 字幕解析、时间轴对齐
│       ├── whisper.py     # Groq/OpenAI转录客户端
│       ├── config.py      # 本地密钥配置管理
│       └── setup.py       # 环境依赖自动安装检测
├── tests/                 # pytest自动化测试套件
├── .github/workflows/     # CI自动打包发布.skill安装包
├── hooks/                 # Claude Code会话启动钩子
└── 各类插件配置文件（适配Codex/Claude Marketplace）

项目代码占比：Python 94.9%、Shell脚本5.1%，轻量无重型依赖，Windows/macOS/Linux全平台兼容。

六、优缺点总结

优势

  1. 低成本：自带字幕模式完全免费，仅无字幕视频需少量Whisper API费用；
  2. 本地预处理：视频下载、抽帧、去重全部本地执行，不泄露原始视频文件；
  3. 多端全覆盖：网页端、本地IDE、各类AI开发工具统一一套/watch指令；
  4. Token优化：帧去重、时长预算、分段采样三重控制，大幅降低图像Token消耗；
  5. 开源免费：MIT协议，无商用限制，支持自定义二次开发、新增平台适配；
  6. 上手极简：无需复杂配置，一条命令完成安装与调用。

局限

  1. 超长视频（10分钟以上）默认稀疏抽帧，精细分析需手动截取时间段；
  2. 无内置本地Whisper模型，纯离线场景必须关闭转录功能，仅靠画面分析；
  3. 依赖本地ffmpeg、yt-dlp环境，云端无命令行权限的AI环境无法使用。

七、最后

在AI Agent普及的当下，文本、代码、图片处理能力已经成熟，但视频一直是主流大模型的薄弱环节。claude-video没有选择复杂的云端视频转码方案，而是依托成熟开源工具（yt-dlp、ffmpeg、Whisper）构建轻量化本地预处理层，用极低成本补齐Claude视频理解能力。

无论是程序员排查录屏Bug、内容创作者拆解竞品视频，还是学习者快速消化长教程，/watch一条指令就能省去手动下载、截图、转录、逐帧查看的重复工作，是面向Claude生态极具实用价值的开源工具。

项目地址：https://github.com/bradautomates/claude-video