渲染、輸出、修正
請在 projects/<name>/ 目錄內執行。最終核准的檔案也會被複製到工作區根目錄的 exports/ 中。
速查表
npx hyperframes render . -o renders/video.mp4 # 預設
npx hyperframes render . --fps 60 -o renders/video-60fps.mp4
npx hyperframes render . --resolution 4k -o renders/video-4k.mp4 # 長寬比需一致；直立 → portrait-4k
npx hyperframes render . --resolution 4k --fps 120 -o renders/video-4k-120.mp4
npx hyperframes render . --fps 24 -o renders/video-24fps.mp4
npx hyperframes render . --format mov -o renders/video.mov # ProRes
npx hyperframes render . --format png-sequence -o renders/frames
npx hyperframes render . --crf 23 -o renders/smaller.mp4 # 較小檔案
- 當圖形疊加在使用者的影片素材上時，請保持素材的原始影格率，除非使用者要求變更。
- 在 4 核心 i3 筆電（約 12 GB RAM）上的參考時間（更快的電腦會更快）：6 秒簡單 1080p 圖形 ≈ 24 秒；3 分 20 秒的 1080x1920 影片 + Paper Cut 效果 ≈ 1.5 小時（~1.1 fps：
filter: drop-shadow會強制截圖渲染，且快速截圖僅在 macOS 上有效）。在長時間渲染前警告使用者，並只在最後階段進行一次渲染。 - 速度調整槓桿：
--workers 3（每個 Chrome 約 256 MB；預設auto在此環境選擇 1 — 請先在短片段上測試）、--quality draft用於預覽渲染，或使用較短的片段。如果渲染時記憶體不足或逾時，請加上--low-memory-mode和/或--protocol-timeout 600000。 - 僅音訊變更無需重新渲染：
node tools/sfx.mjs projects/<n> --mix in.mp4 out.mp4（視訊串流直接複製）。 - 使用
npx hyperframes snapshot（快速）進行迭代，只有在影格看起來正確時才進行渲染。
透明輸出（提示 14）
MOV/PNG 僅在背景透明時才會有透明效果。
- 移除背景及所有影片素材，只保留卡片；周圍區域完全透明。
- 霧面卡片在沒有背景物體時會失去模糊效果 → 針對疊加層改用實心卡片。
- 輸出
renders/card.mov（含 Alpha 的 ProRes 4444，--format mov）以及renders/card-png中的 PNG 序列（--format png-sequence）。 - 在棋盤格背景上拍攝快照，確認只有卡片可見。（
--format webm是另一種透明選項。）
當畫面異常時的處理
| 症狀 | 修正方式 |
|---|---|
| 字型錯誤 / 使用普通後備字型 | 使用 fonts/ 中的檔案並透過 @font-face 載入；絕不使用網頁字型 URL。lint 會標記 font_family_without_font_face。 |
| 文字在手機上被裁切 | 將所有文字保持在寬度中間的 80% 範圍內。 |
| 卡片遮蓋住字幕 | 將所有卡片移至畫面下方三分之一區域之上。 |
| 卡片時間點稍微提前 / 延後 | 語音轉文字可能誤差約 1 秒。請根據實際口語詞語重新調整時間（檢查附近的音訊）。 |
| 檔案過大 | 使用 --crf 23 重新渲染（特別是紋理風格）。 |
| 渲染後無聲音 | 每個 <audio> 都需要 id；<video> 不能設為 muted，且需要 data-has-audio="true"。 |
如果使用者以口語描述問題，請將其對應到上述症狀或 mg-styles 中的設定參數。 |