/watch

赋予 Claude 观看任意视频的能力。

Claude 代码：

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

claude.ai（网页版）：下载 watch.skill 并将其拖放到“设置”→“功能”→“技能”中。

Codex / 通用技能：

git clone https://github.com/bradautomates/claude-video.git ~/.codex/skills/watch

零配置启动 — 首次运行时，macOS 会通过 brew 安装 yt-dlp 和 ffmpeg（Linux/Windows 会显示具体命令）。字幕免费覆盖大多数公开视频。只有当视频没有字幕时，才需要 Whisper API 密钥。

---

Claude 可以阅读网页、运行脚本、浏览代码库。但它无法开箱即用地“观看视频”。当你粘贴 YouTube 链接时，它要么只能根据标题猜测内容，要么只能获取缺失了 90% 画面信息的文字记录。

借助 Claude Video 的 /watch 功能，你只需粘贴 URL 或本地路径并提问，Claude 就会下载视频、以自动调整的速率提取帧、获取带时间戳的文字记录（有免费字幕时优先使用，Whisper API 作为备用），并将每一帧作为图像进行 Read 处理。在它回答问题时，已经“看”过视频画面并“听”过音频内容了。

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

为什么会有这个工具

我开发这个工具是因为我经常通过视频来获取内容。如果看到一个正在爆火的 YouTube 视频，我想知道创作者是如何设计开场钩子的——前 3 秒屏幕上有什么，他们说了什么，为什么这样做有效。以前我得自己边看边拿笔记，现在只需粘贴 URL 然后提问就行。

另一半原因是内容总结。大多数 YouTube 视频不值得我花 20 分钟去看。我把 URL 交给 Claude，它会提取文字稿，告诉我视频的核心内容。如果视频的视觉部分很重要，它还会附带提取的帧画面。如果是播客或访谈类视频，文字稿通常就足够了。

Claude 非常擅长阅读和整合信息，但在此之前，视频是我无法直接提供给它的一种输入形式。粘贴 YouTube 链接根本得不到有用的结果。而 /watch 命令填补了这个空白。

人们实际用它来做什么

分析他人的内容。输入 /watch https://youtu.be/<热门视频> what hook did they open with?，Claude 会查看开头的帧画面，阅读开场文字稿，分析其结构。广告创意、竞争对手的新品发布、播客引言等任何“怎么做”和“做了什么”同样重要的内容，都可以这样分析。

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

总结视频内容。输入 /watch https://youtu.be/<长视频> summarize this 就能完成显而易见的工作——提取视频结构、关键 moments、实际的对话和画面内容。比 2 倍速观看还要快。

工作原理

1. 粘贴视频和问题。可以是 URL（任何 yt-dlp 支持的链接——YouTube、Loom、TikTok、X、Instagram 以及其他几百个平台）或本地路径（.mp4、.mov、.mkv、.webm）。
2. yt-dlp 下载视频。对于 URL，会下载到临时工作目录。对于本地文件，则无需下载，直接原地处理。
3. ffmpeg 按自动比例提取帧画面。帧画面的数量会根据视频时长动态调整：≤30 秒约 30 帧，30-60 秒约 40 帧，1-3 分钟约 60 帧，3-10 分钟约 80 帧，更长的视频则会稀疏地提取 100 帧。硬性限制：最高 2 fps，最多 100 帧。默认生成 512 像素宽的 JPEG 图像——如果 Claude 需要读取屏幕上的文字，可以使用 --resolution 1024 来提高分辨率。
4. 文字稿来自两个途径。首选：yt-dlp 从视频源提取原生字幕（人工或自动生成）。免费、即时、准确性尚可。备用方案：提取单声道 16 kHz 音频片段并发送给 Whisper——优先使用 Groq 的 whisper-large-v3（更便宜且更快）或 OpenAI 的 whisper-1。
5. 将帧画面和文字稿交给 Claude。脚本会打印带有 t=MM:SS 标记的帧画面路径，以及带时间戳的文字稿。Claude 会并行 Read 每个帧画面——JPEG 图像会直接作为图片呈现在其上下文中。
6. Claude 基于实际的屏幕画面和音频内容给出答案。不是“基于描述”或“根据标题”。它“看”了帧画面，“听”了文字稿。它会像真正看过视频的人一样回答问题。
7. 清理。脚本最后会打印工作目录。如果你不打算追问，Claude 会删除该目录。

帧预算 — 为何重要

令牌成本主要由帧决定。每一帧都是一张图像，图像令牌的数量会迅速累积。脚本的自动帧率逻辑旨在避免您在对一段30分钟的视频进行稀疏扫描时耗尽上下文预算，而实际上可能通过聚焦30秒的窗口就能得到更好的答案。

