watch-video

观看视频

Claude 无法直接播放视频。此技能通过 Python 流程实现这一点（从 bradautomates/claude-video 移植，位于 scripts/ 下）：下载视频，使用 ffmpeg 提取自动缩放的 JPEG 帧，获取带时间戳的转录文本（优先使用原生字幕，否则回退到 Whisper API），然后输出一份 Markdown 报告，列出每一帧的路径。随后，Claude 会逐帧 Read，将画面与语音内容对应起来，并写入结构化的笔记文件。

何时调用

仅限斜杠命令。 只有当用户明确输入 /watch-video 时，才运行此技能。这是唯一的触发条件。

不要在以下情况下调用：

• “看看这个视频”“总结一下”“为这个 YouTube 视频做笔记”“分析这个短视频”等随口提出的请求
• 用户只粘贴了一个 YouTube URL 并附带问题（“这个视频里有哪些实用技巧？” + URL）
• 任何未明确使用 /watch-video 命令的视频相关自然语言请求

未使用斜杠命令时，默认处理 YouTube 问题的方式： 用最快的方法获取转录文本——抓取 YouTube 页面、使用 yt-dlp 字幕，或访问转录文本网站——浏览后据此作答。除非用户通过 /watch-video 明确要求，否则帧提取流程过于繁琐。

如果你更希望自动触发，请修改上方的 description: 行，使其匹配你希望 Claude 响应的关键词（例如：“当用户希望 Claude 观看、分析视频或做视频笔记时使用”）。本仓库默认仅通过斜杠命令触发，因为明确调用可以避免在长视频上意外消耗 token。

依赖项

• PATH 中需有 ffmpeg + ffprobe — 用于提取帧和音频
• PATH 中需有 yt-dlp — 用于下载视频和获取字幕
• Python 3.9+ — 随附脚本使用 from __future__ import annotations，因此 Python 3.9 也可运行
• 可选： 对于没有原生字幕的视频，需要 Whisper API 密钥。在 ~/.config/watch/.env 中设置 GROQ_API_KEY（优先使用——成本更低、速度更快，运行 whisper-large-v3）或 OPENAI_API_KEY。没有密钥也能正常处理带字幕的视频；没有字幕的视频则只会返回帧。

运行 python scripts/setup.py --check 验证依赖项，或运行 python scripts/setup.py 创建 .env 并检查二进制文件。在 macOS 上，安装程序会通过 Homebrew 自动安装缺失的二进制文件。在 Linux/Windows 上，它会打印具体的安装命令。

流程

具体操作由 scripts/watch.py 完成。它会下载、提取、转录视频，并将列出每一帧路径的 Markdown 报告输出到 stdout。流程会根据视频时长自动调整帧数预算（最多 100 帧 / 2 fps），无需手动调整间隔。

python scripts/watch.py "<youtube-url-or-local-path>" [flags]

值得了解的标志：

• --start T / --end T — 聚焦某个片段（SS、MM:SS 或 HH:MM:SS）。该范围内会自动提高 fps。对于询问特定时刻的问题，或用户的问题只涉及 10 分钟以上视频中的某一部分时，请使用此选项。
• --max-frames N — 降低帧数上限，以控制 token 预算（默认 80，最高 100）。
• --resolution W — 帧宽度，单位为 px（默认 512；仅当屏幕文字无法辨认时才提高到 1024）。
• --whisper groq|openai — 指定 Whisper 后端（默认：如果两个密钥都存在，则优先使用 Groq）。
• --no-whisper — 没有字幕时完全跳过转录。仅输出帧。
• --out-dir DIR — 将工作文件保存在指定位置（默认为自动生成的临时目录）。

自动 fps 预算（完整视频模式）：

• ≤30s → 最多 30 帧
• 30s–1min → 约 40 帧
• 1–3min → 约 60 帧
• 3–10min → 约 80 帧
• >10min → 稀疏抽取 100 帧（会打印警告；可考虑使用 --start / --end）

分步工作流

1. 运行管线

默认调用方式，不带标志：

python scripts/watch.py "<source>"

对于用户询问了特定时刻的长视频，请传入 --start/--end：

python scripts/watch.py "<source>" --start 2:15 --end 2:45

