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

hyperframes-media

设计与创作

查看项目

更新于 10-15 08:33

技能介绍

HyperFrames Media 用于为 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）：

  • TTS：有凭据时使用 HeyGen Starfish REST（原生词级时间戳）；无凭据时依次回退到 ElevenLabs → Kokoro（再链式转录以获取词级时间戳）。
  • 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 + words），适用于只需 HeyGen TTS 而无需请求文件的场景。

完整参数列表与 audio_meta.json 模式见 scripts/audio.mjs 头部注释。以下参考文档覆盖各能力背后的提供商细节与边界情况。

预检：生成任何音频前先显示登录状态

在生成语音或 BGM 前始终运行此检查——无论是在完整工作流中，还是一次性的“帮我生成 BGM/配音”请求。没有 HeyGen 凭据不是静默回退到本地引擎的理由：应先建议登录，让用户决定。运行共享预检并原样转述其输出——不要自创“缺少密钥”提示，也不要提出把密钥写入每个仓库的 .env：

npx hyperframes auth status

已登录 → 打印账户信息；继续。

未登录（此处 exit 1 属预期——“未登录”是正常状态，不是失败）→ 打印注册优先的指引。建议登录：npx hyperframes auth login 是浏览器 OAuth——它会登录并创建账户（通过本仓库 CLI 始终可用）。若要使用已有的 HeyGen API key（来自 app.heygen.com/settings/api），运行 npx hyperframes auth login --api-key——它保存到共享的 ~/.heygen（不写入每个仓库的 .env）。输出还会列出语音/BGM 将回退到的本地引擎，以及依赖缺失时的 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；词级时间戳：无——之后链式转录。
  3. Kokoro-82M（本地，54 个声音）：始终可用（无需密钥）；词级时间戳：无——之后链式转录。

已发布的 hyperframes tts CLI 通常是仅本地构建（其 --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 相同的凭据，无凭据时按上述开关回退：

  • BGM：HeyGen 类型 music；落在 assets/bgm/track.mp3（检索）· track.wav（生成）；无凭据回退为 Lyria / MusicGen 生成。
  • SFX：HeyGen 类型 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，以避免用户环境变化时提供商静默漂移。
  • 转录时始终传 --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 在语音 + BGM 之下音量约 0.35。见 references/sfx.md / references/bgm.md。
  • 将工作流字幕 HTML 视为生成输出。对于预设支持的视频，可复用皮肤源位于 .hyperframes/caption-skin.html，工作流脚本写出 compositions/captions.html；不要编辑生成的 compositions/captions.html 来修复皮肤。通过工作流的 captions.mjs 重建，或在存在时使用该工作流显式覆盖机制。