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 的头部注释中。以下参考涵盖了每种能力背后的提供商细节和边缘情况。
提供商链(引擎背后的细节)
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。
路由
| 任务 | 查阅参考 |
|---|---|
音频引擎——请求/meta 模式、--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,以避免用户环境变化时提供商静默漂移。 - 始终向
transcribe传递--model。 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按文本查询排序——需具体命名音效(如glass shatter,而非dramatic sound);无匹配则跳过,绝不阻塞渲染。SFX 在语音 + BGM 下的默认音量约为 0.35。参见references/sfx.md/references/bgm.md。