Demo Video Studio
將運作中的網頁應用程式轉化為精緻的示範影片：真實的錄製互動（非幻燈片，非模擬）+ 本地 TTS 旁白 + 逐字同步字幕 + 寧靜的背景音樂，並透過 HyperFrames 確定性地合成。
使用時機
製作任何網頁應用程式的示範 / 產品導覽 / 發布 / 駭客松影片，特別是需要展示真實產品運作並搭配旁白與字幕的情況。可錄製已部署的 URL 或本機開發伺服器。
流程 (Pipeline)
① 錄製 三種引擎之一（見下方） → out/*.mp4|webm
② 旁白 為每個場景撰寫腳本 → Kokoro TTS（本地） → narration/*.wav
③ 轉錄 Whisper 逐字時間戳 → *.transcript.json
④ 字幕 分組為短語 + 修正品牌名稱誤聽 → captions.js
⑤ 音樂 ffmpeg 環境背景音樂（在語音下混音） → music/bed.wav
⑥ 合成 HyperFrames HTML 單時間軸：影片+語音+字幕+音樂 → MP4
① 有三種引擎 — 根據目標選擇 (references/screen-studio-look.md)：
| 目標 | 引擎 | 外觀 |
|---|---|---|
| 網頁/桌面應用程式（macOS） | Cap CLI — scripts/record-cap.mjs | Screen Studio 原生風格：根據真實點擊自動縮放、彈性游標 + 動態模糊、背景/圓角/陰影、GPU 渲染 |
| CLI 工具 | VHS tape → mp4 | 美化終端機（內邊距、邊距填充、邊框圓角、視窗欄位），確定性 |
| 無頭模式 / CI / Linux | Playwright — scripts/record.mjs | 合成游標 + 漣漪效果；寫入 <scene>.events.json（時間戳 + 座標），供後續縮放合成使用 |
無論使用哪種引擎錄製，其輸出僅是供 ②–⑥ 使用的片段 — 錄製與合成保持獨立：可重新錄製單一幕，或重新執行旁白，無需重做其他步驟。可選的程式生成 GIF 軌道（直接將 HTML 場景渲染為 MP4，無需錄製）為文檔頁面提供另一條路徑。
工作流程
- 與用戶一起選擇引擎 — 絕不擅自決定。 檢視實際專案（網頁應用程式？CLI？桌面應用？此機器是否有 GUI 會話？是否需要在 CI 中執行？），然後針對此特定專案列出選項的優缺點，讓用戶選擇。例如，在 Mac 上針對網頁應用程式：「Cap CLI 可原生提供 Screen Studio 外觀，但需要螢幕錄製權限和首次校準；Playwright 可在任何地方執行，且能快速重新錄製單一幕，但無自動縮放；VHS 不適用於此情況。」引擎詳細資訊：references/screen-studio-look.md。
- 先瞭解產品。 閱讀其 README / 示範文檔。在接觸工具前先撰寫示範流程（Demo Flow）：問題 → 產品導覽 → 證據 → 結論。選定推薦的點擊路徑以及每個場景必須達到的可見結果。請參閱 references/templates.md。
- 錄製。 複製
scripts/record.mjs，設定APP和SIZE，將scenes替換為你的編排（滑動 → 暫停 → 操作 → 停留）。以 1:1 裝置比例錄製。node scripts/record.mjs [scene]。引擎與實作範例：references/recording.md。 - 旁白 → 字幕。 為每個場景撰寫一個
assets/narration/NN-*.txt檔案，使用口語風格（你是在與觀眾對話，而非朗讀 README — 這與行銷文案不同；行銷技能提供主題/鉤子/故事板，此技能則撰寫口語內容）。然後執行：bash scripts/tts.sh && bash scripts/transcribe.sh && node scripts/build-captions.mjs。 在build-captions.mjs中編輯PHRASE_FIX以修正你的品牌名稱。 語音可透過契約替換：旁白是每個場景一個 wav 檔案（narration/NN-*.wav）— 可將任何 wav 替換為真人錄音、剪映配音或其他 TTS，然後重新執行轉錄+字幕、重新合成；無需更改其他內容。預設使用 Kokoro（本地、Apache-2.0 授權，支援中文語音）；edge-tts 是免費的線上替代方案。指南：references/narration-and-captions.md。 - 合成與渲染。 從 references/composition-skeleton.html 開始（一個片段 + 字幕軌 + 音訊），擴展時間軸，然後執行：
npx hyperframes render . --resolution landscape --fps 30 --crf 17 --quality high。 以 1:1 比例渲染（原始 1080p → 輸出 1080p）— 切勿升頻至 4K，這會使 UI 變得模糊。references/composition.md。 - 出貨前進行品質檢查。 使用 ffprobe 檢查時長/音訊，抽樣 1–2 幀（不是黑畫面、不是空畫面）、字幕在畫面內、旁白未被剪斷、關鍵結果頁面實際可見。修正流程/時間，然後重新渲染。
快速開始
# 系統依賴
brew install node ffmpeg
npx playwright install chromium
# 本地 TTS + 轉錄的 Python 虛擬環境（一次性）
python3 -m venv .ttsvenv && .ttsvenv/bin/pip install kokoro-onnx soundfile
export PATH="$(pwd)/.ttsvenv/bin:$PATH"
# 1) 錄製 2) 旁白 3) 字幕 4) 合成+渲染
node scripts/record.mjs
bash scripts/tts.sh && bash scripts/transcribe.sh && node scripts/build-captions.mjs
npx hyperframes render . --resolution landscape --fps 30 --crf 17 --quality high --output out/demo.mp4
首次 TTS 會下載約 340 MB（Kokoro），首次轉錄約 466 MB（Whisper small.en）；兩者都會快取在 ~/.cache/hyperframes/。
經驗法則
- 真實互動勝於幻燈片 — 錄製產品實際運作的畫面。
- 1:1，絕不 2 倍升頻 — 以 2 倍 DPR 錄製並渲染 4K 會讓每個 UI 片段變模糊。應以 1080p 創作與渲染。
- 確定性合成 — HTML 中不使用
Date.now()、Math.random()或網路請求；HyperFrames 會按幀搜尋，因此動畫必須可重現。 - 可見游標 + 停留展示結果 — 滑動要從容，在關鍵畫面上暫停。
- 口語旁白，非文檔朗讀 — 旁白跟隨畫面；它不是把 README 大聲唸出來。
- 影片時長 ≥ 旁白時長 — 為片段補充足夠時間，確保畫面不會在語音結束前終止。
依賴
Node 22+, FFmpeg, Playwright（Chromium），以及 HyperFrames CLI（npx hyperframes，使用 npx skills add heygen-com/hyperframes 安裝其技能）。本地 TTS/Whisper 需要 Python + kokoro-onnx。各引擎可選：Cap 路線需要 cap（curl -fsSL https://cap.so/install-cli.sh | sh）+ cliclick（brew install cliclick）+ 螢幕錄製權限；終端路線需要 vhs（brew install vhs）。全部免費 — 授權表格請參閱 references/screen-studio-look.md。HyperFrames 設定請參閱 references/composition.md。
參考資料
- references/pipeline.md — 六個階段與資料流程
- references/screen-studio-look.md — 三種錄製引擎；Cap CLI 生命週期、縮放聚類、VHS tapes、不應自行建置的部分
- references/recording.md — Director 引擎 + 實作範例 + 錄製常見陷阱
- references/narration-and-captions.md — 腳本撰寫、TTS、Whisper、字幕修正
- references/composition.md — HyperFrames 時間軸、淡入淡出、1080p、渲染
- references/composition-skeleton.html — 最小可渲染合成範本，可複製為 index.html
- references/templates.md — 駭客松 + 產品示範結構與腳本範本
- references/troubleshooting.md — 字幕、白畫面、音訊、字型問題