watch-video

/watch-video — 按你选择的深度转录和分析任意视频

替代并扩展了先前的 youtube-transcript 技能。YouTube 现在只是众多来源之一；分析深度由用户控制。

第 1 步 — 解析输入

接受：

• YouTube：完整 URL、youtu.be/<id>、youtube.com/shorts/<id>、11 个字符的原始 ID
• Loom：loom.com/share/<id> 或 loom.com/embed/<id>
• Vimeo：vimeo.com/<id>
• Riverside：下载 URL 或本地文件
• Zoom：已下载录制内容中的本地 .mp4
• X / IG / TikTok 视频：URL — 将元数据获取交由 social-fetch 处理，并使用 yt-dlp 下载文件
• 本地文件：任意 .mp4 / .mov / .webm / .mkv 文件路径

根据 URL 模式或文件扩展名检测来源。如果无法确定，请询问。

第 2 步 — 解析深度模式

调用方式	模式	结果
/watch-video <url>	transcript（默认）	清理后的文本、元数据、可选章节
/watch-video <url> transcript	transcript	与默认模式相同
/watch-video <url> visual	visual	转录文本 + 按间隔提取的帧 + Claude 视觉分析，用于识别关键时刻
/watch-video <url> multimodal	multimodal	将原生视频交给 Gemini（如果有 $GEMINI_API_KEY），否则由 Claude 逐帧密集分析画面

如果未指定深度，且视频时长超过 10 分钟，请在使用默认模式前先询问（长视频的 visual/multimodal 模式确实会产生费用）。

第 3 步 — 获取元数据

对于 URL 来源，使用 yt-dlp：

yt-dlp --print "%(title)s|%(uploader)s|%(duration_string)s|%(upload_date>%Y-%m-%d)s|%(description)s" \
  --print "%(chapters)j" --skip-download "<url>"

提取：标题、上传者/频道、时长、上传日期、简介（第一段）、章节（JSON 或 null）。

对于本地文件，使用 ffprobe：

ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "<file>"

第 4 步 — 创建工作目录

~/Documents/videos/<source>-<slug>-<date>/

其中：

• source：youtube / loom / vimeo / riverside / zoom / local
• slug：标题的 kebab-case 形式（前 4–6 个单词，最多 50 个字符）
• date：YYYY-MM-DD

第 5 步 — 获取转录文本

后端选择（按顺序）：

1. 平台提供的转录文本，前提是存在且看起来完整：

   • YouTube：yt-dlp --write-sub --write-auto-sub --skip-download --sub-lang en --sub-format vtt
   • Loom：通过 https://www.loom.com/share/<id> 页面元数据获取；或在设置了 $LOOM_API_KEY 时使用 Loom API
   • Riverside：录制内容的分享页面提供内置转录文本
   • 如果平台提供的转录文本包含时间戳，则使用它。跳过 Whisper。

2. 本地 MLX-Whisper（Apple Silicon Mac 的默认选项）：

   # Install once: pip install mlx-whisper
   python3 -c "import mlx_whisper; mlx_whisper.transcribe('<file>', path_or_hf_repo='mlx-community/whisper-large-v3-turbo')" \
     > "<workdir>/transcript-raw.json"
   

   或通过 CLI 运行：mlx_whisper <file> --model mlx-community/whisper-large-v3-turbo --output-dir <workdir>

3. 非 Apple Silicon 设备（Linux、Intel Mac、Windows、云端 Agent）：使用 faster-whisper（pip install faster-whisper，支持 CPU 或 CUDA）或 whisper.cpp。模型大小和输出处理方式相同。

如果输入是 URL，请先下载视频文件（使用 yt-dlp；Loom/Vimeo/YT 均受支持）：

yt-dlp -f "bv*[height<=720]+ba/b[height<=720]" -o "<workdir>/video.%(ext)s" "<url>"

720p 足以用于转录和画面分析（下载文件更小，处理更快）。

清理转录文本（仅适用于带滚动字幕的 YouTube 自动字幕；Whisper 输出已是干净文本）：

# YouTube VTT cleanup — de-dup rolling captions, strip tags, paragraph-break on cue gaps >2s
awk '
  /^WEBVTT/ || /^Kind:/ || /^Language:/ || /^NOTE/ { next }
  /-->/ { in_cue = 1; last = ""; next }
  /^$/ { if (last) print last; in_cue = 0; last = ""; next }
  in_cue { gsub(/<[^>]+>/, "", $0); last = $0 }
  END { if (last) print last }
' "<workdir>/transcript.en.vtt" | awk '!seen[$0]++' > "<workdir>/transcript.txt"

将最终文件保存至 <workdir>/transcript.txt。

第 6 步 — 如果是 transcript 模式：到此为止

输出：

• transcript.txt
• metadata.json
• 聊天中的单行摘要：标题、来源、时长、字数
• 工作目录路径
• （可选）第 9 步 — 提议保存到第二大脑

第 7 步 — 如果是 visual 模式：提取帧并进行视觉分析

提取帧（ffmpeg）

根据来源类型启发式地设定提取间隔：

