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 的檔案頭註解中。以下參考資料涵蓋每個功能背後的供應商細節與邊界情況。
預檢——在任何音訊作業前顯示登入狀態
在生成語音或 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提示。逐字轉達此輸出，不要用自己的話改寫。 然後停止並等待使用者選擇——登入，或說「繼續」/「本地」以離線繼續——在生成任何內容之前。 這是一個真實的決策點，不是一個附帶說明：不要將其併入另一個問題，也不要自行跳過。（例外：在自動/非互動模式下，記錄狀態並以離線方式繼續。） 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.mjs用於一次性 HeyGen TTS）產生音訊。不要在工作流程中重新實作 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根據文字查詢排序——請具體命名效果（玻璃碎裂，而非戲劇性音效）；無匹配時跳過，絕不阻擋渲染。SFX 在語音 + BGM 下音量約為 0.35。請參閱references/sfx.md/references/bgm.md。 - 將工作流程的字幕 HTML 視為產生的輸出。 對於基於預設模板的影片，可重複使用的皮膚原始碼位於
.hyperframes/caption-skin.html，工作流程腳本則寫入compositions/captions.html；請勿編輯產生的compositions/captions.html來修正皮膚。請透過工作流程的captions.mjs重建，或在工作流程中存在明確覆寫機制時使用該機制。