itgoyo/hermes-skills

HyperFrames CLI

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

工作流程

1. 建立專案 — npx hyperframes init my-video
2. 編寫 — 撰寫 HTML 合成腳本（請參閱 hyperframes 技能）
3. 檢查 — npx hyperframes lint
4. 預覽 — npx hyperframes preview
5. 渲染 — npx hyperframes render

請在預覽前先執行檢查 — 它會捕捉遺失的 data-composition-id、重疊的軌道以及未註冊的時間軸。

建立專案

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）

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

渲染

npx hyperframes render                                # 標準 MP4（自動輸出到 renders/ 目錄）
創
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	旗標	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、記憶體不足。

常見陷阱

--out 路徑必須是目錄，而不是檔案名稱

npx hyperframes render --out renders/output.mp4 → ✗ 錯誤：「不是一個目錄」 npx hyperframes render → ✅ 自動輸出到 renders/名稱_時間戳.mp4 請使用 --output（而非 --out）來指定檔案路徑。

index.html 的根時間軸必須與子合成的 data-composition-id 相符

如果 index.html 只包含一個 data-composition-src 參考（沒有內聯內容），您仍然需要一個 window.__timelines 註冊，且該註冊必須與一個真實的 data-composition-id 相符。最佳做法：註冊 window.__timelines['<子合成ID>'] = gsap.timeline({paused:true}) — 但由於子合成會註冊自己的時間軸，因此 index.html 的腳本區塊僅用於通過 lint 檢查。請使用子合成的 ID（而非 'root'）。

子合成的 <div> 需要 data-start="0" 和 data-duration

<template> 內部的 <div data-composition-id="..."> 必須具有 data-start="0" 和 data-duration="N"，否則 lint 會發出警告，且播放可能無法啟動。

其他

npx hyperframes compositions   # 列出專案中的合成
npx hyperframes docs           # 開啟文件
npx hyperframes benchmark .    # 執行渲染效能基準測試