bradautomates/claude-video 来源：https://github.com/bradautomates/claude-video

/watch

让Claude能够观看任何视频。

Claude Code（推荐——通过市场自动更新）： /plugin marketplace add bradautomates/claude-video /plugin install watch@claude-video

Codex、Cursor、Copilot、Gemini CLI 或任何 50+ 的 Agent Skills（https://agentskills.io）平台： bash npx skills add bradautomates/claude-video -g （-g 全局安装到当前用户，所有项目均可使用；去掉 -g 则作用于当前项目。）

更多安装选项（claude.ai 网页版、手动安装）见下方 安装 部分。

零配置即可开始 —— yt-dlp 和 ffmpeg 首次运行时会通过 macOS 上的 brew 自动安装（Linux/Windows 会打印确切命令）。大多数公开视频的字幕是免费的。仅在视频没有字幕时才需要 Whisper API 密钥。

Claude 可以阅读网页、运行脚本、浏览仓库。但它无法做到的一件事是观看视频。你粘贴一个 YouTube 链接，它要么根据标题猜测，要么拉取一份缺失了屏幕内容 90% 的文字稿。有了 Claude Video /watch，你可以粘贴 URL 或本地路径，提出一个问题，然后 Claude 会先获取字幕，只下载它需要的内容，提取帧（场景感知，或在 efficient 模式下快速提取关键帧），拉取带时间戳的文字稿（有免费字幕时优先使用，否则回退到 Whisper API），并将每一帧作为图像进行 Read 操作。等到它回答时，它已经看到了视频并听到了音频。

/watch https://youtu.be/dQw4w9WgXcQ 在30秒标记处发生了什么？

人们实际用它来做什么

分析他人的内容。 /watch https://youtu.be/ 他们开场用了什么钩子？ Claude 会查看前几帧，阅读开头文字稿，拆解结构。同样适用于广告创意、竞争对手发布、播客开场，任何“如何做“与“做了什么“同样重要的内容。

从视频诊断错误。 有人发送给你一段屏幕录制，演示某个问题。/watch bug-repro.mov 出了什么问题？ Claude 观看录制视频，找到问题出现的帧，描述屏幕上显示的内容，通常能抓住原因，而你甚至不需要打开文件。

总结视频。 /watch https://youtu.be/ 总结这个 做了显而易见的事情 —— 提取结构、关键时刻、实际所说的内容和展示的内容。比 2 倍速观看还快。

从更新视频中剔除炒作。 /watch https://youtu.be/ 实际上新的是什么——跳过炒作 将一个“颠覆性“的功能发布剥离出几个真正重要的东西，这样你就能在十分钟的介绍和过度推销之外获得实质内容。

将播放列表转化为笔记。 /watch https://youtu.be/ 将总结转化为笔记 对一系列视频逐条运行，生成每段视频的摘要，从而使一个频道或课程成为可搜索的笔记集，而不是需要花几小时观看的内容。

工作原理

1. 你粘贴视频和问题。 URL（任何 yt-dlp 支持的来源 —— YouTube、Loom、TikTok、X、Instagram，以及另外几百个平台）或本地路径（.mp4、.mov、.mkv、.webm）。
2. yt-dlp 首先检查字幕。 在 transcript 细节模式下，有字幕的 URL 无需下载视频即可返回。否则，或者当需要 Whisper 处理音频时，只下载运行所需的内容。
3. ffmpeg 按所选细节模式提取帧。 efficient 模式仅解码关键帧（近乎即时）；balanced/token-burner 优先选择场景变更帧，当产生量不足时回退到基于时长的均匀采样器。默认 JPEG 宽度为 512 像素，高度限制在 1998 像素以内，以保证与 Claude Read 兼容。
4. 文字稿来自两个来源之一。 首先尝试：yt-dlp 从来源拉取原生字幕（手动或自动生成）。免费、即时、大致准确。回退方案：提取一个单声道 16 kHz 64 kbps 的 mp3 音频片段（约 480 kB/分钟）并发送给 Whisper —— 优选 Groq 的 whisper-large-v3（更便宜更快）或 OpenAI 的 whisper-1。
5. 帧 + 文字稿交给 Claude。 脚本打印带有 t=MM:SS 标记的帧路径和带时间戳的文字稿。Claude 并行 Read 每一帧 —— JPEG 直接作为图像渲染到其上下文中。
6. Claude 的回答基于屏幕上和音频中实际显示的内容。 不是“根据描述“或“根据标题“。它看到了帧，听到了文字稿。它的回答方式就像看过视频的人那样。
7. 清理。 脚本最后打印工作目录。如果你不继续追问，Claude 会删除它。

帧预算 —— 为什么重要

帧数是 token 消耗的主要来源。每一帧都是一张图像；图像 token 消耗得很快。脚本的自动 fps 逻辑就是为了防止你在一个 30 分钟视频的稀疏扫描中超出上下文预算，而其实 30 秒的聚焦窗口就能更好回答。

