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 宿主平台：

npx skills add bradautomates/claude-video -g

（-g 全局安装到你的用户目录，在所有项目中可用。去掉则按项目范围安装。）

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

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

---

Claude 可以阅读网页、运行脚本、浏览仓库。但它无法开箱即用地观看视频。你粘贴一个 YouTube 链接，它要么只能根据标题猜测，要么拉取一份缺失屏幕内容 90% 的转录文本。

有了 Claude Video /watch，你可以粘贴 URL 或本地路径，提出一个问题，Claude 会先获取字幕，只下载所需内容，提取帧（按场景感知，或使用 efficient 模式快速提取关键帧），拉取带时间戳的转录文本（字幕可用时免费，否则使用 Whisper API 作为后备），并将每一帧作为图像 Read。等到它回答问题时，它已经看过了视频并听过了音频。

/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?

人们实际用它做什么

分析他人的内容。 /watch https://youtu.be/<viral-video> what hook did they open with? Claude 查看前几帧，阅读开场转录文本，分析结构。同样适用于广告创意、竞品发布、播客开场等任何如何做与做了什么同样重要的场景。

通过视频诊断 Bug。 有人给你发了一段出问题的屏幕录制。/watch bug-repro.mov what's going wrong? Claude 观看录制内容，找到问题出现的帧，描述屏幕上显示的内容，通常无需你打开文件就能捕捉到原因。

总结视频。 /watch https://youtu.be/<long-thing> summarize this 做了显而易见的事 — 提取结构、关键时刻、实际说和展示了什么。比以 2 倍速观看更快。

从更新视频中剔除炒作。 /watch https://youtu.be/<launch-video> what's actually new — skip the hype 将一个“改变游戏规则”的功能发布提炼成少数重要事项，让你在不需要十分钟简介和过度宣传的情况下获取实质内容。

将播放列表转换为笔记。 /watch https://youtu.be/<video> summarize this to a note 对一系列视频运行，并为每个视频归档一份总结，使得一个频道或课程变成一组可搜索的笔记，而不是需要你从头看到尾的几小时内容。

工作原理

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 文件默认宽 512px，高度限制为 1998px 以适应 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 会将其删除。

帧预算 — 为什么重要

令牌成本主要由帧主导。每一帧都是一张图像；图像令牌会迅速累积。脚本的自动 fps 逻辑就是为了让你不至于在稀疏扫描一个 30 分钟的视频上浪费上下文预算，而本来一个聚焦的 30 秒窗口就能更好地回答。

时长	默认帧预算	你获得什么
≤30 秒	~30 帧	密集 — 基本上每个关键时刻
30 秒 - 1 分钟	~40 帧	仍然密集
1 - 3 分钟	~60 帧	舒适
3 - 10 分钟	~80 帧	稀疏但可用
> 10 分钟	100 帧（有上限模式）	“稀疏扫描”警告 — 重新聚焦运行，或使用 --detail token-burner 获取无上限全覆盖

当用户指定某一时刻（“大约 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. 帧预算上限在去重后应用，因此预算用于不同的帧。

与最后保留的帧（而不是前一帧）进行比较，可以捕捉到永远不会触发逐帧阈值的缓慢渐变动画。阈值故意设置得很低，并测量绝对亮度而非结构，因此一行代码差异、终端滚动一行、或两个不同颜色的扁平幻灯片都能保留。

Frames 行会报告折叠情况，例如 6 selected from 14 candidates (… 8 near-duplicates dropped …)。对于持续运动的素材，没有帧被丢弃，你支付的费用与原来一样。

细节模式 — 实测

--detail 旋钮在速度和令牌成本之间进行视觉保真度权衡。以下数据来自一次针对 49:08 YouTube 视频（1280×720、英语自动字幕）的实际运行 — 一个较长的、基本静态的屏幕录制，是考验上限最严苛的场景。提取时间为本地 CPU 对预下载副本进行；一次性下载耗时 ~37 秒 / 76 MB，由三种帧模式共享。

模式	引擎	帧数	上限	提取时间	时间覆盖	估计图像令牌数
transcript	无（字幕）	0	—	~4.5 秒（一次 yt-dlp 调用，无下载）	完整（文本）	0（≈26.6k 文本令牌）
efficient	关键帧（-skip_frame nokey）	50	50	~0.5 秒	0:00 → 49:04（完整）	~9.8k
balanced	场景切换	100	100	~20.9 秒	0:00 → 48:38（完整）	~19.7k
token-burner	场景切换	116	无上限	~21.0 秒	0:00 → 48:38（完整）	~22.8k

• 图像令牌使用 Anthropic 的 (width × height) / 750 — 在默认 512px 宽度下，这些 720p 帧为 512×288，约 197 令牌/帧；--resolution 1024 则大约是这个的 4 倍。带字幕的模式下，转录文本总是存在的，在长视频中往往是更大的成本。
• 所有帧模式共用一种采样规则。 每种模式先检测整个范围内的所有候选帧，然后均匀采样（首帧和末帧始终保留）到其上限。不同模式仅在候选来源（关键帧 vs. 场景切换）和上限上有所区别，在覆盖范围分配上从不不同 — 因此最后一帧始终落在末尾，而不是中途。
• efficient 是速度等级（~0.5 秒）— 它只重建关键帧，因此比场景模式快约 40 倍（场景模式需要解码每一帧来寻找切换点）。在低运动素材上，它可能返回比 balanced 更多的帧（关键帧数量超过场景切换）；“efficient” 意味着快速提取，而不是帧数更少。
• token-burner 仅在超过上限时与 balanced 不同。 该片段有 116 个场景切换，因此 balanced 采样了 100 帧，而 token-burner 保留了全部 116 帧。在高运动、有数百个切换点的视频上，token-burner 会保留所有帧（并触发 >250 帧令牌警告），而 balanced 会缩减到 100 帧。

