claude-watch

/claude-watch — Claude 将视频转换为学习笔记

你没有视频输入。这个技能会为你提供视频，并且将每次观看转换为已保存的笔记文件。

步骤 0 — 设置预检（成功时静默）

每次调用 /claude-watch 时运行：

python3 "${CLAUDE_SKILL_DIR}/scripts/setup.py" --check

退出代码：0 已就绪（静默 — 继续），2 缺少二进制文件，3 缺少 API 密钥，4 两者都缺少。退出代码非零时，运行安装程序：

python3 "${CLAUDE_SKILL_DIR}/scripts/setup.py"

在 macOS 上，它会自动通过 brew install 安装 ffmpeg 和 yt-dlp。在 Linux/Windows 上，它会打印相应的命令。它会创建 ~/.config/claude-watch/.env（权限模式 0600），其中包含注释形式的占位符。

如果之后仍缺少 Whisper 密钥，请使用 AskUserQuestion 询问用户是否有 Groq 密钥（优先使用 — 更便宜、更快）或 OpenAI 密钥，并将密钥写入 ~/.config/claude-watch/.env。如果用户不想提供密钥，则使用 --no-whisper 运行；没有原生字幕的视频只会返回帧。

适用场景

• 用户粘贴教程 / 讲座 / 演讲的 URL，并要求学习其中内容
• 用户提供本地屏幕录制或视频，并希望获得笔记
• 用户输入 /claude-watch <url-or-path> [topic]

调用方式

步骤 1 — 解析输入。 将来源（URL 或路径）与用户提到的任何主题分开。主题决定笔记中要强调哪些部分 — 将它传递给内容综合环节，而不是脚本。

步骤 2 — 运行观看脚本。

python3 "${CLAUDE_SKILL_DIR}/scripts/watch.py" "<source>"

可选标志：

• --start T / --end T — 聚焦某个片段（SS、MM:SS 或 HH:MM:SS）
• --max-frames N — 降低帧数预算（默认值为 80）
• --resolution W — 当屏幕文字很小时，将帧宽度提高到 1024 px
• --scene-threshold X — 灵敏度（默认值为 0.30；调高可减少切换，调低则会增加切换）
• --max-gap S — 覆盖范围下限，单位为秒（默认值为 45）
• --whisper groq|openai — 指定后端
• --no-whisper — 完全禁用 Whisper
• --out-dir DIR — 覆盖资源库根目录

步骤 3 — 读取每一帧。 脚本结束时会输出结构化的 === frames === 块，其中列出每一帧的路径和时间戳。并行读取所有帧 — 它们会以图像形式呈现在你的上下文中。

步骤 4 — 加载转录文本。 === transcript === 块会指向 transcript.json（聚焦模式下为 transcript.window.json）。读取它 — 这是一个由 {t_start, t_end, text, speaker_break} 组成的列表。

步骤 5 — 将 notes.md 写入资源库目录。 使用下方的严格模板。保存到 <library_dir>/notes.md。然后在聊天中打印 3 行摘要：

1. 标题和 slug
2. 章节数量 + 关键概念
3. 笔记文件的路径

不要删除资源库目录。它就是生成的文件。

笔记模板（结构不可更改）

# <Video Title>

**Source:** <URL or path>  ·  **Duration:** MM:SS  ·  **Watched:** YYYY-MM-DD

## TLDR
<3-4 sentences: what the video is about and the single most important takeaway.>

## Key Concepts
- **<concept>** — <one-line definition> · `[t=MM:SS]`
- ...

## Notes

### [t=00:04] <Section title you derive from on-screen + spoken content>

![](frames/0001_t00-04.jpg)

**On screen:** <Transcribe / describe the slide, code, diagram. If code, transcribe verbatim.>

**Said:** <Relevant transcript excerpt for this scene, lightly cleaned.>

**Synthesis:** <Your connection — what this section is teaching, how it links to prior section.>

### [t=00:31] <next section>
...

## Code & Commands
<every code-on-screen frame's content as a runnable fenced block, language-tagged, with [t=MM:SS] back-link>

```python
# [t=03:45]
def forward(x):
    return x @ W + b
```

## Diagrams Referenced
- `[t=02:10]` — <one-line description of the diagram in frame 0008>
- ...

## Open Questions
- <things mentioned but not fully covered, or follow-ups to explore>

模板中内置的规则

• 一个场景 = 一个章节。 使用每一帧中的 t=MM:SS 作为章节锚点。
• 相邻且主题明显相同的场景可以合并。合并时，在括号中说明：(合并了 t=02:10 和 t=02:42 的场景)
• 代码块必须使用正确的语言标记围栏，并逐字转录画面中的内容。
• 即使是标题页，也必须包含“屏幕内容”块。 这样可以保持结构一致。
• 时间戳使用绝对时间（视频中的实际时间线）— 对于 YouTube 来源，观众可以粘贴 <URL>&t=<seconds> 跳转到该时间点。

重新运行

如果用户重新观看同一个 URL，脚本会重复使用缓存的下载内容、转录文本和场景。只有帧和笔记会重新生成。若要强制完整重新运行，请先删除 <library_dir>/meta.json。

故障模式

• 设置预检退出代码非零 → 运行 setup.py，然后通过 AskUserQuestion 索取密钥。
• 没有转录文本 → 脚本会输出 transcript_source: none。仅根据帧生成笔记，并告知用户。
• 长视频稀疏扫描警告 → 提议使用 --start / --end 重新运行，聚焦用户关注的部分。
• Whisper 失败 → 使用 --whisper openai 重试（如果 Groq 失败），反之亦然。

Token 预算

帧占据了主要成本（60 帧、512 px 时约需 50–80k 个输入 token）。转录内容开销很低。--resolution 1024 会使每帧成本翻四倍——仅当用户必须阅读屏幕上很小的文字时才使用。

如果用户针对本次会话中你已经看过的视频提出后续问题，请勿重新运行脚本。资料库目录位于磁盘上；只需重新 Read 所需的帧。

安全性

• 在本地运行 yt-dlp、ffmpeg、ffprobe
• 仅当缺少字幕时，才会将提取的单声道 16 kHz 音频发送给 Groq（首选）或 OpenAI Whisper API
• 为密钥读取/写入 ~/.config/claude-watch/.env（模式为 0600）
• 将生成的文件保存在 ~/claude-watch/library/<slug>/ 中——如果你比较谨慎，可在首次运行后检查该目录
• 不会在音频转 Whisper 调用之外记录或传输 API 密钥、视频文件或原始 URL