当用户指定一个时间点（“大约 2:30”、“最后 30 秒”、“从 0:45 到 1:00”）时，使用 --start / --end。聚焦模式会获得更密集的每秒预算，上限为 2 fps。远比对整个片段进行稀疏扫描有用得多。

帧去重

帧选择 —— 关键帧（efficient）、场景变更检测（balanced/token-burner），或其回退的均匀采样器 —— 仍然可能产生几乎相同的帧：一个固定 90 秒的幻灯片的屏幕录制会产生一打几乎相同的帧，每一帧都会作为单独图像计费。去重过程会在帧到达 Claude 之前删除它们。它默认在所有帧模式下运行（--no-dedup 可以关闭）：

1. 一次 ffmpeg 调用将每个提取的 JPEG 缩放到 16×16 灰度缩略图。之后全部使用纯标准库 Python —— 不需要图像库。
2. 对每一帧，计算其与上一个被保留的帧之间的平均绝对差（每像素亮度平均变化，0–255 尺度）。
3. 如果该差值小于或等于阈值（2.0），则帧是近乎重复的，被丢弃。否则保留并作为新的参考。
4. 帧预算上限在去重后应用，因此预算只用于不同的帧。
5. 与上一个保留的帧（而不是前一个原始帧）比较，能捕捉到缓慢的淡入淡出，这种变化不会触发帧到帧的阈值。

阈值故意设得较低，并且测量绝对亮度而不是结构，因此一行代码差异、终端滚动一行、或两个不同颜色的平面幻灯片都能保留。

帧行会报告被合并的情况，例如 6 selected from 14 candidates (... 8 near-duplicates dropped ...)。对于始终运动的画面，不会丢弃任何帧，你需要付出本来就会付出的 token 成本。

细节模式 —— 实测数据

--detail 旋钮在速度和 token 成本之间进行视觉保真度的权衡。以下数据来自对一个 49:08 YouTube 视频（1280×720，英文自动字幕）的真实运行 —— 这是一个很长、大部分静态的屏幕录制，是对上限模式压力最大的情况。提取时间是本地 CPU 对预下载副本的处理；一次性下载约 ~37 秒 / 76 MB，三种帧模式共享该下载。

• 图像 token 使用 Anthropic 的 (宽度 × 高度) / 750 —— 在默认的 512 像素宽度下，这些 720p 帧为 512×288，约 197 token/帧；--resolution 1024 大约是其 4 倍。文字稿在每个有字幕模式下都会呈现，并且在长视频中通常是更大的成本。
• 所有帧模式共享同一个采样规则。 每个模式在整个范围内检测所有候选帧，然后均匀采样（始终保留第一帧和最后一帧）降到其上限。模式之间仅在候选来源（关键帧 vs. 场景剪切）和上限上有所不同，绝不改变覆盖的分布方式 —— 因此最后一帧始终落在末尾，而不是中途。
• efficient 是速度层级（~0.5 秒）—— 它只重建关键帧，因此比场景模式快约 40 倍，后者需要解码每一帧来找到剪切点。在低运动画面中，它甚至可能返回比 balanced 更多的帧（关键帧多于场景剪切）；“efficient” 意味着快速提取，而不是更少的帧。
• token-burner 仅在超出上限时与 balanced 不同。 本例中检测到 116 个剪切，因此 balanced 采样了 100 帧，token-burner 保留了全部 116 帧。在高运动视频中有数百个剪切时，token-burner 会保留所有帧（并在超过 250 帧时触发 token 警告），而 balanced 则缩减到 100 帧。从冷 URL 端到端执行来看，transcript 是最便宜的模式；其他帧模式在上述提取时间之上还需额外加上约 37 秒的共享下载时间。

安装

Claude Code

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

稍后使用 /plugin update watch@claude-video 更新。

Codex、Cursor、Copilot、Gemini CLI 和 50+ 其他宿主

Agent Skills（https://agentskills.io）CLI 会将技能安装到它能检测到的任何代理中：

bash npx skills add bradautomates/claude-video -g

-g 会将技能安装到当前用户全局（~/.codex/skills、~/.cursor/skills 等）；去掉它则安装到当前项目。

有用的标志：

• -a, --agent <agent> — 指定目标宿主机，例如 -a codex -a cursor
• -l, --list — 列出此仓库中的技能而不安装
• --copy — 复制文件而不是符号链接（用于不支持符号链接的文件系统）

CLI 从 skills/watch/SKILL.md 发现技能，并将整个文件夹 —— SKILL.md 及其 scripts/ 运行时 —— 作为一个自包含单元复制。SKILL.md 会根据其安装位置解析自己的脚本，因此它在所有宿主机上工作方式相同。

稍后使用 npx skills update watch -g 更新。

claude.ai（网页版）

1. 从最新版本下载 watch.skill（https://github.com/bradautomates/claude-video/releases/latest）。
2. 前往 设置 → 能力 → 技能。
3. 点击 + 并放入文件。
4. 首先在“能力“下启用“代码执行和文件创建“ —— 该技能会调用 ffmpeg 和 yt-dlp，没有它就无法运行。

