hyperframes-media

HyperFrames Media

创建合成所需的音频和媒体素材——配音（TTS）、背景音乐 + 音效、转录、字幕、背景移除——然后在 HTML 中使用并为这些数据制作动画。关于将素材放入合成中，请参阅 hyperframes-core。

音频引擎——TTS · BGM · SFX 共用一个来源

工作流不会手动编写音频逻辑，也不会附带一份副本。只有一个引擎——scripts/audio.mjs，它接收通用的 audio_request.json，并写入 audio_meta.json（以及 assets/voice|bgm|sfx 下的素材）：

# <MEDIA_DIR> = this skill's directory
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，可在只需要 HeyGen TTS 而不需要请求文件时使用（输入一段文本 → 输出 wav + 词级时间戳）。

完整的标志列表和 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 tts CLI 通常是仅限本地的构建版本（其 --help 显示“Kokoro-82M”，且没有 --provider/--words），即使设置了 $HEYGEN_API_KEY，也会静默回退到 Kokoro。这就是引擎通过独立的 scripts/heygen-tts.mjs（REST）实现 HeyGen 路径的原因，而不是使用 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 → “Language Rule”。
• HeyGen 会返回词级时间戳；ElevenLabs / Kokoro 不会。 对于后两者，引擎会自动接续调用 transcribe；单独使用时，向 HeyGen 传入 --words，或对音频文件运行 transcribe。
• 字幕使用扁平词数组格式，格式为 { id, text, start, end }。参见 references/transcribe.md → “Output Shape”。
• remove-background --background-output 会抠出透明区域，而非进行修复。 若要获得“没有人物的场景”，需要使用其他工具。参见 references/remove-background.md → “When NOT the right tool”。
• BGM/SFX 默认通过 HeyGen 检索；无凭据时，BGM 会改为生成，SFX 会使用捆绑的素材库。 /audio/sounds 会根据文本查询排序——请具体描述音效（例如 glass shatter，而不是 dramatic sound）；如果没有匹配项，会跳过，不会阻止渲染。SFX 在人声和 BGM 下方的音量约为 0.35。参见 references/sfx.md / references/bgm.md。
• 将工作流中的字幕 HTML 视为生成产物。 对于使用预设的视频，可复用的样式源文件位于 .hyperframes/caption-skin.html，工作流脚本会写入 compositions/captions.html；不要通过编辑生成的 compositions/captions.html 来修复样式。请通过工作流的 captions.mjs 重新构建，或在工作流提供相应机制时使用其显式覆盖机制。