/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> | 转录 (默认) | 干净文本、元数据、可选章节 |
/watch-video <url> transcript | 转录 | 与默认相同 |
/watch-video <url> visual | 视觉 | 转录 + 间隔帧 + Claude 视觉分析识别关键时刻 |
/watch-video <url> multimodal | 多模态 | Gemini 原生视频理解(若有 $GEMINI_API_KEY),否则密集逐帧 Claude 视觉分析 |
如果未指定深度且视频长度超过 10 分钟,则在默认前询问(视觉/多模态对长视频成本较高)。
步骤 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/localslug:标题的短横线命名形式(前 4–6 个单词,最多 50 字符)date:YYYY-MM-DD
步骤 5 — 获取转录
后端选择(按顺序):
-
平台提供的转录(如果存在且看起来完整):
- 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。
- YouTube:
-
MLX-Whisper 本地(默认备用 — 在 Mac M 系列上快速):
# 安装一次: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> -
whisper.cpp(如果 MLX 不可用时的进一步备用)
如果视频是 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 清理 — 去重滚动字幕,去除标签,在提示间隙 >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.txtmetadata.json- 聊天中的一行摘要:标题、来源、时长、单词数
- 工作目录路径
- (可选)步骤 9 — 提供捕捉到第二大脑的选项
步骤 7 — 如果是 visual 模式:提取帧 + 视觉分析
帧提取 (ffmpeg)
根据来源启发式的节奏:
| 来源类型 | 帧节奏 |
|---|---|
| 屏幕共享 / Loom / 演示 | 每 5 秒 1 帧(UI 变化快) |
| 演讲者头部特写 / 播客 | 每 30 秒 1 帧(变化慢) |
| 幻灯片演示 | 每 10 秒 1 帧 + 在检测到的每个场景变化处强制一帧 |
| 不确定时默认 | 每 15 秒 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 视觉进行综合。
每帧批次提示(每次调用最多约 10 帧):
这是来自视频时间戳 T1..TN 的 N 帧。对于每帧,用 1–2 句话描述屏幕上的内容。标记:(a) 与前一帧相比的 UI 变化,(b) 屏幕上可见的文本,(c) 任何看起来像决策、操作或值得注意的事件的时间点。同时注意此窗口期间所说的转录文本。
将输出保存为 <workdir>/moments.md:
# 关键时刻 — <title>
## 00:00:15 (frame-001.png)
**屏幕上**: 登录表单,邮箱字段获得焦点
**转录**: "所以你只需打开它..."
**备注**: UI 演示开始
## 00:00:45 (frame-002.png)
**屏幕上**: 包含 4 个卡片的面板
**转录**: "这里就是你看到所有项目的地方。"
**备注**: 主要视图变化 — 首次出现面板
生成摘要
识别关键时刻后,将整个视频综合到 <workdir>/summary.md:
# 摘要 — <title>
**来源:** <source URL / file>
**时长:** <hh:mm:ss>
**观看时间:** <date>
**模式:** visual
## 简要总结
<2–4 句话>
## 关键时刻
- 00:00:15 — <一行>
- 00:00:45 — <一行>
## 标记的操作项
- <item> [timestamp]
## 标记的决策
- <decision> [timestamp] — 考虑路由到 /decide
## 值得保留的引文
- "..." [timestamp]
## 未解决的问题
- <提出但未回答的问题>
步骤 8 — 如果是 multimodal 模式
后端选择
-
Gemini 原生 如果设置了
$GEMINI_API_KEY(对于长视频比逐帧便宜得多 + 更快):默认模型:
gemini-3.5-flash(发布于 2026 年 5 月,约每百万 token $1.50 输入 / $9 输出;每秒视频约 $0.15;在编码/智能体基准上以 4 倍速度超越 3.1 Pro)。对于品牌审计 / 高利害分析(细节重要时)重写为gemini-3.1-pro;对于批量廉价处理使用gemini-2.5-flash-lite。# 步骤 1:通过 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') # 等待文件变为 ACTIVE(Gemini 首先处理视频) while true; do STATE=$(curl -s "$FILE_URI?key=$GEMINI_API_KEY" | jq -r '.state') [ "$STATE" = "ACTIVE" ] && break sleep 3 done # 步骤 2:使用文件 + 多模态分析提示生成内容 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\":\"<多模态分析提示 — 参见步骤 7 的摘要模板 + 用例扩展>\"} ] }] }"文件在 Gemini Files API 中持续存在约 48 小时 — 对于用不同提示重新查询同一视频很有用。
-
密集 Claude 视觉备用(如果没有 Gemini 密钥):
- 帧节奏:每 3 秒 1 帧(比视觉模式密集得多)
- 使用多模态分析提示批量通过 Claude 视觉
- 对于长视频比 Gemini 更慢且更昂贵 — 在 >10 分钟内容上运行前警告用户
多模态输出
与步骤 7 相同的 summary.md 模板 + 一个扩展部分:
## 多模态观察
- **肢体语言 / 表达**: <关于演讲者头部特写视频的观察>
- **节奏**: <快/慢/不均匀>
- **视觉风格**: <品牌审计、广告审核、设计观察>
- **音频质量 / 氛围**: <音乐、静音、背景音>
确切的额外部分取决于用例(品牌审计、广告审核、演讲表达评审、客户通话读取)。用例根据来源和用户在调用时的口头表述推断。
步骤 9 — 可选:捕捉到第二大脑
在任何模式完成后,提供:
"要将其捕捉到第二大脑吗?我会将摘要、来源 URL 和转录链接写入
${SECOND_BRAIN_VAULT:-$HOME/Documents/SecondBrain}/raw/目录下的call-<slug>.md(或meeting-/note-/resource-)。"
按来源的类型前缀:
| 来源 | 前缀 |
|---|---|
| Loom / Zoom / Riverside / Otter / 通话录制 | call- |
| 会议(自己的笔记,不是转录) | meeting- |
| 演讲 / 主题演讲 / 会议 | note- |
| 广告 / 落地页视频 / 营销参考 / 竞争对手视频 | resource- |
文件内容:1 行来源、摘要、指向完整工作目录的链接。
步骤 10 — 报告
在聊天中:
- 一行标题:
<source> · <title> · <duration> · <mode> · <word count> 个单词 - 工作目录路径
- 对于
visual/multimodal:简要列出前 3 个关键时刻 - 对于所有模式:任何标记的操作项 / 决策,用于分类
- 如果已捕捉到第二大脑:该路径也
来源参考
| 来源 | 下载 | 内置转录 | 备注 |
|---|---|---|---|
| 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 (Mac) |
| 缺少 ffmpeg(用于视觉/多模态) | 告诉用户:brew install ffmpeg |
| 视觉分析返回空 / 不清晰 | 降低帧数,重试,或回退到仅转录并附注 |
请求多模态但无 $GEMINI_API_KEY 且 >30 分钟视频 | 警告成本,建议回退到视觉模式 |
缺少 yt-dlp 二进制文件 | brew install yt-dlp |
关于质量的备注
- 用户选择深度,而非技能。 转录 / 视觉 / 多模态是三种不同的成本 + 延迟配置。长视频(>10 分钟)在花费视觉/多模态前始终确认。
- 首选平台转录,其次 Whisper。 YouTube 自动字幕、Loom 转录、Riverside 内置转录 — 在它们存在时都是免费且即时的。仅在无平台提供内容时才回退到 MLX-Whisper 本地。
- MLX-Whisper 本地是 Mac 上的快速路径。 M 系列机器的转录速度快于实时。云端 Whisper 是远距离的第二选择 — 花费金钱、依赖网络、在典型时长上延迟更差。
- 按来源类型的帧节奏。 屏幕共享 / 演示需要每 5 秒 1 帧(UI 变化快);演讲者头部特写播客需要每 30 秒 1 帧(变化慢)。如果不确定,默认为 15 秒。错误的节奏 = 错过关键时刻或浪费视觉分析成本。
- 720p 已足够。 下载 1080p / 4K 用于转录 + 帧分析浪费带宽 + 存储。
yt-dlp -f "bv*[height<=720]+ba/b[height<=720]"是默认选项。 - 场景变化检测捕捉幻灯片过渡。 当视频是幻灯片演示时,添加
ffmpeg -vf "select='gt(scene,0.3)'"以在每个检测到的幻灯片变化处强制一帧 — 比纯基于时间的采样更可靠。 - 多模态成本警告不是可选的。 对 60 分钟视频使用 Gemini 多模态成本相当高。在运行前警告;如果用户不确定,提供仅转录作为备用。
- 摘要格式包含路由提示。
## 标记的决策+## 标记的操作项部分发出/decide和/pm后续操作的信号。下游的可组合性依赖于摘要结构。