HyperFrames CLI
所有操作皆透過 npx hyperframes 執行。需要 Node.js >= 22 和 FFmpeg。
工作流程
- 建立專案 —
npx hyperframes init my-video - 撰寫 — 編輯 HTML 合成畫面(參閱
hyperframes技能) - 程式碼檢查 —
npx hyperframes lint - 視覺檢查 —
npx hyperframes inspect - 預覽 —
npx hyperframes preview - 渲染 —
npx hyperframes render
在預覽前請先執行 lint 和 inspect。lint 可找出缺少 data-composition-id、軌道重疊以及未註冊的時間軸。inspect 會在無頭 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 --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 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/名稱_時間戳.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 | 旗標 | 關閉 | 可重現的輸出 |
--gpu | 旗標 | 關閉 | GPU 加速編碼 |
--strict | 旗標 | 關閉 | 在 lint 錯誤時失敗 |
--strict-all | 旗標 | 關閉 | 在錯誤和警告時都失敗 |
品質指引: 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 # 列出專案中的合成畫面
npx hyperframes docs # 開啟文件
npx hyperframes benchmark . # 基準測試渲染效能