# claude-video

**Repository Path**: lizhx/claude-video

## Basic Information

- **Project Name**: claude-video
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# /watch（中文版）

**让 Claude 拥有“看视频”的能力。**

Claude 能读网页、跑脚本、翻仓库，但开箱即用的情况下它**看不了视频**：你贴一个 YouTube 链接，它只能靠标题猜测，或拿到一份缺失了 90% 画面信息的文字稿。

有了 `/watch`，你只需贴一个视频 URL 或本地路径，再提个问题，它就会：**先取字幕 → 按需下载 → 按场景提取关键帧 → 拉取带时间戳的字幕（有字幕优先，无字幕则回退到 Whisper 转录）→ 把每一帧当作图片 `Read` 进来**。等它回答时，它已经“看”过了画面、“听”过了声音。

> 本仓库是 [bradautomates/claude-video](https://github.com/bradautomates/claude-video) 的中文文档镜像（MIT 协议）。原技能以 **Agent Skills** 格式发布，可在 Claude Code、Codex、Cursor、Gemini CLI 等 50+ 宿主中使用；在本仓库中，你也可以直接手动运行 `skills/watch/scripts/` 下的 Python 脚本来使用它（例如在 CodeBuddy 等非 Claude 宿主环境）。

```bash
/watch https://youtu.be/dQw4w9WgXcQ 第 30 秒发生了什么？
```

---

## 一、人们拿它来做什么

- **分析别人的内容**：`/watch <爆款视频> 他们开头用了什么钩子？` —— 看开头几帧、读开场字幕、拆解结构。广告创意、竞品发布、播客开场都适用。
- **从录屏里定位 Bug**：别人发来一段出问题的录屏，`/watch bug-repro.mov 哪里出错了？` —— 看录制、找到问题出现的那一帧并描述画面，往往不用你亲自打开文件就能看出原因。
- **总结视频**：`/watch <长视频> 帮我总结` —— 抽取结构、关键节点、真实说了和展示了什么，比 2 倍速看完更快。
- **滤掉发布会里的噱头**：`/watch <发布会> 真正新增了什么，别管那些吹的` —— 把“改变行业”的功能落地成真正重要的几件事。
- **把播放列表变成笔记**：对一系列视频逐个运行，产出可检索的逐视频摘要。

---

## 二、工作原理（简述）

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` 拉取源站原生字幕（免费、即时）；回退方案：抽取单声道 16kHz 64kbps 的 mp3 音频（约 480 kB/分钟），送往 Whisper —— Groq 的 `whisper-large-v3`（首选，更便宜更快）或 OpenAI 的 `whisper-1`。
5. **帧 + 字幕交给 Claude。** 脚本打印带 `t=MM:SS` 标记的帧路径，以及带时间戳的字幕。Claude 并行 `Read` 每一帧 —— JPEG 会直接作为图片渲染进上下文。
6. **Claude 基于“实际看到的画面 + 听到的声音”作答**，而不是“根据描述”或“根据标题”。
7. **清理。** 脚本最后打印工作目录；若不再追问，Claude 会删掉它。

---

## 三、帧预算——为什么重要

Token 成本主要由帧决定。脚本的自动 fps 逻辑存在的目的，就是避免你为了一段 30 分钟视频的稀疏扫描，把上下文预算烧光——而其实聚焦到 30 秒窗口效果更好。

| 时长 | 默认帧预算 | 你能得到什么 |
|------|-----------|--------------|
| ≤30 秒 | ~30 帧 | 密集——几乎每个关键时刻 |
| 30 秒–1 分钟 | ~40 帧 | 仍然密集 |
| 1–3 分钟 | ~60 帧 | 舒适 |
| 3–10 分钟 | ~80 帧 | 稀疏但可用 |
| >10 分钟 | 100 帧（封顶模式） | 会打印“稀疏扫描”警告——改用聚焦模式，或 `--detail token-burner` 做完整无上限覆盖 |

当用户指定某个时刻（`--start`/`--end`），脚本进入**聚焦模式**，按秒预算更密，上限 2 fps。

---

## 四、安装

| 宿主 | 安装方式 |
|------|----------|
| **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（网页版）** | 从 [最新 Release](https://github.com/bradautomates/claude-video/releases/latest) 下载 `watch.skill` → Settings → Capabilities → Skills → `+` |
| **手动 / 开发** | `git clone` 后把 `skills/watch` 软链到宿主的 skills 目录（见下） |
| **任意环境直接跑脚本** | 见本仓库《操作手册.md》 |

### 手动（开发者）

```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 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` 直接可用。

> 在 CodeBuddy 等不支持 Agent Skills 的宿主里，没有 `/watch` 命令，请按《操作手册.md》直接运行 `watch.py`。

---

## 六、自带密钥

字幕覆盖了绝大多数公开视频，且免费。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 第 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            # 从 1 小时 12 分到最后
```

其他旋钮（传给 `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 先读字幕，再瞄准主讲人标记的“看这里”“注意这个”等时刻。叠加在细节帧之上（占用预算）；聚焦模式下窗口外的 cue 会被丢弃；配合 `--detail transcript` 时这些成为唯一帧。
- `--max-frames N` —— 降低帧上限以收紧 Token 预算。
- `--resolution W` —— 把帧宽提到 1024px（当 Claude 需要读屏上文字时）。
- `--fps F` —— 覆盖自动 fps（仍封顶 2 fps）。
- `--whisper groq|openai` —— 强制指定 Whisper 后端。
- `--no-whisper` —— 完全禁用转录；仅出帧。
- `--no-dedup` —— 保留近似重复帧。
- `--out-dir DIR` —— 把工作文件放到指定目录（默认自动生成的 tmp 目录）。

---

## 八、限制

- **长视频精度取决于细节模式。** 封顶模式（`efficient`、默认 `balanced`）在超过约 10 分钟后覆盖会变稀疏——帧上限摊到整段上。脚本会打印“稀疏扫描”警告，建议改用 `--start`/`--end` 聚焦重跑；`token-burner` 解除上限，保留整段每一个场景切换帧。
- **细节是一个档位。** 默认 `balanced`：场景感知帧、最大 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-skill.sh        # 为 claude.ai 构建 dist/watch.skill（仅开发）
├── hooks/                        # SessionStart 状态钩子（仅 Claude Code）
├── .claude-plugin/               # plugin.json + marketplace.json（Claude Code）
├── .codex-plugin/                # plugin.json —— Codex/agents 清单
├── .agents/plugins/              # marketplace.json —— Agent Skills 市场列表
├── AGENTS.md → CLAUDE.md         # 通用 agent 入口
├── tests/                        # pytest 套件（ffmpeg 合成片段，无网络）
└── .github/workflows/            # release.yml —— 打 tag 时自动构建 watch.skill
```

---

## 十、开发

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

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

发布：打 `vX.Y.Z` tag 并推送。工作流会构建 `dist/watch.skill` 并附到 GitHub Release。请保持 `skills/watch/SKILL.md`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 中的版本一致。

---

## 开源

MIT 协议。基于 `yt-dlp`、`ffmpeg` 以及 Claude 的多模态 `Read` 工具。Whisper 转录通过 [Groq](https://groq.com) 或 [OpenAI](https://openai.com)。

由 Brad Bonanno 构建。