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 憑證並非要默默地回退到本地引擎:首先建議登入,讓使用者決定。執行共用的預檢指令,並直接轉述其輸出——不要自行編造「缺少 key」的提示,也不要提議將 key 寫入每個儲存庫的 .env:
npx hyperframes auth status
- 已登入 → 它會列印帳戶資訊;繼續進行。
- 未登入 (
exit 1在此是預期行為——「未登入」是正常狀態,並非失敗) → 它會列印引導註冊的資訊。建議登入:npx hyperframes auth login是瀏覽器 OAuth——它會登入並建立帳戶(透過此儲存庫的 CLI 始終可用)。若要使用現有的 HeyGen API key(來自 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;若獨立使用,請傳遞--words給 HeyGen,或對音訊檔案執行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);無匹配則跳過,絕不阻擋渲染。在語音 + BGM 下,SFX 的音量約為 ~0.35。請參閱references/sfx.md/references/bgm.md。 - 將工作流程的字幕 HTML 視為生成的輸出。 對於預設支援的影片,可重複使用的皮膚原始碼位於
.hyperframes/caption-skin.html,工作流程腳本則寫入compositions/captions.html;請勿編輯生成的compositions/captions.html來修復皮膚。請透過工作流程的captions.mjs重新建置,或在存在時使用該工作流程的明確覆寫機制。