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是预期行为——