bradautomates/claude-video

# /watch **赋予 Claude 观看任何视频的能力。** Claude Code: ``` /plugin marketplace add bradautomates/claude-video /plugin install watch@claude-video ``` claude.ai (网页版)：[下载 `watch.skill`](https://github.com/bradautomates/claude-video/releases/latest) 并将其拖放到 Settings → Capabilities → Skills 中。 Codex / 通用 skills: ``` git clone https://github.com/bradautomates/claude-video.git ~/.codex/skills/watch ``` 开箱即用，零配置即可启动 —— `yt-dlp` 和 `ffmpeg` 会在 macOS 上首次运行时通过 `brew` 自动安装（Linux/Windows 会打印出确切的安装命令）。对于绝大多数公开视频，通过字幕即可免费处理。仅当视频没有任何字幕时，才需要 Whisper API key。 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`（总结这个）会执行显而易见的操作——提取视频结构、关键时刻，以及实际讲述和展示的内容。比以 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 帧。默认输出宽 512px 的 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 会将其删除。 ## 帧数预算——为什么这很重要 Token 成本主要由视频帧决定。每一帧都是一张图像；图像 token 累积得非常快。该脚本自动计算 fps 逻辑的存在，是为了防止你在对 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`](https://github.com/bradautomates/claude-video/releases/latest) → Settings → Capabilities → Skills → `+` | | **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`](https://github.com/bradautomates/claude-video/releases/latest)。 2. 进入 Settings → Capabilities → Skills。 3. 点击 `+` 并将文件拖放进去。 请先在 Capabilities 下启用“Code execution and file creation”（代码执行与文件创建）——该 skill 需要通过 shell 调用 `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` 时，该 skill 会运行 `scripts/setup.py --check`。如果 `ffmpeg` / `yt-dlp` 不在你的 PATH 中，或者没有设置 Whisper API key，它会引导你完成修复： - **macOS** —— 自动运行 `brew install ffmpeg yt-dlp`。 - **Linux** —— 打印出确切的 `apt` / `dnf` / `pipx` 命令。 - **Windows** —— 打印出 `winget` / `pip` 命令。 - **API key** —— 创建 `~/.config/watch/.env`（权限模式 `0600`），其中包含带有注释的 `GROQ_API_KEY`（首选）和 `OPENAI_API_KEY` 占位符。 设置完成后，预检将是静默的，`/watch` 即可正常工作。此检查耗时不到 100 毫秒，因此不会拖慢你后续的运行速度。 ## 自带 API 密钥 字幕可以免费覆盖大部分公开视频。Whisper 备选方案仅在视频确实没有字幕轨道时才会启动——通常是本地文件、TikTok、某些 Vimeo 视频以及偶尔没有字幕的 YouTube 上传内容。 | 功能 | 所需条件 | 成本 | |------------|---------------|------| | 下载 + 原生字幕 | `yt-dlp` + `ffmpeg` | 免费 | | Whisper 备选 (首选) | [Groq API key](https://console.groq.com/keys) — `whisper-large-v3` | 便宜，快速 | | Whisper 备选 (备选) | [OpenAI API key](https://platform.openai.com/api-keys) — `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? ``` 聚焦于特定片段 —— 更密集的帧数预算，更低的 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 # 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` —— 将工作文件保留在特定位置（默认：自动生成的 tmp 目录）。 ## 限制 - **最佳准确度：10 分钟以内。** 超过此长度，脚本会打印“稀疏扫描”警告——请使用 `--start`/`--end` 针对你真正关心的部分重新运行。 - **硬性上限：2 fps，100 帧。** 帧数决定了 Token 成本；即使自动 fps 计算出的值更高，脚本也会强制执行此限制。 - **Whisper 上传限制：25 MB。** 在单声道 16 kHz 的情况下，这大约相当于 50 分钟的音频。更长的视频需要带有字幕，或者使用 `--start`/`--end` 限定在较小的窗口内。 - **不支持私有平台。** 此 skill 不会登录任何账号。仅限公开 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 ``` ## 开发 ``` # 构建 claude.ai 上传 bundle： bash scripts/build-skill.sh # → dist/watch.skill ``` 发布流程：打上 `vX.Y.Z` 标签，并推送该标签。工作流会构建 `dist/watch.skill` 并将其附加到 GitHub release 中。 有关版本历史，请参阅 [CHANGELOG.md](CHANGELOG.md)。 ## 开源 MIT 许可证。 基于 `yt-dlp`、`ffmpeg` 以及 Claude 的多模态 `Read` 工具构建。通过 [Groq](https://groq.com) 或 [OpenAI](https://openai.com) 进行 Whisper 转录。 [github.com/bradautomates/claude-video](https://github.com/bradautomates/claude-video) · [LICENSE](LICENSE)

标签：AI辅助, Claude插件, 多模态, 视频处理, 语音转文字, 逆向工具