脚本会将所有内容写入临时工作目录，并将 Markdown 报告输出到 stdout。请捕获 stdout — 其中包含：

• 标题（Title）、上传者（Uploader）、时长（Duration）、转录来源（Transcript source）：captions / whisper (groq) / whisper (openai) / none available
• ## Frames 部分，其中包含 - \` (t=MM:SS)` 行
• ## Transcript 部分，其中包含 [MM:SS] text... 行
• 页脚，包含 Work dir: <path>

2. 阅读每一帧

在一条消息中读取所有列出的帧路径（并行调用 Read 工具）。Read 工具会将 JPEG 渲染为图像。报告中每帧的文件名和 t=MM:SS 会标明其出现时间 — 将每帧与该时间戳对应的转录行配对。

对于超长视频（>10 min，稀疏模式）：预算已将帧数上限设为 100，因此读取所有帧没有问题。

3. 编写摘要

默认输出文件：<work-dir>/<slug>-notes.md。如果用户说“将笔记保存到永久位置”，请询问保存位置。

按如下结构编写 Markdown：

# <Title>

**Source:** <URL or local path>
**Duration:** <mm:ss>
**Uploader:** <if from YouTube>
**Transcript source:** <captions / whisper (groq) / whisper (openai) / none>

## One-line summary
<≤20 words — the core claim or hook of the video>

## TL;DR
<3–5 bullet points capturing the main arguments, moments, or beats>

## Timeline
- **[00:00]** <what's happening visually + the key line being said>
- **[00:15]** ...
<one row per meaningful beat, not per frame>

## Key quotes
> "<verbatim quote>" — [mm:ss]

## Visual notes
<what the video shows that the transcript alone would miss — setting, B-roll, on-screen text, graphics, transitions, subject's emotion>

## Takeaways (optional)
<Only include if the content is directly relevant to the user's domain or goals. Omit otherwise.>

4. 清理

写入 .md 后，删除工作目录（其中包含完整下载的视频和帧文件，占用空间很大）。脚本会在报告页脚打印 Work dir: <path>；将该路径传给 rm -rf。

如果用户指定了非临时的 --out-dir，请在删除前征求同意。

常见问题

• YouTube Shorts / 年龄限制 / 仅限会员观看 — yt-dlp 可能会失败。原样显示其 stderr；不要静默重试。
• 没有字幕 + 没有 Whisper 密钥 — 报告会显示 Transcript: none available，并指向 setup.py。告诉用户，他们可以将 Groq 密钥添加到 ~/.config/watch/.env 以使用 Whisper，或使用 --no-whisper 仅处理帧。
• 本地文件没有音轨 — Whisper 提取会正常报错退出。使用 --no-whisper 仅处理帧。
• 超长视频（>30 min） — 运行前请先向用户确认。管线会将帧数上限设为 100，因此预算有上限，但对 60 分钟的视频进行稀疏的 100 帧扫描并不实用。几乎总是更适合聚焦于特定片段。
• Groq 遇到 Cloudflare 403 — whisper.py 已设置自定义 User-Agent，以绕过 Cloudflare 对默认 Python UA 的拦截。如果遇到 403，这就是故障原因。
• 不会自动从 Groq 回退到 OpenAI — 脚本会在每次运行开始时选择一个 Whisper 后端（如果设置了 Groq 密钥则使用 Groq，否则使用 OpenAI），之后不会切换。如果 Groq 限流，脚本会重试 Groq 两次，然后报错。如需使用 OpenAI，请传入 --whisper openai。

不要做的事

• 不要根据标题或缩略图编造内容来假装“观看”视频。如果管线失败，请如实说明。
• 不要在实际阅读帧之前编写摘要。仅凭转录会遗漏视觉上下文（B-roll、屏幕文字、情绪、图形、转场）。
• 不要跳过清理。帧文件和下载的视频占用空间很大。
• 不要自动处理视频 URL。只能通过斜杠命令调用 — 请参阅上文“何时调用”。

引擎归属

scripts/ 下的管线脚本来自 bradautomates/claude-video（MIT）。完整的上游许可证请参阅 THIRD_PARTY_NOTICES.md。