HyperFrames CLI 是做什麼的？
一切都透過 npx hyperframes 運行。需要 Node.js >= 22 和 FFmpeg。
工作流程
- 初始化 —
npx hyperframes init my-video - 編寫 — 編輯 HTML 合成（參見
hyperframes技能） - Lint 檢查 —
npx hyperframes lint - 視覺檢測 —
npx hyperframes inspect - 預覽 —
npx hyperframes preview - 渲染 —
npx hyperframes render
在預覽前先進行 lint 檢查和視覺檢測。lint 會捕捉缺少的 data-composition-id、重疊的軌道以及未註冊的時間軸。inspect 在 headless Chrome 中開啟渲染的合成，掃描時間軸，並回報文字溢出氣泡/容器或超出畫布的問題。
初始化
npx hyperframes init my-video # 互動式向導
npx hyperframes init my-video --example warm-grain # 選擇範例
npx hyperframes init my-video --video clip.mp4 # 帶影片檔案
npx hyperframes init my-video --audio track.mp3 # 帶音訊檔案
npx hyperframes init my-video --example blank --tailwind # 使用 Tailwind v4 瀏覽器執行環境
npx hyperframes init my-video --non-interactive # 跳過提示（CI/代理）
範本：blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。
init 會建立正確的檔案結構、複製媒體、使用 Whisper 轉錄音訊，並安裝 AI 編碼技能。請使用它來代替手動建立檔案。
使用 --tailwind 時，請在編輯類別或主題令牌之前呼叫 tailwind 技能。該架構使用 Tailwind v4.2 瀏覽器執行環境，而非 Studio 的 Tailwind v3 設定。
Lint 檢查
npx hyperframes lint # 當前目錄
npx hyperframes lint ./my-project # 指定專案
npx hyperframes lint --verbose # 資訊級別發現
npx hyperframes lint --json # 機器可讀
檢查 index.html 和 compositions/ 中的所有檔案。報告錯誤（必須修復）、警告（應修復）和資訊（使用 --verbose）。
視覺檢測
npx hyperframes inspect # 檢查時間軸上的渲染佈局
npx hyperframes inspect ./my-project # 指定專案
npx hyperframes inspect --json # 代理可讀的發現
npx hyperframes inspect --samples 15 # 更密集的時間軸掃描
npx hyperframes inspect --at 1.5,4,7.25 # 明確的關鍵幀時間戳
在 lint 和 validate 之後使用此功能，特別是對於包含對話氣泡、卡片、標題或緊湊排版的合成。它會報告：
- 文字延伸到最近視覺容器或氣泡之外
- 文字被自身的固定寬度/固定高度盒子裁剪
- 文字延伸到合成畫布之外
- 子元素逃離裁剪容器
在渲染前應修復錯誤。警告會呈現給代理審閱；添加 --strict 以在警告時也失敗。重複的靜態問題預設會摺疊，以便 JSON 輸出在 LLM 上下文視窗中保持緊湊。如果溢出是入口/出口動畫的有意設計，請在元素或其祖先上標記 data-layout-allow-overflow。如果裝飾性元素不應被審計，請標記 data-layout-ignore。
npx hyperframes layout 仍作為相容別名可用於執行相同的視覺檢測流程。
預覽
npx hyperframes preview # 服務當前目錄
npx hyperframes preview --port 4567 # 自訂連接埠（預設 3002）
檔案變更時自動重新載入。自動在瀏覽器中開啟工作室。
將專案交回給使用者時，請使用工作室專案 URL，而不是來源 index.html 路徑：
http://localhost:<port>/#project/<project-name>
使用預覽輸出中的實際連接埠和專案目錄名稱。例如，在 codex-openai-video 中執行 npx hyperframes preview --port 3017 後，報告 http://localhost:3017/#project/codex-openai-video。
將 index.html 僅視為原始碼上下文。將其連結為實作檔案是可以的，但不要將其標記為專案或預覽表面。
渲染
npx hyperframes render # 標準 MP4
npx hyperframes render --output final.mp4 # 命名輸出
npx hyperframes render --quality draft # 快速疊代
npx hyperframes render --fps 60 --quality high # 最終交付
npx hyperframes render --format webm # 透明 WebM
npx hyperframes render --docker # 位元組一致
| 旗標 | 選項 | 預設值 | 備註 |
|---|---|---|---|
--output | 路徑 | renders/name_timestamp.mp4 | 輸出路徑 |
--fps | 24, 30, 60 | 30 | 60fps 使渲染時間加倍 |
--quality | draft, standard, high | standard | draft 用於疊代 |
--format | mp4, webm | mp4 | WebM 支援透明度 |
--workers | 1-8 或 auto | auto | 每個會啟動 Chrome |
--docker | 旗標 | 關閉 | 可重現輸出 |
--gpu | 旗標 | 關閉 | GPU 加速編碼 |
--strict | 旗標 | 關閉 | 在 lint 錯誤時失敗 |
--strict-all | 旗標 | 關閉 | 在錯誤和警告時失敗 |
--variables | JSON 物件 | — | 覆蓋 data-composition-variables 中宣告的變數值 |
--variables-file | 路徑 | — | 包含變數值的 JSON 檔案（--variables 的替代方案） |
--strict-variables | 旗標 | 關閉 | 在 --variables 中出現未宣告的鍵或類型不匹配時渲染失敗 |
品質指南： 疊代時使用 draft，審閱時使用 standard，最終交付時使用 high。
參數化渲染： 合成在其 <html> 根元素上使用 data-composition-variables 宣告變數——這是一個 JSON 宣告陣列（每個條目包含 {id, type, label, default}），定義了結構描述。內部的腳本透過 window.__hyperframes.getVariables() 讀取解析後的值。CLI 的 --variables '{"title":"Q4 Report"}' 是一個按 id 鍵索引的 JSON 物件，會覆蓋一次渲染中宣告的預設值；缺失的鍵會回退，因此同一個合成在開發預覽和生產環境中都能不變地運行。（子合成主機也可以使用 data-variable-values 覆蓋每個實例的值——相同的物件結構，作用域僅限於子合成的一次掛載。請參見 hyperframes 技能以了解完整模式。）
資產預處理
npx hyperframes tts、transcribe 和 remove-background 會生成資產（旁白音訊、逐字轉錄、透明影片），這些資產會被放入合成中。每個命令在首次運行時會下載自己的模型。關於語音選擇、whisper 模型規則（.en 會翻譯非英文的陷阱）、輸出格式選擇（VP9 alpha WebM 與 ProRes）以及 TTS → 轉錄 → 字幕鏈，請調用 hyperframes-media 技能。
故障排除
npx hyperframes doctor # 檢查環境（Chrome、FFmpeg、Node、記憶體）
npx hyperframes browser # 管理捆綁的 Chrome
npx hyperframes info # 版本和環境詳細資訊
npx hyperframes upgrade # 檢查更新
如果渲染失敗，請先執行 doctor。常見問題：缺少 FFmpeg、缺少 Chrome、記憶體不足。
其他
npx hyperframes compositions # 列出專案中的合成
npx hyperframes docs # 開啟文件
npx hyperframes benchmark . # 基準測試渲染效能