手动安装（开发者）

克隆仓库并将自包含的技能文件夹符号链接到宿主机的技能目录中 —— 符号链接确保安装与工作树同步，便于编辑：

``bash git clone https://github.com/bradautomates/claude-video.git ln -s “$(pwd)/claude-video/skills/watch” ~/.claude/skills/watch

或者 ~/.codex/skills/watch

``

对于 claude.ai，从源码构建 .skill 包：bash skills/watch/scripts/build-skill.sh 会生成 dist/watch.skill。

首次运行

在第一次调用 /watch 时，技能会运行 scripts/setup.py --check。如果 ffmpeg / yt-dlp 不在你的 PATH 中，或者未设置 Whisper API 密钥，它会引导你修复：

• macOS — 自动运行 brew install ffmpeg yt-dlp。
• Linux — 打印确切的 apt / dnf / pipx 命令。
• Windows — 打印 winget / pip 命令。
• API 密钥 — 创建 ~/.config/watch/.env（权限 0600），其中包含 GROQ_API_KEY（首选）和 OPENAI_API_KEY 的注释占位符。

设置完成后，预检静默运行，/watch 直接生效。检查过程是 sub-100ms 的查询，不会拖慢后续运行。

自带密钥

字幕覆盖了大多数公开视频，是免费的。Whisper 回退仅在视频确实没有字幕轨道时才会启用 —— 通常是本地文件、TikTok、某些 Vimeo 以及偶尔缺少字幕的 YouTube 上传。

用法

/watch https://youtu.be/dQw4w9WgXcQ 在30秒标记处发生了什么？ /watch https://www.tiktok.com/@user/video/123 总结这个 /watch ~/Movies/screen-recording.mp4 UI何时崩溃？ /watch https://vimeo.com/123 她提到了哪些工具？

聚焦特定部分 —— 更密集的帧预算，更低的 token 成本：

/watch https://youtu.be/abc --start 2:15 --end 2:45 /watch video.mp4 --start 50 --end 60 /watch "$URL" --start 1:12:00 # 从1h12m到结尾

其他旋钮（传递给 scripts/watch.py）：

• --detail transcript|efficient|balanced|token-burner — 保真度/速度旋钮。transcript 跳过帧（仅文字稿）；efficient 使用快速关键帧（上限 50）；balanced 使用场景感知帧（上限 100）；token-burner 是场景感知且无上限。
• --timestamps T1,T2,... — 在每个绝对时间戳（SS/MM:SS/HH:MM:SS）抓取一帧。Claude 先读取文字稿，然后定位演示者标记的时刻（“看这里”、“如你所见”）。添加到细节帧之上（从上限中预留）；在聚焦模式下，超出窗口的时间戳会被丢弃；在 --detail transcript 模式下，这些是唯一的帧。
• --max-frames N — 降低帧上限以获得更紧的 token 预算。
• --resolution W — 当 Claude 需要阅读屏幕文本（幻灯片、终端、代码）时，将帧宽度提升到 1024 像素。
• --fps F — 覆盖自动 fps 计算（仍受限于 2 fps 上限）。
• --whisper groq|openai — 强制使用特定的 Whisper 后端。
• --no-whisper — 完全禁用转录；仅包含帧。
• --no-dedup — 保留近乎重复的帧。默认情况下，帧增量传递会丢弃与前一帧视觉上几乎相同的帧（保持的幻灯片、静态屏幕录制、暂停的视频），使帧预算用于不同的内容；此标志关闭该功能。
• --out-dir DIR — 将工作文件保存在特定位置（默认：自动生成的临时目录）。

限制

• 长视频的准确性取决于细节模式。 在有上限的模式（efficient、默认 balanced）下，超过约 10 分钟后覆盖会变稀薄 —— 帧上限会分布到整个片段，因此脚本会打印“稀疏扫描“警告，建议使用 --start/--end 重新聚焦运行。token-burner 解除上限，并保留整个视频中每一个场景变更帧，因此在更长的片段上保持完整，代价是更多的图像 token。10 分钟标记是针对有上限模式的指导，而不是硬性上限。
• 细节是一个旋钮。 默认是平衡的：场景感知帧、最大 2 fps、100 帧上限。使用 --detail efficient 进行快速 50 帧关键帧传递，或使用 --detail token-burner 进行无上限的场景候选。在 ~/.config/watch/.env 中设置 WATCH_DETAIL 可更改默认值。

结构

. ├── skills/watch/ # 自包含技能 — 被每个安装程序作为一个单元复制 │ ├── SKILL.md # 技能定义（包含脚本路径） │ └── scripts/ │ ├── watch.py # 主要入口点 │ ├── setup.py # 预检环境 │ ├── build-skill.sh # 为 claude.ai 构建 .skill 包 │ └── util/ # 在 watch.py 和 setup.py 之间共享的辅助模块 ├── README.md # 你正在阅读的内容 ├── LICENSE # MIT └── dist/ # 构建输出（仅 release）