coleam00/hyperframes-ai-video-generation

HyperFrames CLI

所有操作皆透過 npx hyperframes 執行。需要 Node.js >= 22 和 FFmpeg。

工作流程

1. Scaffold（搭建） — npx hyperframes init my-video
2. 撰寫 — 編寫 HTML 合成（參閱 hyperframes 技能）
3. Lint（程式碼檢查） — npx hyperframes lint
4. Vision 檢查 — npx hyperframes inspect
5. 預覽 — npx hyperframes preview
6. 渲染 — npx hyperframes render

請在預覽前先執行 lint 和 inspect。lint 會檢查遺漏的 data-composition-id、重疊的軌道以及未註冊的時間軸。inspect 會在無頭 Chrome 中開啟渲染後的合成，掃描時間軸，並報告文字溢出對話框/容器或畫布的情況。

搭建 Scaffold

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 編碼技能。請用它來取代手動建立檔案。

Lint 程式碼檢查

npx hyperframes lint                  # 當前目錄
npx hyperframes lint ./my-project     # 指定專案
npx hyperframes lint --verbose        # 顯示資訊級別的發現
npx hyperframes lint --json           # 機器可讀格式

檢查 index.html 以及 compositions/ 中的所有檔案。報告錯誤（必須修復）、警告（應該修復）以及資訊（使用 --verbose）。

Vision 檢查

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）

檔案變更時會熱重新載入。會自動在瀏覽器中開啟工作室。

渲染

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 "Text here" --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 .    # 基準測試渲染效能