时长	默认帧预算	效果
≤30秒	~30帧	密集 — 基本覆盖每个关键瞬间
30秒 - 1分钟	~40帧	仍然密集
1 - 3分钟	~60帧	舒适
3 - 10分钟	~80帧	稀疏但可用
> 10分钟	100帧	“稀疏扫描”警告 — 建议重新运行并聚焦

当用户指定某个时刻（“大约2:30”、“最后30秒”、“从0:45到1:00”）时，请传递 --start / --end 参数。聚焦模式会获得更高的每秒帧预算，上限为2 fps。这比对整个视频进行稀疏扫描要有用得多。

安装

平台	安装方法
Claude Code	/plugin marketplace add bradautomates/claude-video，然后 /plugin install watch@claude-video
claude.ai (网页版)	下载 watch.skill → 设置 → 功能 → 技能 → +
Codex	git clone https://github.com/bradautomates/claude-video.git ~/.codex/skills/watch
手动 / 开发	git clone https://github.com/bradautomates/claude-video.git ~/.claude/skills/watch

Claude Code

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

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

claude.ai（网页版）

1. 从最新发布版本中下载 watch.skill。
2. 前往设置 → 功能 → 技能。
3. 点击 + 并将文件拖入。

首先在功能下启用“代码执行和文件创建”——该技能需要调用 ffmpeg 和 yt-dlp，因此若不启用将无法运行。

Codex

git clone https://github.com/bradautomates/claude-video.git ~/.codex/skills/watch

手册（开发者版）

git clone https://github.com/bradautomates/claude-video.git ~/.claude/skills/watch

首次运行

首次调用 /watch 时，该功能会运行 scripts/setup.py --check。如果您的 PATH 中没有 ffmpeg / yt-dlp，或者未设置 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 即可直接使用。该检查耗时不到 100 毫秒，因此不会影响后续运行速度。

自备密钥

字幕功能可免费覆盖大多数公开视频。仅当视频确实没有字幕轨道时（通常是本地文件、TikTok 视频、部分 Vimeo 视频以及少数无字幕的 YouTube 上传视频），才会启用 Whisper 备用方案。

功能	所需条件	成本
下载 + 原生字幕	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            # from 1h12m to end

其他参数（传递给 scripts/watch.py）：

• --max-frames N — 降低帧上限以控制 token 预算。
• --resolution W — 当 Claude 需要读取屏幕文本（幻灯片、终端、代码）时，将帧宽度提升至 1024 像素。
• --fps F — 覆盖自动 FPS 计算（仍上限为 2 FPS）。
• --whisper groq|openai — 强制使用特定的 Whisper 后端。
• --no-whisper — 完全禁用转录；仅保留帧。
• --out-dir DIR — 将工作文件保存在指定位置（默认：自动生成的临时目录）。

限制

• 最佳准确性：10 分钟以内。 超过此时长，脚本会打印“稀疏扫描”警告 —— 可使用 --start/--end 重新运行以聚焦于您实际关心的部分。
• 硬限制：2 FPS，100 帧。 帧数决定 token 成本；即使自动 FPS 计算结果更高，脚本也会强制执行此限制。
• Whisper 上传限制：25 MB。 在单声道 16 kHz 情况下，约为 50 分钟音频。更长的视频需要字幕或使用 --start/--end 截取更小的片段。
• 不支持私有平台。 此功能不会登录任何平台。仅支持公共 URL 和本地文件。如果 yt-dlp 无法在无身份验证的情况下访问，那么 /watch 也无法访问。

结构

.
├── SKILL.md                 # skill contract — loaded by all three surfaces
├── scripts/
│   ├── watch.py             # entry point — orchestrates download → frames → transcript
│   ├── download.py          # yt-dlp wrapper
│   ├── frames.py            # ffmpeg frame extraction + auto-fps logic
│   ├── transcribe.py        # VTT parsing + dedupe + Whisper orchestration
│   ├── whisper.py           # Groq / OpenAI clients (pure stdlib)
│   ├── setup.py             # preflight + installer
│   └── build-skill.sh       # build dist/watch.skill for claude.ai upload
├── hooks/                   # SessionStart status hook (Claude Code only)
├── .claude-plugin/          # plugin.json + marketplace.json (Claude Code)
├── .codex-plugin/           # codex packaging
└── .github/workflows/       # release.yml — auto-builds watch.skill on tag push

开发

# Build the claude.ai upload bundle:
bash scripts/build-skill.sh      # → dist/watch.skill

发布步骤：创建标签 vX.Y.Z 并推送该标签。工作流将构建 dist/watch.skill 并将其附加到 GitHub 发布版本中。

版本历史请参见 CHANGELOG.md。

开源许可

采用 MIT 许可证。

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

---

github.com/bradautomates/claude-video · LICENSE