Communitygithub.com

HyperFrames CLI

HyperFrames 命令列工具 — 包含 hyperframes init、lint、inspect、preview、render、transcribe、tts、doctor、browser、info、upgrade、compositions、docs、benchmark。用於建立專案、程式碼檢查、驗證、視覺佈局檢查、在工作室中預覽、渲染影片、轉錄音訊、生成 TTS 或排除 HyperFrames 環境問題。

HyperFrames CLI 是什麼?

HyperFrames CLI 是一個功能豐富的命令列工具,專為 HyperFrames 影片製作流程設計。它提供從初始 scaffolding、撰寫 HTML composition、程式碼檢查 (lint)、視覺檢查 (inspect)、預覽 (preview) 到渲染 (render) 的一站式工作流程。支援 lint 檢查遺漏的 data-composition-id、重疊軌道及未註冊時間軸;視覺檢查則透過無頭 Chrome 逐幀掃描,報告文字溢出容器或畫布的問題。此外,還包含音訊轉錄、文字轉語音 (TTS)、環境診斷 (doctor)、瀏覽器管理、專案資訊查詢及升級檢查等輔助功能。此工具支援 Node.js >= 22 和 FFmpeg,可與 Cursor、Codex 等 AI 代理整合,自動化影片製作與問題排除。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/rbrown101010/codex-marketing-skills/tree/HEAD/plugin-workflows/hyperframes-cli

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

HyperFrames CLI 是做什麼的?

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

工作流程

  1. 建立專案骨架 — npx hyperframes init my-video
  2. 撰寫 — 編寫 HTML composition(請參閱 hyperframes 技能)
  3. 程式碼檢查 — npx hyperframes lint
  4. 視覺檢查 — npx hyperframes inspect
  5. 預覽 — npx hyperframes preview
  6. 渲染 — npx hyperframes render

請在預覽前先執行 lint 與 inspect。lint 會檢查遺漏的 data-composition-id、重疊的軌道以及未註冊的時間軸。inspect 會在無頭 Chrome 中打開渲染後的 composition,在時間軸上搜尋,並回報文字溢出泡泡/容器或畫布外的情況。

建立專案骨架

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 之後使用此指令,特別針對含有對話泡泡、卡片、字幕或緊湊排版的 composition。它會回報:

  • 文字超出最近視覺容器或泡泡外
  • 文字被自身固定寬/高的框線裁剪
  • 文字超出 composition 畫布
  • 子元素逃離裁剪容器

錯誤應在渲染前修正。警告會留給代理審查;加上 --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輸出路徑
--fps24、30、603060fps 會使渲染時間加倍
--qualitydraft、standard、highstandarddraft 用於迭代
--formatmp4、webmmp4WebM 支援透明背景
--workers1-8 或 autoauto每個 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   # 列出專案中的 composition
npx hyperframes docs           # 開啟文件
npx hyperframes benchmark .    # 測試渲染效能

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

相關技能