Communitygithub.com

whyiloveher2411/_biong_backend_FE

HyperFrames 媒體資產 — 音訊與媒體資產,由單一的音訊引擎 (scripts/audio.mjs) 驅動,支援多供應商 TTS(HeyGen / ElevenLabs / Kokoro 本地)、背景音樂 + 音效(預設 HeyGen 音訊庫檢索,搭配本地 Lyria / MusicGen BGM 生成與內建 SFX 庫作為無憑證後備)、Whisper 轉錄、去背與字幕製作。適用於配音 / TTS、BGM、SFX / 音效、轉錄、字幕 / 歌詞 / 卡拉 OK / 逐字樣式、語音 + 供應商選擇及音樂情緒提示。

_biong_backend_FE 是什麼?

此技能為 HyperFrames 作品提供完整的音訊與媒體資產建立管道,核心是單一音訊引擎 (`scripts/audio.mjs`),它能接受中立的 `audio_request.json` 並產出 `audio_meta.json` 與資產檔案。支援多供應商文字轉語音(TTS),依序嘗試 HeyGen(原生逐字時間戳)、ElevenLabs(需後續轉錄取得時間戳)、或無需金鑰的本地 Kokoro-82M。背景音樂(BGM)與音效(SFX)預設從 HeyGen 音訊庫檢索,若無憑證則自動降級為本地 Lyria / MusicGen 生成 BGM,或使用內建的 21 個 SFX 音檔庫。此外還包含 Whisper 轉錄、去背、與複雜的字幕編寫功能(支援卡拉 OK 逐字動畫)。對於需要快速整合語音、音樂與字幕的開發者來說,這是最佳選擇,因為所有媒體操作都集中在一個引擎,避免了重複實作。支援 Claude Code、Cursor、Codex 等 AI 代理平台。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/whyiloveher2411/_biong_backend_FE/tree/HEAD/agent/skills/hyperframes-media

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 憑證存在不存在
TTSHeyGen Starfish REST(原生逐字時間戳)→ ElevenLabs → Kokoro(串連 transcribe 以取得單字)
BGMHeyGen 音樂檢索Lyria → MusicGen 本地生成(分離執行)
SFXHeyGen 音效檢索(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 "..."):

順序供應商偵測條件逐字時間戳
1HeyGen (Starfish)$HEYGEN_API_KEY / hyperframes auth login是,原生 — 傳遞 --words narration.words.json 以捕獲
2ElevenLabs$ELEVENLABS_API_KEY 已設定否 — 之後串連 transcribe
3Kokoro-82M(本地,54 種語音)總是存在(無需金鑰)否 — 之後串連 transcribe

已發布的 hyperframes tts CLI 通常是僅本地建置(其 --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存放位置回退(無憑證)
BGMmusicassets/bgm/track.mp3 (檢索) · track.wav (生成)Lyria / MusicGen 生成
SFXsound_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
轉錄處理 — 輸入格式、品質門檻、清理、APIreferences/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。

相關技能