Home

claude-session-recorder / vhs-demo Wiki

把終端機操作變成有旁白、經過同步驗證的 1920×1080 教學影片。

這個專案是什麼

本 repo（vhs-demo）是一套「敘事式終端機教學影片」的產線，核心亮點是 claude-session-recorder：錄下一場真實的 Claude Code TUI session， 右側疊上 explainshell 風格的解說面板，並配上先於畫面動作的語音旁白—— 你會先聽到「這個指令要做什麼」，然後才看到它出現。

成品是一支 1920×1080 的 MP4：左側終端機、右側面板、語音三者永遠 lock-step， 而且是確定性（deterministic）產出——claude 只跑一次，之後把錄影中的靜態片段 用 freeze-frame splice 重新對齊到已寫好的旁白上。不用重拍、不會飄移。MIT 授權。

四種製作路徑

1. CLI lesson — 打一條指令，逐 token 解析它的 flags（rsync、jq、awk、sed→gsed、grep、find、tar、fzf、ssh、rg、ifconfig、df、cp …）。
2. mdp slideshow — 把 Markdown 簡報跑成終端機 slideshow，搭配細節面板。
3. nvim code-demo — 驅動編輯器現場寫程式並執行。
4. live Claude Code session — 錄下真實的 claude TUI 執行過程，從 hook 時間碼與 transcript 產生旁白（engine/experimental/session-recorder/live/）。

快速開始

pip install -e engine/experimental/session-recorder/live
record-session /tmp/demo engine/experimental/session-recorder/live/script.example.json
# → /tmp/demo/session_panel.mp4

Repo 佈局

engine/                 標準渲染引擎（TEMPLATE / source-of-truth）
  src/                  clipkit.py、build.py、overlay.py、verify_sync.py、bundle.py、envcheck.py
  experimental/         slideshow/（mdp）、nvim/、session-recorder/（hooks + live/）
<slug>/                 一個可攜的 clip：vendored src/ + lesson.py + config.toml
                        + setup.sh + CLAUDE.md + <slug>.mp4/.srt + provenance/
.claude/workflows/clip.js   /clip 動態 workflow
material/               放要做成 clip 的題材
docs/plans/             設計與實作計畫文件

同步是怎麼做到的（核心概念）

一段連續的旁白；畫面上的動作被釘（pin）在旁白的句子邊界上 （edge-tts 會給每個句子真實的 timestamp）。終端機真實的 clear frame 從影片像素偵測出來，面板就在螢幕清空的那一格切換。同步是用迴圈工程化的： verify_sync.py 有五道 gate，任何東西都不會默默出貨。

Wiki 頁面導覽

頁面	內容
Maintenance	維護指南：引擎修改流程、pipeline、所有 hard-won gotchas
Roadmap	路線圖：「majestic Claude Code tutorial」計畫與現況
Plan and Tech Debt	計畫文件索引與已知技術債清單