claude-video 让 Claude Code 真正看得见、听得懂任意视频

项目类型Infrastructure / Runtime

最适合使用 Claude Code、Codex、Cursor、Copilot 或 Gemini CLI，并希望 Agent 能直接理解 YouTube 视频、屏幕录像和本地媒体文件的开发者。

风险等级中等 —— 依赖外部二进制（yt-dlp、ffmpeg）、可选的付费 Whisper API，以及宿主 Agent 对图像 Read 的支持。

评估时间15 到 30 分钟：通过 Claude Code marketplace 安装，并对一条带字幕的短视频跑一次 /watch。

核心问题: 你的 Agent 宿主是否支持 SKILL.md 技能和 Claude 兼容的图像 Read，并且你能接受 yt-dlp 与 ffmpeg 作为本地依赖？

91/100

RepoDaily 采用评分

RepoDaily 将该项目的采用分评为 91/100（强）：分数来自文章来源、安装路径、生产风险、差异化、许可证清晰度以及 AI/Agent 适配度。

基于 RepoDaily 来源和采用说明的方向性评分，不是基准测试。风险: 中

100证据质量

包含 4 个来源、覆盖 4 类来源；如有 RepoDaily 独有模块，会进一步提高证据分。

100可安装/可试用性

检测到 5 个工作流步骤、5 个下一步动作，以及 5 个命令/安装信号。

68维护可信度

趋势热度为 +948 stars；如内容中有 release、issue 或维护信号，会提高维护可信度。

93生产准备度

采纳风险标记为 medium，并包含 5 条安全说明与 4 条跳过条件。

100差异化

3 个机会视角、4 个替代方案，以及 3 个类型化模块支撑差异化判断。

82许可证清晰度

文章中包含许可证来源或许可证表述。

84Agent / AI 适配度

文章正文和元数据中检测到 6 个 AI/Agent 相关信号。

项目概览

claude-video 是一个 Python 技能，通过一个 /watch 斜杠命令为 Claude 以及 50 多个 Agent Skills 宿主扩展视频理解能力。你粘贴 URL 或本地路径并提问，技能会先抓取字幕、按需下载、抽取场景感知的帧、生成带时间戳的转录文本，再把每一帧作为图像喂给模型。等 Claude 回答时，它已经真正看过画面、听过音频。

仓库的定位非常明确：Agent 可以浏览页面、运行脚本、阅读仓库，但唯独看不了视频。粘贴一个 YouTube 链接，模型往往只能根据标题猜测，或拿到一份缺失大量画面信息的转录文本。claude-video 用 yt-dlp 处理来源、ffmpeg 抽帧、原生字幕或 Whisper 做转录，把这一空缺补上。

安装体验被设计得很轻量。在 Claude Code 中添加 marketplace 并安装 watch 插件即可；在 Codex、Cursor、Copilot、Gemini CLI 或其他 Agent Skills 宿主上运行 `npx skills add bradautomates/claude-video -g`。yt-dlp 和 ffmpeg 会在首次运行时通过 macOS 的 Homebrew 安装，Linux 和 Windows 则会打印需要执行的命令。大多数公开视频可以免费拿到字幕，只有在没有字幕时才需要 Whisper API key。

0.2.0 版本发布于 2026-06-29，把项目重构成自包含的 `skills/watch/` 包，让 SKILL.md 与其 scripts 作为同级目录一起分发。这修复了一个具体缺陷：此前通过 `npx skills add` 的非 Claude 安装只复制了 SKILL.md，却没有带上它实际调用的 scripts，导致 Cursor、Codex 等宿主上技能完全不可用。

解决什么问题

Agent 收到 YouTube 链接后，要么凭标题猜测，要么读取一份缺失大量画面信息的转录文本。
屏幕录像里的 bug 复现对 Agent 完全不可读，只能由人工拖动进度条并描述故障帧。
冗长的更新与发布视频把真正的变更埋在开场白和营销里。
课程和会议播放列表变成数小时的被动观看，而不是可检索的笔记。
不同来源的原生字幕质量参差，转录缺口会让摘要直接失效。

工作原理

