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 的开头注释中。下面的参考文献涵盖了每种能力背后的供应商细节和边界情况。
预检 —— 在任何音频之前显示登录状态
在生成配音或背景音乐之前始终运行此步骤 —— 无论是在完整工作流内部还是单独的“生成一段背景音乐/配音”请求中。 没有 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)。输出还会列出本地引擎在语音/背景音乐方面的回退选项,以及依赖缺失时的pip提示。原样输出此结果 —— 不要用自己的措辞重新阐述。 然后停止并等待用户选择 —— 登录,或者说“GO”/“local”以离线继续 —— 然后才开始生成任何内容。 这是一个真正的决策点,不是路过提示:不要把它折叠到另一个问题中,也不要自行继续。(例外:在自治/非交互模式下,记录状态并离线继续。) 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 使用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);未匹配则跳过,永不阻塞渲染。在语音 + BGM 下,SFX 音量约为 ~0.35。参见references/sfx.md/references/bgm.md。 - 将工作流中的字幕 HTML 视为生成的输出。 对于基于预设的视频,可重用的皮肤源位于
.hyperframes/caption-skin.html,工作流脚本写入compositions/captions.html;不要编辑生成的compositions/captions.html来修复皮肤。通过工作流的captions.mjs重新构建,或者使用该工作流中存在的显式覆盖机制。