来源类型	提取间隔
屏幕共享 / Loom / 演示	每 5s 提取 1 帧（界面变化很快）
人物出镜 / 播客	每 30s 提取 1 帧（变化较慢）
幻灯片演示	每 10s 提取 1 帧 + 对检测到的每次场景变化强制提取一帧
无法确定时的默认值	每 15s 提取 1 帧

mkdir -p "<workdir>/frames"
ffmpeg -i "<workdir>/video.mp4" -vf "fps=1/15" "<workdir>/frames/frame-%04d.png" -y

检测场景变化（尤其适用于幻灯片）：

ffmpeg -i "<workdir>/video.mp4" -vf "select='gt(scene,0.3)',showinfo" -vsync vfr "<workdir>/frames/scene-%04d.png" 2> "<workdir>/scene-detection.log"

视觉分析

将每一帧与相同时间段的转录文本片段配对。然后批量发送给 Claude vision 进行综合分析。

逐帧批处理提示词（每次调用最多约 10 帧）：

以下是视频中时间戳为 T1..TN 的 N 帧。请用 1–2 句话描述每一帧中屏幕上显示的内容。标记：（a）与上一帧相比的 UI 变化；（b）屏幕上可见的文字；（c）看起来像是决策、操作或值得注意事件的时刻。同时注明此时间段内说出的转录文本。

将输出保存为 <workdir>/moments.md：

# Key moments — <title>

## 00:00:15 (frame-001.png)
**On screen**: Login form, email field focused
**Transcript**: "So you just open it up and..."
**Note**: Beginning of UI demo

## 00:00:45 (frame-002.png)
**On screen**: Dashboard with 4 cards
**Transcript**: "And here's where you see all your projects."
**Note**: Major view change — first time the dashboard appears

生成摘要

识别出各个时刻后，将整个视频综合整理到 <workdir>/summary.md：

# Summary — <title>

**Source:** <source URL / file>
**Duration:** <hh:mm:ss>
**Watched at:** <date>
**Mode:** visual

## TL;DR
<2–4 sentences>

## Key moments
- 00:00:15 — <one-line>
- 00:00:45 — <one-line>

## Action items flagged
- <item> [timestamp]

## Decisions flagged
- <decision> [timestamp] — consider routing to /decide

## Quotes worth keeping
- "..." [timestamp]

## Open questions
- <question raised but not answered>

步骤 8 — 如果是 multimodal 模式

后端选择

1. Gemini 原生模式：如果设置了 $GEMINI_API_KEY（处理长视频时比逐帧方式便宜得多，也快得多）：

   默认模型：gemini-3.5-flash（于 2026 年 5 月发布，输入每 100 万个 token 约 $1.50，输出每 100 万个 token 约 $9；视频每秒约 $0.15；在编码/Agent 基准测试中的表现优于 3.1 Pro，速度快 4 倍）。品牌审查或注重细节的高风险分析可切换为 gemini-3.1-pro；批量低成本处理可使用 gemini-2.5-flash-lite。

   # Step 1: Upload video via Files API
   FILE_URI=$(curl -s -X POST "https://generativelanguage.googleapis.com/upload/v1beta/files?key=$GEMINI_API_KEY" \
     -H "X-Goog-Upload-Command: start, upload, finalize" \
     -H "Content-Type: video/mp4" \
     --data-binary "@<workdir>/video.mp4" | jq -r '.file.uri')
   
   # Wait until file is ACTIVE (Gemini processes the video first)
   while true; do
     STATE=$(curl -s "$FILE_URI?key=$GEMINI_API_KEY" | jq -r '.state')
     [ "$STATE" = "ACTIVE" ] && break
     sleep 3
   done
   
   # Step 2: Generate content with the file + multimodal-analysis prompt
   curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent?key=$GEMINI_API_KEY" \
     -H "Content-Type: application/json" \
     -d "{
       \"contents\":[{
         \"parts\":[
           {\"file_data\":{\"mime_type\":\"video/mp4\",\"file_uri\":\"$FILE_URI\"}},
           {\"text\":\"<multimodal analysis prompt — see Step 7's summary template + use-case extensions>\"}
         ]
       }]
     }"
   

文件会在 Gemini Files API 中保留约 48 小时，方便使用不同提示词重新查询同一视频。

2. Claude 密集视觉分析回退方案（未设置 Gemini 密钥时）：
   • 帧间隔：每 3s 1 帧（比视觉模式密集得多）
   • 使用多模态分析提示词，通过 Claude vision 批处理
   • 处理长视频时比 Gemini 慢且成本更高——处理超过 10 分钟的视频前，请提醒用户

多模态输出

使用与步骤 7 相同的 summary.md 模板，并添加一个扩展部分：

## Multimodal observations
- **Body language / delivery**: <observations on talking-head video>
- **Pacing**: <fast/slow/uneven>
- **Visual style**: <brand audit, ad review, design observations>
- **Audio quality / atmosphere**: <music, silence, background>

具体附加部分取决于使用场景（品牌审查、广告审查、演讲表现评估、客户通话解读）。使用场景根据来源以及用户调用时的口头说明推断。

步骤 9 — 可选：保存到 second-brain

任何模式完成后，询问用户是否要保存：

