SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场hyperframes-media

hyperframes-media

设计与创作

查看项目

更新于 11-08 16:04

技能介绍

HyperFrames Media 用于创建合成所需的音频与媒体素材，包括语音旁白（TTS）、背景音乐与音效、转录、字幕和背景移除，随后可在 HTML 中消费并动画化这些数据。将素材放入合成的部分参见 hyperframes-core。

一、音频引擎 工作流不自行手写音频，也不复制供应商代码，而是统一使用引擎 scripts/audio.mjs：它接收中性的 audio_request.json，并写出 audio_meta.json 以及 assets/voice、assets/bgm、assets/sfx 下的素材。调用命令为： node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json 其中 <MEDIA_DIR> 为该技能目录。

请求文件格式为：{ 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 凭证（从 $HEYGEN_API_KEY、$HYPERFRAMES_API_KEY 或 ~/.heygen 解析，而非来自 CLI）。

  • TTS：有凭证时使用 HeyGen Starfish REST（原生词级时间戳）；无凭证时依次降级到 ElevenLabs、Kokoro（后两者需链式转录以获得词级时间戳）。
  • BGM：有凭证时从 HeyGen 音乐库检索；无凭证时用 Lyria 或 MusicGen 本地生成（分离进程）。
  • SFX：有凭证时从 HeyGen 音效库检索（min_score 0.4）；无凭证时使用内置的 21 文件音效库（assets/sfx/）。

三、生成前预检 在生成语音或 BGM 之前（无论完整工作流还是一次性请求），都应先运行 npx hyperframes auth status 并原样转述其输出，不要自行编造“缺少密钥”提示，也不要提出把密钥写入仓库级 .env。已登录则直接继续；未登录（退出码 1 属正常状态）会输出优先注册的指引，此时应建议登录：npx hyperframes auth login 为浏览器 OAuth，可登录并创建账号；若要使用已有 HeyGen API 密钥（来自 app.heygen.com/settings/api），运行 npx hyperframes auth login --api-key，密钥保存到共享的 ~/.heygen。输出还会列出本地降级引擎及依赖缺失时的 pip 提示，需原样转述，然后停下等待用户选择（登录，或回复 go / local 离线继续）后再生成。自主或非交互模式下可记录状态并离线继续。npx hyperframes auth status --json 返回 { configured, recommended_action, offline_engines } 便于确定性分支。若 CLI 无法运行，仍应建议登录并停下等待用户选择。凭证解析优先级与本地依赖清单见 references/requirements.md。

四、提供商链路 TTS 按首个可用提供商优先：1) HeyGen（Starfish），检测条件为 $HEYGEN_API_KEY 或已登录，原生词级时间戳，可用 --words narration.words.json 捕获；2) ElevenLabs，设置 $ELEVENLABS_API_KEY 时启用，无词级时间戳，需链式转录；3) Kokoro-82M 本地（54 个音色），始终可用，无词级时间戳，需链式转录。已发布的 hyperframes tts CLI 常为仅本地构建（--help 显示 Kokoro-82M，无 --provider/--words），即使设置了 $HEYGEN_API_KEY 也会静默回退到 Kokoro；因此引擎的 HeyGen 路径使用自包含的 scripts/heygen-tts.mjs（REST），CLI 仅用于 Kokoro 路径。详见 references/tts.md。

BGM 与 SFX 默认从 HeyGen 音频库（/v3/audio/sounds）检索，使用与 HeyGen TTS 相同的凭证；无凭证时按上述开关回退。BGM 有凭证时检索为 assets/bgm/track.mp3，生成时为 track.wav；SFX 有凭证时检索为 assets/sfx/<slug>.mp3，无凭证时使用内置 21 文件库（assets/sfx/* 与 manifest.json）。详见 references/bgm.md 和 references/sfx.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：CLI 默认 small.en 会静默翻译非英语音频，详见 references/transcribe.md 的“Language Rule”。
  • HeyGen 返回词级时间戳，ElevenLabs 与 Kokoro 不返回；引擎对后两者自动链式转录，单独使用时对 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 音量约 0.35，位于人声与 BGM 之下。
  • 工作流字幕 HTML 视为生成产物：使用预设的视频，可复用皮肤源位于 .hyperframes/caption-skin.html，工作流脚本写出 compositions/captions.html；不要直接编辑生成的字幕 HTML 来修皮肤，应通过工作流的 captions.mjs 重建，或使用工作流提供的显式覆盖机制。

六、适用场景与限制 适用于为 HyperFrames 合成补充配音、配乐、音效，完成语音转录与字幕制作，以及背景移除等媒体素材准备。限制方面：HeyGen 相关能力依赖可解析凭证，无凭证时按上述链路降级；部分 CLI 为仅本地构建；背景移除不适合需要修复被移除区域的场景；BGM 生成需在组装前等待完成。