HyperFrames 媒體資產
為組合建立所需的音頻與媒體資產 — 語音旁白(TTS)、背景音樂 + 音效、轉錄、字幕、去背 — 然後在 HTML 中消費並動畫化這些資料。若要將資產放入組合,請參閱 hyperframes-core。
音頻引擎 — TTS · BGM · SFX 的單一來源
工作流程不應手動拼湊音頻或複製供應商套件。只有一個引擎 — scripts/audio.mjs — 它接受中性的 audio_request.json 並寫出 audio_meta.json(以及 assets/voice|bgm|sfx 下的資產):
# <MEDIA_DIR> = 此技能的路徑
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
所有三項能力取決於一個開關 — 是否存在 HeyGen 憑證(從 $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen 解析,非 CLI):
| 能力 | HeyGen 憑證存在 | 憑證不存在 |
|---|---|---|
| TTS | HeyGen Starfish REST(原生逐字時間戳) | → ElevenLabs → Kokoro(鏈式 transcribe 取得逐字時間) |
| BGM | HeyGen 音樂檢索 | Lyria → MusicGen 本地生成(分離執行) |
| SFX | HeyGen 音效檢索(min_score 0.4) | 內建 21 個檔案音效庫(assets/sfx/) |
- 請求(
audio_request.json):{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }。id將每一行連接回呼叫端的模型(影格編號、場景 ID 等)。bgm.mode=retrieve | generate | none;省略時自動(有憑證時檢索,否則生成)。明確指定retrieve是嚴格的 — 它會跳過而非啟動分離的生成(適用於沒有wait-bgm步驟的呼叫端)。 - 輸出(
audio_meta.json,以 id 為鍵):{ tts_provider, voice_id, bgm, bgm_pending, …, voices: [{ id, path, duration_s, words }], sfx: [{ id, name, file, source, offset_s, duration_s, volume }], total_duration_s }。 --only tts,bgm,sfx執行子集並合併到現有的--out(例如,先 TTS+BGM,等音效提示存在後再加 SFX)。- BGM 生成以分離方式啟動(
bgm_pending: true)— 在組裝前運行scripts/wait-bgm.mjs。 scripts/heygen-tts.mjs是相同程式碼的單次 CLI(一個文字 → wav + 逐字時間),適合只需 HeyGen TTS 而無需請求檔案的場景。
完整標誌列表 + audio_meta.json 結構位於 scripts/audio.mjs 的標頭註解中。以下參考資料涵蓋各項能力背後的提供者細節與邊界情況。
預檢 — 在任何音頻之前顯示登入狀態
在生成語音或 BGM 之前務必執行此步驟 — 無論是在完整工作流程還是單次「幫我生成 BGM/語音旁白」請求中。 沒有 HeyGen 憑證不是默默降級到本地引擎的理由:首先建議登入,讓使用者決定。執行共享的預檢並逐字傳達其輸出 — 不要自行編寫「遺失金鑰」提示,也不要把金鑰寫入每個儲存庫的 .env:
npx hyperframes auth status
- 已登入 → 它會顯示帳戶資訊;繼續。
- 未登入(此處預期
exit 1—「未登入」是正常狀態,不是失敗)→ 它會顯示註冊優先指引。建議登入:npx hyperframes auth login是瀏覽器 OAuth — 它會登入並建立帳戶(始終可透過此儲存庫的 CLI 使用)。若要使用現有的 HeyGen API 金鑰(來自 app.heygen.com/settings/api),請執行npx hyperframes auth login --api-key— 它會儲存到共享的~/.heygen(無需每個儲存庫的.env)。輸出還會列出語音/BGM 將降級到的本地引擎,以及在缺少依賴時的pip提示。逐字傳達此輸出 — 不要用自己的措辭重新解釋。 然後停止並等待使用者選擇 — 登入,或說「go」/「local」以繼續離線運作 — 在生成任何內容之前。 這是一個真正的決策點,不是過場備註:不要把它併入其他問題,也不要自行跳過它。(例外:在自主/非互動模式下,記錄狀態並繼續離線運作。) npx hyperframes auth status --json會回傳{ configured, recommended_action, offline_engines },供確定性分支使用。- 如果 CLI 無法執行(不在 PATH 上且
npx無法擷取)→ 仍然建議登入(npx hyperframes auth login)並停下來等待使用者選擇 — 不要把「沒有憑證」當作本地生成的默認綠燈。
憑證解析、完整金鑰優先順序以及本地依賴列表位於 references/requirements.md。
提供者鏈(引擎背後的細節)
TTS — 第一個可用的提供者勝出(引擎,或 npx hyperframes tts "..."):
| 順序 | 提供者 | 檢測時機 | 逐字時間戳 |
|---|---|---|---|
| 1 | HeyGen(Starfish) | $HEYGEN_API_KEY / hyperframes auth login | 有,原生 — 傳入 --words narration.words.json 以擷取 |
| 2 | ElevenLabs | 設定 $ELEVENLABS_API_KEY | 無 — 之後鏈式 transcribe |
| 3 | Kokoro-82M(本地,54 種語音) | 始終可用(無需金鑰) | 無 — 之後鏈式 transcribe |
已發布的
hyperframes ttsCLI 通常是僅限本地版本的建置(其--help顯示「Kokoro-82M」,沒有--provider/--words),即使設定了$HEYGEN_API_KEY也會默默降級到 Kokoro。這就是為什麼引擎的 HeyGen 路徑是獨立的scripts/heygen-tts.mjs(REST),而不是 CLI;CLI 僅用於 Kokoro 路徑。請參閱references/tts.md。
BGM & SFX — 預設從 HeyGen 音頻庫(/v3/audio/sounds)檢索,使用與 HeyGen TTS 相同的憑證,並使用上方開關的無憑證降級方案:
| 資產 | HeyGen type | 存放位置 | 降級(無憑證) |
|---|---|---|---|
| BGM | music | assets/bgm/track.mp3(檢索) · track.wav(生成) | Lyria / MusicGen 生成 |
| SFX | sound_effects(min_score 0.4) | assets/sfx/<slug>.mp3 | 內建 21 個檔案音效庫(assets/sfx/* + manifest.json) |
請參閱 references/bgm.md 和 references/sfx.md。
路由
| 任務 | 閱讀 |
|---|---|
音頻引擎 — 請求/中繼資料結構、--only、開關 | scripts/audio.mjs(標頭註解) |
npx hyperframes tts / heygen-tts.mjs — 提供者、語音、逐字時間 | references/tts.md |
| BGM — HeyGen 檢索 + 本地 Lyria / MusicGen 生成 | references/bgm.md |
SFX — HeyGen 檢索(min_score 0.4)+ 內建本地音效庫 | references/sfx.md |
npx hyperframes transcribe — Whisper、模型規則、輸出格式 | references/transcribe.md |
npx hyperframes remove-background — 透明去背 | references/remove-background.md |
| TTS → 轉錄 → 字幕(無錄製語音旁白) | references/tts-to-captions.md |
| 字幕編寫 — 樣式偵測、佈局、單字分組、退出 | references/captions/authoring.md |
| 轉錄稿處理 — 輸入格式、品質門檻、清理、API | references/captions/transcript-handling.md |
| 字幕動態 — 卡拉 OK、標記效果、音頻反應式 | references/captions/motion.md |
| 模型快取、系統依賴、疑難排解 | references/requirements.md |
不可協商的規則
- 單一引擎,不得複製供應商套件。 透過
scripts/audio.mjs(或單次 HeyGen TTS 使用heygen-tts.mjs)產生音頻。請勿在工作流程中重新實作 TTS/BGM/SFX — 請撰寫audio_request.json適配器並呼叫引擎。 - 「HeyGen 可用」= 可解析的憑證,而非 CLI。 整個開關依賴
heygenCredential();已發布的hyperframes tts可能僅支援 Kokoro,而且根本沒有hyperframes bgm/hyperframes sfx指令。 - 語音 ID 是提供者專用的。
am_michael僅限 Kokoro;HeyGen UUID 在 Kokoro 上無效。如果你傳入--voice,也請固定--provider,以避免使用者環境變更時提供者默默漂移。 - 務必傳入
--model給transcribe。 CLI 預設的small.en會默默翻譯非英文音頻。請參閱references/transcribe.md→「語言規則」。 - HeyGen 會回傳逐字時間戳;ElevenLabs / Kokoro 不會。 引擎會為後兩者自動鏈式
transcribe;單獨使用時,請為 HeyGen 傳入--words,或對音頻檔案執行transcribe。 - 字幕使用扁平單字陣列格式,包含
{ id, text, start, end }。請參閱references/transcribe.md→「輸出格式」。 remove-background --background-output是挖洞,而非修補。 對於「沒有人的場景」,需要使用不同的工具。請參閱references/remove-background.md→「何時不是正確工具」。- BGM/SFX 預設使用 HeyGen 檢索;無憑證降級為生成(BGM)或內建音效庫(SFX)。
/audio/sounds根據文字查詢排序 — 具體命名音效(如glass shatter,而非dramatic sound);無匹配則跳過,絕不阻擋渲染。SFX 在語音 + BGM 下的音量約為 0.35。請參閱references/sfx.md/references/bgm.md。 - 將工作流程字幕 HTML 視為產生的輸出。 對於預設背景的影片,可重複使用的皮膚原始碼位於
.hyperframes/caption-skin.html,工作流程腳本會寫入compositions/captions.html;請勿編輯產生的compositions/captions.html來修正皮膚。請透過工作流程的captions.mjs重建,或使用該工作流程的明確覆寫機制(如果存在的話)。