Communitygithub.com

johnnyjclin/video-producer

HyperFrames CLI 工具 — hyperframes init, lint, validate, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark。適用於建立專案、語法檢查與驗證 Composition、在 Studio 中預覽、渲染影片、轉錄音訊、生成 TTS 或疑難排解 HyperFrames 環境。

video-producer 是什麼?

HyperFrames CLI 是一個整合性的指令列工具,專為 HyperFrames 影片製作框架設計。它提供從專案初始化、撰寫與驗證 HTML Composition、到最終渲染成 MP4 或 WebM 影片的完整工作流程。支援 lint 靜態檢查與 validate 瀏覽器內執行階段檢查(含 WCAG 對比度稽核),確保渲染前品質。此外,還包含音訊轉錄(Whisper)、文字轉語音(TTS)、環境診斷(doctor)及效能基準測試等功能。此技能適用於 Claude Code、Cursor、Codex 等 AI 代理平台,可讓代理程式透過 npx 指令自動化完成影片製作中的各項任務。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/johnnyjclin/video-producer/tree/HEAD/.claude/skills/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 validate(瀏覽器內執行階段檢查 + 對比度稽核)
  5. 預覽 — npx hyperframes preview
  6. 渲染 — 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輸出路徑
--fps24, 30, 603060fps 會使渲染時間加倍
--qualitydraft, standard, highstandard迭代時使用 draft
--formatmp4, webmmp4WebM 支援透明背景
--workers1-8 或 autoauto每個 worker 會啟動一個 Chrome
--docker旗標off可重複的輸出
--gpu旗標offGPU 加速編碼
--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 .    # 基準測試渲染效能

相關技能