HyperFrames Media
建立作品所需的音訊與媒體資產 — 語音旁白 (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 的標頭註解中。以下參考資料涵蓋每個功能背後的供應商詳細資訊與邊緣情況。
供應商鏈(引擎背後的細節)
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 |
| 越南語 TTS 腳本 — 標點符號、語音學(TTS 層) | references/tts-vi.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);無匹配則跳過,絕不阻塞渲染。SFX 在語音 + BGM 下的音量約為 0.35。請參閱references/sfx.md/references/bgm.md。