“要将内容保存到 second-brain 吗？我会在 ${SECOND_BRAIN_VAULT:-$HOME/Documents/SecondBrain}/raw/ 中写入一个 call-<slug>.md（或 meeting- / note- / resource-）文件，包含摘要、来源 URL 和转录文本链接。”

根据来源选择文件名前缀：

来源	前缀
Loom / Zoom / Riverside / Otter / 通话录音	call-
会议（自己的笔记，而非转录文本）	meeting-
演讲 / 主题演讲 / 会议	note-
广告 / 落地页视频 / 营销参考资料 / 竞品视频	resource-

文件正文：1 行来源信息、摘要、指向完整工作目录的链接。

步骤 10 — 报告

在聊天中：

• 一行标题：<source> · <title> · <duration> · <mode> · <word count> words
• 工作目录路径
• 对于 visual / multimodal：简要列出最重要的 3 个时刻
• 对于所有模式：列出需要分流处理的行动项 / 决策
• 如果已保存到 second-brain：也提供该路径

来源参考

来源	下载方式	内置转录文本	备注
YouTube	yt-dlp	自动字幕（--write-auto-sub）	与之前的 youtube-transcript 技能相同
Loom	yt-dlp（支持 Loom）	有 — 通过嵌入元数据或 Loom API 获取	异步屏幕共享场景的重点用途
Vimeo	yt-dlp	有时有	营销/嵌入式视频
Riverside	导出文件中的直接 URL，或本地文件	有 — Riverside 会生成	播客节目
Zoom	本地 .mp4（下载的录制文件）	有时有（Zoom 音频转录文件）	客户通话
X / IG / TikTok	元数据使用 social-fetch，文件使用 yt-dlp	无	短视频
本地文件	不适用	不适用	提供路径

组合使用

• social-fetch — 在处理视频前获取 X/IG/TikTok URL 元数据（互动数据、作者、回复）
• second-brain — 根据来源类型，将摘要保存为 raw/call-<slug>.md、meeting-、note- 或 resource-
• decide — 当视频包含已标记的决策时，转到 /decide 进行结构化记录
• pm — 摘要中标记的待办事项可分流到项目看板
• slide-deck — 演讲录制内容 → 提取大纲 → 起草演示文稿（循环）
• jab-hook — 播客／演讲视频中的引言和适合剪辑的片段可用于 BIP／宣传帖子
• skillify from-video — 流程录制内容在 visual 模式下的主要用例。用户录制自己执行工作流的过程（Loom／屏幕共享），此技能提取转录文本和关键视觉片段，然后由 skillify 将工作流综合整理为 SKILL.md。“录制一次，AI 转换为技能。”

错误处理

失败情况	响应
视频不可用／私密／受地区限制	告知用户并停止
没有字幕且未安装 Whisper	告知用户：pip install mlx-whisper（Apple Silicon）或 pip install faster-whisper（其他设备）
缺少 ffmpeg（用于视觉／多模态处理）	告知用户：brew install ffmpeg
视觉分析返回空结果／不清晰	减少帧数后重试，或附上说明并退回仅使用转录文本
请求多模态处理，但没有 $GEMINI_API_KEY 且视频时长超过 30min	提示费用，询问是否改用视觉模式
缺少 yt-dlp 二进制文件	brew install yt-dlp

关于质量的说明

• 由用户选择深度，而非技能。 转录文本／视觉／多模态是三种成本和延迟各不相同的处理方式。长视频（>10 min）在进行视觉／多模态处理前，始终先确认。
• 先用平台转录，再用 Whisper。 YouTube 自动字幕、Loom 转录文本、Riverside 内置转录文本——只要存在，都是免费且即时的。只有在平台提供的方式都不可用时，才退回到本地 Whisper。
• 本地 Whisper 是快速路径。 M 系列 Mac 上的 MLX 转录速度快于实时；其他设备上可使用同等方案 faster-whisper。云端 Whisper 是次选方案——需要付费、依赖网络，而且在常见视频时长下延迟更高。
• 根据来源类型调整帧采样频率。 屏幕共享／演示需要每 5s 采样 1 帧（UI 变化快）；访谈类播客每 30s 采样 1 帧即可（变化慢）。不确定时默认每 15s 采样 1 帧。频率不当会导致错过关键片段，或浪费视觉分析成本。
• 720p 足够。 为转录和帧分析下载 1080p／4K 会浪费带宽和存储空间。默认使用 yt-dlp -f "bv*[height<=720]+ba/b[height<=720]"。
• 场景变化检测可捕捉幻灯片切换。 如果视频是幻灯片演示，添加 ffmpeg -vf "select='gt(scene,0.3)'"，强制在每次检测到幻灯片切换时提取一帧——这比单纯按时间间隔采样更可靠。
• 多模态费用警告不可省略。 对 60-min 视频进行 Gemini 多模态处理费用相当高。运行前先警告用户；如果用户不确定，提供仅使用转录文本的备选方案。
• 摘要格式包含后续路由提示。 ## Decisions flagged 和 ## Action items flagged 部分用于提示后续使用 /decide 和 /pm。下游组合能力体现在摘要结构中。