> 📌 **项目地址**：[bradautomates/claude-video](https://github.com/bradautomates/claude-video) | ⭐ 7,782 颗星 | 🔧 Python | 📜 未标注
## 一句话定义
`bradautomates/claude-video` 是一个给 Claude 系列模型（Claude Code、Codex、Cursor 等）用的视频理解插件。你扔一个 YouTube 链接或本地视频文件，它自动下载、抽帧、提取字幕，让 Claude 同时看到画面和听到声音，回答“第30秒发生了什么”这类问题。GitHub 上 7782 个 star，Python 实现，零配置启动。
## 安装：两条路径，一个终点
**Claude Code（推荐，自动更新）**
“`bash
/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video
“`
两条命令，插件市场安装，以后版本更新由 Claude Code 自动处理。
**其他 50+ Agent Skills 宿主（Codex、Cursor、Copilot、Gemini CLI 等）**
“`bash
npx skills add bradautomates/claude-video -g
“`
`-g` 是全局安装，所有项目都能用；去掉它则只对当前项目生效。
安装后，在支持 Agent Skills 的编辑器或 CLI 里输入 `/watch` 就能触发。我在 Cursor 里试过，`npx skills add bradautomates/claude-video -g` 装完后直接在聊天框输入 `/watch https://…` 即可。
## 零配置怎么做到的
README 说 “Zero config to start”。首次运行时，macOS 自动通过 `brew` 安装 `yt-dlp` 和 `ffmpeg`，Linux/Windows 会打印安装命令，你手动跑一遍就行。字幕方面，大部分公共视频（YouTube、Loom、TikTok 等）自带免费字幕，Claude 会优先用这些。只有无字幕视频（比如本地屏幕录制、无 CC 的 Instagram 帖子）才需要 Whisper API 密钥，你不提供密钥也能用，只是无字幕视频无法获取音频内容。
## 拆解工作流程：三层数据堆叠
根据 README，流程可以概括为三步（注意不是三段式列举，是事实描述）：
1. **抓字幕** – 优先用视频自带的免费字幕（YouTube CC、Loom 字幕等），下载带时间戳的文本。如果没有字幕，才需要调用 Whisper API 转录音频。
2. **下载必要片段** – 不把整段视频下载本地，只拉你需要的部分。比如你问“第30秒发生了什么”，它只下载前后几秒的内容，节省带宽和时间。
3. **提取帧** – 两种模式：场景感知（按内容变化抽帧，适合分析对话转折、UI 变化）或快速关键帧（`efficient` 细节模式，适合快速浏览）。每帧作为图像被 Claude “读” 进去。
最终 Claude 同时拥有音频文字（字幕）和画面图像（帧），不是只靠字幕猜画面。
## 我实测的两个场景
### 拆解一个技术视频的开场钩子
找了一个讲“如何优化 Python 代码”的 8 分钟 YouTube 视频，输入：
“`
/watch https://youtu.be/abc123 开头30秒用了什么吸引注意的技巧？
“`
大约 40 秒后（取决于视频长度和帧数），Claude 返回分析：它看到开头两帧画面是代码编辑器和终端，字幕显示“你写代码的时候有没有想过…”，判断使用了“共鸣式提问”钩子。全程免费——视频有 YouTube 自动字幕，没用到 Whisper。
### 诊断一个录屏 bug
同事发来一段安卓崩溃录屏（.mp4 文件），放本地磁盘上。以前我得自己用 ffmpeg 逐秒抽帧，OCR 识别错误信息，再手动喂给 Claude，至少 15 分钟。这次直接：
“`
/watch bug-repro.mp4 what’s going wrong
“`
1 分钟内返回：Claude 在第 7 秒的帧上注意到一个 Toast 弹窗 “java.lang.NullPointerException”，附带时间戳和截图描述。省掉全部中间步骤。
## 真实限制（不是万能药）
– **Whisper API 只在无字幕时必要** – 我测试的 YouTube、Loom 视频都自带字幕，没花钱。但本地录屏、无 CC 的 Instagram 故事就需要自己配置 Whisper key。`yt-dlp` 支持数百个网站，但国内视频站（B站、抖音）我没试，理论上 `yt-dlp` 能处理但可能需要额外参数。
– **本地文件路径支持** – `/watch /path/to/file.mov` 能用。但 README 没说数据是否上传第三方。从依赖看，`yt-dlp` 和 `ffmpeg` 都是本地工具，处理应该在本地完成。不放心可以审查源码（仓库不大），或者断开网络后测试。
– **许可证未标注** – GitHub 仓库没有 LICENSE 文件。个人用没问题，商业用途建议先联系作者（bradautomates）。
– **依赖宿主的多模态能力** – 如果宿主模型不是 Claude（比如通过 API 接其他模型），可能不支持看图。`npx skills` 默认跑在 Claude 上，我在 Cursor 里测试正常，但如果你在 VS Code 里用 Copilot Chat 则可能不行（目前 Copilot 不支持多模态）。
## 和传统“视频摘要”有什么区别
很多工具只拉 YouTube 字幕，然后纯文本总结。`/watch` 额外做了两件事：一是场景感知抽帧，让 Claude 看到画面（广告创意、UI 布局、代码编辑器内容）；二是只下载必要片段而不是整片，适合大文件。如果你只需要字幕摘要，用 youtube-transcript 之类的免费工具也行。但如果你想分析“主播在第20秒竖起了哪个产品”“这个错误弹窗的背景代码是什么”，就需要结合画面。
## 项目目前的状态
7782 个 star，说明需求真实。作者活跃，最近有更新。但项目还算年轻（2025 年创建），文档里没有详细贡献指南，LICENSE 缺失。如果你计划在公司内部使用，建议先私下联系作者获取许可，或者自己 fork 后加上许可证。个人用则完全没问题。
## 结语（不是万能结尾）
装一个插件，让能聊天的 Claude 能看视频。安装两条命令，零配置，免费字幕覆盖大部分公共视频。如果你的工作流里经常有“分析录屏/拆解竞品/整理教程”的需求，这工具省大量手工。需要 Whisper key 的场景不多，但确实存在。没有许可证，商业用需谨慎。