你粘贴视频并提问。来源可以是 yt-dlp 支持的任意 URL（YouTube、Loom、TikTok、X、Instagram 以及数百个站点），或本地文件（.mp4、.mov、.mkv、.webm）。
yt-dlp 先检查字幕。在 `transcript` 模式下，带字幕的 URL 直接返回，无需下载视频；否则只下载本次运行所需的内容。
ffmpeg 按所选 detail 抽帧。`efficient` 只解码关键帧（上限 50）；`balanced`（默认）全解码以捕获每一处场景切换（上限 100）；`token-burner` 不设上限地保留每个场景切换帧。
转录文本有两个来源：优先用 yt-dlp 拉取原生字幕（免费、即时、准确度尚可），否则抽取一段 mono 16 kHz 64 kbps 的 mp3 音频（约 480 kB/分钟）发给 Whisper —— 优先用 Groq 的 whisper-large-v3，回退到 OpenAI 的 whisper-1。
帧与转录文本交给 Claude。技能把每帧 Read 成宽 512px、高度限制 1998px 的 JPEG（兼容 Claude Read），让模型同时拥有画面与音频上下文。

架构解读：各组件如何组合

运行时是一个自包含的 `skills/watch/` 包；SKILL.md 从被 Read 的位置解析 `$SKILL_DIR`，而非仅限 Claude Code 的变量，因此脚本调用在所有宿主上都可用。
外部依赖为 yt-dlp（来源处理）和 ffmpeg（抽帧）；两者在 macOS 首次运行时通过 `brew` 自动安装，Linux/Windows 打印精确命令。
帧处理流水线把每个候选帧降采样为 16×16 灰度缩略图，按与上一保留帧的平均像素差丢弃近似重复帧，再应用预算上限。
转录层优先使用 yt-dlp 原生字幕，否则回退到 Whisper；超过 25 MB 上传上限的音频会被自动分片，部分分片失败可容忍，只有全部分片失败才终止转录。
默认 detail 可通过 `~/.config/watch/.env` 中的 `WATCH_DETAIL` 配置；主要运行开关有 `--detail`、`--no-dedup`、`--timestamps`、`--no-whisper` 和 `--max-frames`。

试用路径：从安装到第一个回答

Claude Code：`/plugin marketplace add bradautomates/claude-video`，然后 `/plugin install watch@claude-video`。
其他 Agent Skills 宿主：`npx skills add bradautomates/claude-video -g` 全局安装，去掉 `-g` 则按项目作用域安装。
冒烟测试：`/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?`，同时验证抽帧与字幕处理。
本地文件测试：`/watch bug-repro.mov what's going wrong?`，验证 ffmpeg 对屏幕录像的处理。
在 Windows 上请使用 `python` 而非 `python3` 调用脚本，因为 `python3` 在该平台上会指向 Microsoft Store 占位程序。

命令面与 detail 模式

`--detail transcript` 只返回字幕、不抽帧；它也是 `--timestamps` 唯一会产出帧的模式。
`--detail efficient` 只解码关键帧，近乎即时，上限 50 帧。
`--detail balanced` 为默认；全解码以捕获整段视频的每个场景切换，上限 100。
`--detail token-burner` 场景感知、不设上限，并豁免长视频的稀疏扫描警告。
`--timestamps T1,T2,…` 在每个绝对时间戳抓一帧，帧数计入上限。
`--no-whisper` 完全关闭转录、只出帧；`--no-dedup` 关闭近似重复帧过滤。

谁适合关注

适合关注

希望通过 marketplace 安装 /watch、并获得自动更新的 Claude Code 用户。
需要在现有 Agent 宿主内获得视频理解能力的 Cursor、Codex、Copilot、Gemini CLI 用户。
分析竞品视频、广告创意、发布会片段结构与开场钩子的创作者和营销人员。
不想人工拖进度条就能分诊屏幕录像 bug 复现的开发者。
把冗长播放列表和课程转成可检索、逐视频笔记的学习者。

可以先跳过

宿主无法执行 SKILL.md 技能或无法以 Claude 兼容格式 Read 图像的 Agent。
禁止 yt-dlp、ffmpeg 以及外网视频或 Whisper API 访问的隔离环境。
要求严格本地转录、不依赖任何外部 API、且没有自建 Whisper 后端的团队。
标题和已有转录已能覆盖所有问题的场景。

