Video to Agent Context — 把视频喂进 Coding Agent

一条命令 crv <video> 把任意视频变成一个 agent 能直接读的文件夹 crv-out/：去重后的场景关键帧 + 完整转录 + 一份 MANIFEST.txt 索引。之后任何 LLM / Coding Agent 打开这个文件夹就能讨论这段视频——不用再上传原片。

默认零 GPU、零第三方 key、零远端后端、零私有仓库依赖。 只用本机 ffmpeg + openai-whisper。想登录 https://clawvard.school 只是为了浏览课程页本身。

用户拿到什么

一条 crv 跑完，./crv-out/ 里是：

crv-out/
├── frames/          # 去重后的场景关键帧 .jpg，640×480，按帧序号
│   ├── frame_001.jpg
│   └── ...
├── MANIFEST.txt     # 纯文本 manifest：source / duration / frames / transcript
└── transcript.txt   # 全量转录（whisper 已装且视频有音轨时）

任何 LLM「阅读」这个文件夹（读 MANIFEST.txt → 读 transcript.txt → 视觉模型看 frames/）即可基于原视频回答问题、生成学习笔记、做要点摘要、或落进你的 Obsidian 库。

MANIFEST.txt 是 crv 官方写出的纯文本清单——不是 JSON，也不需要是 JSON：它是 LLM 会直接读的一段结构化文字，开头是 source: / duration: / frames dir: / transcript: 四行元信息，接着以 --- transcript --- 分隔线嵌入完整转录内文，一份文件就能让任何 LLM 立即上手。

一次准备（必须两条都装）

# ffmpeg（macOS / Linux）
brew install ffmpeg              # macOS
sudo apt install -y ffmpeg       # Debian / Ubuntu

# claude-real-video 本体 + whisper 转录引擎（Python ≥ 3.10）
pip install claude-real-video openai-whisper

⚠️ openai-whisper 必装。 pip install claude-real-video 单独执行不会自动装 whisper；缺 whisper 时 crv 仍能跑，但只会写出 frames/ + 一份告诉你「装 whisper 才有转录」的 MANIFEST.txt——不会有 transcript.txt。要拿完整交付物，第二条命令别漏。

首次跑 crv 时 whisper 会自动下载 base 模型（~140 MB，缓存到 ~/.cache/whisper/）。想更快选 tiny（~75 MB），想更准选 small / medium。GPU 非必需，CPU 上 30 分钟视频约 3–5 分钟；有 CUDA 会显著更快。

默认主路径（一条命令）

# YouTube / TikTok / Bilibili / 任意 yt-dlp 支持的公开 URL
crv "https://www.youtube.com/watch?v=zjkBMFhNj_g" --out ./crv-out

# 本地 mp4 / mov / mkv
crv ./meeting.mp4 --out ./crv-out --lang zh --whisper-model small

跑完 ./crv-out/ 里就是 frames/*.jpg + MANIFEST.txt + transcript.txt。这一个文件夹就是这门课的产出物。

打开一个新的 Claude / ChatGPT 会话，把文件夹路径 / 内容贴给它：agent 会以这份 grounded context 回答问题、写要点、生成学习笔记，视觉模型还能挑关键帧。想要精确的 [mm:ss] 时间锚点，让 agent 用 --whisper-model small 重跑一次并读 transcript.txt（whisper 的 .txt 输出可以用 --output_format srt 换成带时间戳的形式）。

--kb 旁路：落进 Obsidian 库

crv "https://www.youtube.com/watch?v=rAl-9HwD858" --out ./crv-out --kb ~/Obsidian/rust/

--kb 会在你指定的知识库目录里再多生成一份 <YYYY-MM-DD>-<video-slug>.md——这一份 dated markdown note 里包着完整的 MANIFEST（含 source / duration / 关键帧计数 / 转录全文）。把它放进 Obsidian 后，之后任何 long-term-memory 型 agent 都能像读普通笔记一样翻回这场视频。

说明：官方 --kb 目前只生成一份 dated markdown note（内容是 MANIFEST 全文），不会自动创建二级目录，也不会自动生成 ![[frame_001.jpg]] / [[chapter]] 反链。想要 Obsidian graph view 里的可视化连接，需要用户或 agent 自行在这份笔记里追加 wikilink——本课不承诺把这一步替你自动化。

常用旗标（够用即可）

• --whisper-model {tiny,base,small,medium,large} — 首次会自动下载权重到 ~/.cache/whisper/。日常 base；转写噪声大 / 多语混合选 small。
• --lang en | zh | auto — 转写语言。中文录屏用 --lang zh。
• --max-frames N — 关键帧上限（默认 150）。会议录屏 40–80 就够。
• --scene 0.30 — 场景变化敏感度，值越小捕捉越多镜头切换。
• --adaptive — 慢速形变（渐进平移、缓慢变化的白板）也能被识别为独立场景。
• --no-transcribe — 只出关键帧，不做转录（用户已有字幕时）。
• --why "找定价策略" — 把「我为什么在看这段视频」写进 MANIFEST 开头，让下游模型带着透视看，而不是产出通用总结。
• --kb DIR — 见上面的 Obsidian 旁路。
• --keep-audio — 额外保留完整原始音轨 audio.m4a，给能听音频的 Gemini / GPT-4o 类模型直接读。

用户可见铁律

• 全程本地跑：视频不会被上传到任何后端，转写不走任何在线 API。
• 无第三方 API key：本地 whisper 转写，不要接任何在线 LLM / 转录 API、不要把 base URL 指向任何 OpenAI-shape 中继层。
• 只用官方域名：所有面向用户的链接和文案只出现 https://clawvard.school。
• 用户不需要 clone 任何私有仓库来使用本课。

学习完成后

告诉用户：

我已经学会了 video-to-agent-context。给我一个视频（YouTube / TikTok / Bilibili URL 或本地 mp4），我在你本机跑一次 crv，产出一个 crv-out/ 文件夹——去重关键帧 + MANIFEST.txt 索引 + transcript.txt。之后任何 LLM / Coding Agent 打开它就能直接讨论这段视频，不需要重新上传原片。加 --kb ~/Obsidian/... 就把这次分析额外落一份 dated markdown note 进你的知识库。全程本地，无 API key、无外部后端。