从一个冷 URL 开始，transcript 是目前最便宜的模式；帧模式在上述提取时间之上增加了共享的约 37 秒下载时间。

安装

平台	安装
Claude Code	/plugin marketplace add bradautomates/claude-video 然后 /plugin install watch@claude-video
Codex、Cursor、Copilot、Gemini CLI 及 50+ 更多	npx skills add bradautomates/claude-video -g
claude.ai（网页版）	下载 watch.skill → 设置 → 能力 → 技能 → +
手动/开发	git clone 然后将 skills/watch 符号链接到宿主平台的 skills 目录（见下方）

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 CLI 将该技能安装到它检测到的任意代理中：

npx skills add bradautomates/claude-video -g

-g 全局安装到你的用户目录（~/.codex/skills、~/.cursor/skills 等）；去掉则为当前项目安装。有用的标记：

• -a, --agent <names…> — 指定目标宿主平台，例如 -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。
2. 前往设置 → 能力 → 技能。
3. 点击 + 并将文件拖入。

首先在“能力”下启用“代码执行和文件创建” — 该技能需要使用 ffmpeg 和 yt-dlp，否则无法运行。

手动安装（开发者）

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

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 直接工作。检查过程是不到 100ms 的查找，因此不会在后续运行中拖慢你。

自带密钥

字幕覆盖大多数公开视频，免费。Whisper 后备仅在视频确实没有字幕轨道时触发 — 通常是本地文件、TikTok、部分 Vimeo 以及偶尔没有字幕的 YouTube 上传。

能力	需要什么	成本
下载 + 原生字幕	yt-dlp + ffmpeg	免费
Whisper 后备（首选）	Groq API 密钥 — whisper-large-v3	便宜、快速
Whisper 后备（备选）	OpenAI API 密钥 — whisper-1	标准定价
完全禁用 Whisper	--no-whisper	免费，仅帧（无字幕时）

用法

/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?
/watch https://www.tiktok.com/@user/video/123 summarize this
/watch ~/Movies/screen-recording.mp4 when does the UI break?
/watch https://vimeo.com/123 what tools does she mention?

聚焦特定片段 — 更密集的帧预算，更低的令牌成本：

/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 — 降低帧上限以获得更紧凑的令牌预算。
• --resolution W — 当 Claude 需要读取屏幕文本（幻灯片、终端、代码）时，将帧宽度提升到 1024 px。
• --fps F — 覆盖自动 fps 计算（仍限制最大 2 fps）。
• --whisper groq|openai — 强制使用特定的 Whisper 后端。
• --no-whisper — 完全禁用转录；仅帧。
• --no-dedup — 保留近似重复的帧。默认情况下，帧差值传递会丢弃与前一个视觉上几乎相同的帧（静态幻灯片、屏幕录制、暂停的视频），从而将帧预算用于不同的内容；此标记关闭该功能。
• --out-dir DIR — 将工作文件保存在特定目录（默认：自动生成的临时目录）。

限制

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

结构

.
├── skills/watch/                 # 自包含技能 — 被所有安装程序作为整体复制
│   ├── SKILL.md                  # 技能合约 — 所有平台的最终真理
│   └── scripts/
│       ├── watch.py              # 入口点 — 协调下载 → 帧 → 转录
│       ├── download.py           # yt-dlp 封装
│       ├── frames.py             # ffmpeg 帧提取 + 自动 fps 逻辑
│       ├── transcribe.py         # VTT 解析 + 去重 + Whisper 协调
│       ├── whisper.py            # Groq / OpenAI 客户端（纯标准库）
│       ├── config.py             # 共享配置（~/.config/watch/.env）
│       ├── setup.py              # 预检 + 安装器
│       └── build-script.sh       # 构建 dist/watch.skill 用于 claude.ai 上传（仅开发）
├── hooks/                        # SessionStart 状态钩子（仅 Claude Code）
├── .claude-plugin/               # plugin.json + marketplace.json（Claude Code）
├── .codex-plugin/                # plugin.json — Codex/代理清单（"skills": "./skills/"）
├── .agents/plugins/              # marketplace.json — Agent Skills 市场列表
├── AGENTS.md → CLAUDE.md         # 通用代理入口点
├── tests/                        # pytest 测试套件（ffmpeg 合成片段，无网络）
└── .github/workflows/            # release.yml — 推送标签时自动构建 watch.skill

开发

# 运行测试套件（标准库 + pytest；帧测试需要 ffmpeg）：
python3 -m pytest -q

# 构建 claude.ai 上传包：
bash skills/watch/scripts/build-skill.sh      # → dist/watch.skill

发布：标记 vX.Y.Z，推送该标记。工作流会构建 dist/watch.skill 并将其附加到 GitHub 发布。确保版本在 skills/watch/SKILL.md、.claude-plugin/plugin.json 和 .codex-plugin/plugin.json 中保持一致。

查看 CHANGELOG.md 了解版本历史。

开源

MIT 许可证。

基于 yt-dlp、ffmpeg 和 Claude 的多模态 Read 工具构建。Whisper 转录通过 Groq 或 OpenAI 实现。

由 Brad Bonanno 构建 — 我在 YouTube (@bradbonanno) 上制作关于使用 AI 构建的内容，并在 Solaris Automation 为企业构建 AI 操作系统。如果 /watch 让你免于在视频中来回拖动，欢迎在频道上打个招呼。

Star 历史

---

github.com/bradautomates/claude-video · @bradbonanno · Solaris Automation · LICENSE