HyperFrames 中文影片實戰
在 HTML 裡寫影片，引擎逐幀渲染成 MP4。本 skill 是 2026-10 一次完整 6.5 分鐘中文科普影片（含真實數據、配音、截圖）的實戰沉澱，重點是官方文檔沒寫、踩過才知的坑。
全流程（五步）
- 初始化：
npx hyperframes init <dir>→ Node22+、FFmpeg 前置；本機需HYPERFRAMES_BROWSER_PATH=/usr/bin/google-chrome（引擎自動下載 chrome-headless-shell 會因網路失敗，見 pitfalls#1） - 結構與內容：主
index.html串聯場景 sub-comp；內容素材（真實數據/截圖）先歸檔scripts/sources.md再上畫面——資訊密度是解說影片的第一生命 - 動畫：每場景一個 paused GSAP timeline；逐句字幕系統 + 節奏高亮（配方見
references/scene-recipe.md） - 校驗：
npx hyperframes check全綠是渲染前提；修復套路見references/pitfalls.md（90% 的錯誤都在手冊裡有現成解法） - 配音（可選）：edge-tts 生成 → 按實測時長適配語速 → 音頻必須掛主 index 的 root 內（sub-comp 裡不生效，見 pitfalls#6）→ 重渲
- 質檢與交付：渲染後
npx hyperframes snapshot抽關鍵幀逐張看（視覺自檢閉環：渲染→看幀→改進→再渲）；封面圖直接用 snapshot 出，不另開工具
關鍵命令：preview 用 --background（可熱重載）；渲染 365s@1080p 約 9-10 分鐘（5 worker 截圖模式，本機無 GPU）。
何時讀哪個參考
- 任何報錯/渲染異常 → 先查
references/pitfalls.md（按症狀查，含相機 transform 鏈這個未解引擎 bug 的結論） - 寫新場景 →
references/scene-recipe.md（含逐句字幕 JS 模板、標註動畫模式） - 加配音 →
references/voice-pipeline.md - 分析參考影片（抖音等）→ pitfalls.md 末節「參考影片定量拆解」
- 找現成動效塊/同賽道 skill/配音升級/剪映打通等外部工具 →
references/ecosystem.md（開源生態清單，含官方 capture --video 1:1 復刻）
自帶腳本
scripts/inject_subtitles.py—— 逐句字幕批量注入（HTML/CSS/JS 一次到位，防手寫錯）scripts/gen_voice.py—— edge-tts 批量生成 + 自動語速適配場景時長（uv run 執行）scripts/frame_audit.py—— 渲染幀質心審計（畫面偏移/空白自動檢出，排鏡頭問題必備）
三條鐵律
- 改任何場景檔案前先 grep：Studio 會給元素插
data-hf-id，字串替換會靜默失敗（pitfalls#2） - 不碰大畫布相機方案：引擎渲染管線對連續 transform 鏈驅動錯位，已多方案驗證無解（pitfalls#8），動畫只做元素級
- 敘事時間軸先行：字幕句時間 + 配音時長決定一切動畫節奏；先鎖時間軸再做動畫，返工成本最低