风险与注意事项

中

核心功能依赖外部二进制、宿主对图像的支持以及可选的付费转录 API；安装门槛低，但依赖面不可忽视。

必须存在并正确调用 yt-dlp 和 ffmpeg；首次运行的自动安装仅在 macOS 上通过 Homebrew，其他平台需手动操作。
Whisper 回退需要 Groq 或 OpenAI 的 API key，并将音频外发，可能违反数据策略。
非 Claude 宿主依赖 0.2.0 的自包含包结构；此前的版本在这些宿主上是坏的。
Token 成本随帧数增长，`token-burner` 模式对场景切换帧显式不设上限。
在带 Microsoft Store `python3` 占位程序的系统上需要按文档使用 `python` 调用。

0.1.3 加固了 subprocess argv 以防选项注入（issue #2）：在 yt-dlp argv 中 URL 前插入 `--`，并收紧 `is_url` 以拒绝以 `-` 开头的来源、要求非空 netloc。
在传给 ffmpeg 或 ffprobe 之前，通过 `Path.resolve()` 将视频和音频路径解析为绝对路径，避免以 `-` 开头的相对路径被误判为 flag。
Whisper 回退会把一段 mono 16 kHz 64 kbps 的 mp3 发给 Groq 或 OpenAI；在敏感录像上使用前请审查供应商与数据处理策略。
未声称对下载媒体有沙箱隔离；对待不可信 URL 应与对待任何 yt-dlp 输入一样谨慎。

替代方案比较

方案	适用场景	代价
yt-dlp（独立使用） GitHub ↗	只需要字幕、元数据或媒体文件本身，并打算人工查看。	免费，MIT 许可。
Whisper（OpenAI 开源版本） GitHub ↗	希望本地转录，不把音频发给第三方 API。	自托管免费；算力成本取决于硬件。
ffmpeg GitHub ↗	需要在 Agent 循环之外手动抽帧、转码或处理音频。	免费，依据构建为 LGPL/GPL。
内置 Agent 粘贴转录文本	来源已有完整准确的转录，且不需要画面信息。	免费。

这个趋势说明了什么

视频化 Bug 分诊流水线

QA 团队每天收到屏幕录像；/watch 可以抽出故障帧、读取画面状态，并草拟 issue，无需人工拖视频。

对最近五条录像运行 `/watch bug-repro.mov what's going wrong?`，把生成描述与已建档的工单对比。

把竞品内容拆解变成数据

营销团队可以对竞品最近 20 条视频批量跑 /watch，把开场钩子、结构和画面主张抽成结构化表格。

用 `--detail balanced` 批量处理频道 URL，再与自己近期发布的钩子模式对比。

课程与播放列表压缩

学习者可以把冗长的播放列表转成逐视频笔记，保留纯字幕会丢失的画面与图示信息。

对幻灯密集的课程模块跑 /watch，确认笔记引用了具体视觉帧，而不只是口述内容。

下一步建议

在 Claude Code 上安装并跑一次带字幕的冒烟测试

最快的验证方式是在 Claude Code 上安装后，对一条短视频跑一次 /watch，一次性覆盖 marketplace 安装、yt-dlp 字幕抓取、ffmpeg 抽帧与 Claude 图像 Read。

在 Claude Code 中运行 `/plugin marketplace add bradautomates/claude-video`。
运行 `/plugin install watch@claude-video`。
运行 `/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?`。
如果回答同时引用了画面和音频，再试一个本地 `.mov` 文件。
只有确认默认 `balanced` 模式无法满足需求后，再去 `~/.config/watch/.env` 设置 `WATCH_DETAIL`。

RepoDaily 判断

claude-video 把 Agent 一个真实的盲区 —— 视频 —— 变成了一行 /watch 命令，在字幕优先抓取、场景感知抽帧和 Whisper 自动分片上做出了扎实的工程取舍。中等风险来自 yt-dlp 与 ffmpeg 依赖、可选的付费转录，以及宿主对图像的支持；对于能接受这些前提的 Claude Code 与 Agent Skills 用户，这是一个定位清晰、实用的能力升级。