Demo Video Studio 是做什麼的？

將一個正在運行的網頁應用程式，變成一部精美的示範影片：真實的互動錄製（非幻燈片、非模擬）+ 本地 TTS 旁白 + 逐字同步字幕 + 輕柔的背景音樂，並以確定性方式透過 HyperFrames 組合而成。

何時使用

任何需要為網頁應用程式製作示範、流程導覽、產品介紹、發表或黑客松影片的場合，尤其是當你需要展示真實產品正在運作並附帶旁白和字幕時。可錄製已部署的 URL 或本地開發伺服器。

管道

① 錄製     Playwright 驅動你的即時應用程式，顯示可見游標 → out/clips/*.webm
② 旁白     為每個場景撰寫旁白稿 → Kokoro TTS (本地)         → narration/*.wav
③ 轉錄     Whisper 逐字時間戳記                           → *.transcript.json
④ 字幕     分組為短語 + 修正品牌誤聽                      → captions.js
⑤ 音樂     ffmpeg 環境背景音樂（在語音下低音量混合）      → music/bed.wav
⑥ 組合     HyperFrames HTML 單一時間軸：影片+語音+字幕+音樂 → MP4

錄製與組合彼此獨立：可僅重新錄製一個場景，或僅重新執行旁白，無需重做另一項。程式生成的 GIF 軌道（HTML 場景直接渲染為 MP4，無需錄製）是可選的輔助路徑，適用於文件頁面。

工作流程

先了解產品。 閱讀其 README / 示範文件。在接觸工具之前先撰寫示範流程：問題 → 產品導覽 → 證據 → 結論。選擇建議的點擊路徑以及每個場景必須達到的可見結果。請參閱 references/templates.md。
錄製。 複製 scripts/record.mjs，設定 APP 和 SIZE，將 scenes 替換為你的編排（滑入 → 暫停 → 動作 → 停留）。以 1:1 裝置比例錄製。node scripts/record.mjs [scene]。引擎及實際範例：references/recording.md。
旁白 → 字幕。 為每個場景以 VO 旁白風格（你是在對觀眾說話，而不是朗讀 README）撰寫一份 assets/narration/NN-*.txt。然後執行： bash scripts/tts.sh && bash scripts/transcribe.sh && node scripts/build-captions.mjs。在 build-captions.mjs 中編輯 PHRASE_FIX 以修正你的品牌名稱。指南：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

# Python 虛擬環境，用於本地 TTS + 轉錄（一次性）
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 會跳轉幀，因此動作必須可重現。
顯示可見游標 + 在結果上停留 — 從容滑動，在關鍵畫面上暫停。
VO 旁白，不是文件 — 旁白跟隨畫面；它不是在朗讀 README。
影片長度 ≥ 旁白長度 — 為片段增加緩衝時間，確保視覺畫面不會在語音結束前結束。

相依性

Node 22+、FFmpeg、Playwright (Chromium)，以及 HyperFrames CLI（npx hyperframes，使用 npx skills add heygen-com/hyperframes 安裝其技能）。本地 TTS/Whisper 需要 Python + kokoro-onnx。HyperFrames 設定請參閱 references/composition.md。

參考資料

references/pipeline.md — 六個階段及資料流
references/recording.md — Director 引擎 + 實際範例 + 錄製陷阱
references/narration-and-captions.md — VO 旁白撰寫、TTS、Whisper、字幕修正
references/composition.md — HyperFrames 時間軸、淡入淡出、1080p、渲染
references/composition-skeleton.html — 最小可渲染的組合，可複製作為 index.html
references/templates.md — 黑客松 + 產品示範的結構和 VO 骨架
references/troubleshooting.md — 字幕、白畫面、音訊、字型

Demo Video Studio