HyperFrames CLI
所有操作都透過 npx hyperframes 執行。需要 Node.js >= 22 與 FFmpeg。
工作流程
- Scaffold —
npx hyperframes init my-video - 撰寫 — 編寫 HTML 組合(參見
hyperframes技能) - Lint(程式碼檢查) —
npx hyperframes lint - 執行時期驗證 —
npx hyperframes validate - 視覺檢查 —
npx hyperframes inspect - 預覽 —
npx hyperframes preview - 渲染 —
npx hyperframes render
請在預覽前先執行 Lint 與 Inspect。lint 會捕捉缺少 data-composition-id、重疊軌道及未註冊時間軸的情況。inspect 會在無頭 Chrome 中打開渲染組合,掃描時間軸,並報告從氣泡/容器或畫布溢出的文字。
Scaffolding
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 時,請注意 scaffold 使用 Tailwind v4.2 的瀏覽器執行環境,而非 Studio 的 Tailwind v3 設定 — 在編輯前請根據 v4 文件檢查 class 與主題 token 語法。
Linting
npx hyperframes lint # 目前目錄
npx hyperframes lint ./my-project # 特定專案
npx hyperframes lint --verbose # 資訊層級的發現
npx hyperframes lint --json # 機器可讀
檢查 index.html 及 compositions/ 中的所有檔案。回報錯誤(必須修正)、警告(建議修正)以及資訊(使用 --verbose 時)。
執行時期驗證
npx hyperframes validate # 目前目錄
npx hyperframes validate ./my-project # 特定專案
npx hyperframes validate --json # 機器可讀
npx hyperframes validate --timeout 5000 # 腳本/媒體較慢時(預設 3000 毫秒)
在無頭 Chrome 中載入組合,並回報 JS 控制台錯誤、資源缺失及 WCAG 對比度問題(--no-contrast 可跳過對比度檢查)。請在 lint 之後、inspect 之前執行。
validate 在上游已棄用,改為 npx hyperframes check,它會在一個瀏覽器工作階段中執行 lint、執行時期、版面、動畫及對比度驗證 — 兩者任一種皆可滿足「lint 與 validate」檢查項目的需求。
視覺檢查
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)
檔案變更時會熱重載。會自動在瀏覽器中開啟 Studio。
當將專案交還給使用者時,請使用 Studio 專案 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 | 旗標 | off | 可重現的輸出 |
--gpu | 旗標 | off | GPU 加速編碼 |
--strict | 旗標 | off | 在 lint 錯誤時失敗 |
--strict-all | 旗標 | off | 在錯誤和警告時都失敗 |
--variables | JSON 物件 | — | 覆蓋在 data-composition-variables 中宣告的變數值 |
--variables-file | 路徑 | — | 包含變數值的 JSON 檔案(--variables 的替代方案) |
--strict-variables | 旗標 | off | 在 --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 . # 基準測試渲染效能