HyperFrames CLI
所有操作均透過 npx hyperframes 執行。需要 Node.js >= 22 和 FFmpeg。
工作流程
- 建立專案 —
npx hyperframes init my-video - 撰寫 — 編輯 HTML Composition(請參閱
hyperframes技能) - 語法檢查 —
npx hyperframes lint(靜態檢查) - 驗證 —
npx hyperframes validate(瀏覽器內執行階段檢查 + 對比度稽核) - 預覽 —
npx hyperframes preview - 渲染 —
npx hyperframes render
Lint 可捕捉靜態問題(缺少 data-composition-id、重疊軌道、未註冊時間軸)。Validate 則能透過在實際瀏覽器中暫停 Composition 並檢查畫面,來捕捉執行階段/視覺問題(對比度、異常覆蓋層、遺失素材)。渲染前請務必執行兩者。
驗證
npx hyperframes validate # 完整驗證(靜態 + 對比度 + 合約)
npx hyperframes validate --no-contrast # 快速迭代時跳過 WCAG 對比度稽核
npx hyperframes validate --json # 機器可讀輸出
驗證會在暫停的 Composition 中跳到數個時間點,對頁面進行螢幕截圖,取樣每個文字元素背後的像素以計算 WCAG 對比度,並驗證執行階段合約(window.__timelines 註冊、class="clip" 存在性、有效的 data-* 屬性)。請在每次渲染前執行——它成本低廉,且能捕捉 Lint 無法發現的問題。
建立專案
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 --non-interactive # 跳過提示(CI/代理程式使用)
範本:blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。
init 會建立正確的檔案結構、複製媒體檔案、使用 Whisper 轉錄音訊,並安裝 AI 編碼技能。請使用此指令取代手動建立檔案。
語法檢查
npx hyperframes lint # 檢查目前目錄
npx hyperframes lint ./my-project # 檢查特定專案
npx hyperframes lint --verbose # 顯示資訊層級結果
npx hyperframes lint --json # 機器可讀輸出
檢查 index.html 及 compositions/ 目錄下的所有檔案。回報錯誤(必須修正)、警告(建議修正)以及資訊(使用 --verbose)。
預覽
npx hyperframes preview # 提供目前目錄服務
npx hyperframes preview --port 4567 # 自訂連接埠(預設 3002)
檔案變更時自動重新載入。自動在瀏覽器中開啟 Studio。
渲染
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 | 每個 worker 會啟動一個 Chrome |
--docker | 旗標 | off | 可重複的輸出 |
--gpu | 旗標 | off | GPU 加速編碼 |
--strict | 旗標 | off | 遇 Lint 錯誤則失敗 |
--strict-all | 旗標 | off | 遇錯誤和警告均失敗 |
品質建議: 迭代時使用 draft,審查時使用 standard,最終交付使用 high。
轉錄
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
npx hyperframes transcribe subtitles.srt # 匯入現有字幕
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
文字轉語音
npx hyperframes tts "文字內容" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list # 顯示所有語音
疑難排解
npx hyperframes doctor # 檢查環境(Chrome、FFmpeg、Node、記憶體)
npx hyperframes browser # 管理內建 Chrome
npx hyperframes info # 版本與環境詳細資訊
npx hyperframes upgrade # 檢查更新
如果渲染失敗,請先執行 doctor。常見問題:缺少 FFmpeg、缺少 Chrome、記憶體不足。
其他
npx hyperframes compositions # 列出專案中的 Composition
npx hyperframes docs # 開啟文件
npx hyperframes benchmark . # 基準測試渲染效能