Communitygithub.com

whyiloveher2411/_biong_backend_FE

为 HyperFrames 合成作品生成音频和媒体资产,由统一的音频引擎(`scripts/audio.mjs`)驱动——支持多提供商 TTS(HeyGen / ElevenLabs / 本地 Kokoro)、背景音乐 + 音效(默认通过 HeyGen 音频库检索,并具备本地 Lyria / MusicGen BGM 生成和内置 SFX 库作为免凭证后备)、Whisper 转录、背景去除和字幕制作。适用于配音 / TTS、BGM、SFX / 音效、转录、字幕 / 副标题 / 歌词 / 卡拉 OK / 逐词样式、语音 + 提供商选择以及音乐情绪提示。

_biong_backend_FE 是什么?

该技能是 HyperFrames 媒体引擎,专为合成作品提供端到端的语音和音频资产生成。它围绕一个核心脚本 `scripts/audio.mjs` 构建,接受统一的 `audio_request.json` 输入,输出结构化的 `audio_meta.json` 以及按类型(voice/bgm/sfx)组织的媒体文件。引擎的关键设计在于其优雅的降级策略:当检测到 HeyGen 凭证时,优先使用 HeyGen 的 TTS、BGM 检索和 SFX 检索;若无凭证,则自动降级至本地 Kokoro TTS、Lyria/MusicGen 本地 BGM 生成以及一个内置的 21 个文件 SFX 库。这种单引擎、免硬编码的路线确保了所有工作流使用同一套音频逻辑,避免了提供商锁定。该技能支持 HeyGen、ElevenLabs 和 Kokoro 三种 TTS 提供商,其中 HeyGen 原生支持逐词时间戳,另两者需链式调用转录。对于 BGM 和 SFX,引擎默认从 HeyGen 检索,但无凭证时分别切换到本地生成或内置库,保证了最低可用性。此外,技能还覆盖了从 TTS 到字幕的完整管线——包括使用 Whisper 进行多语言转录(需指定模型以避免语言误翻)、背景去除(输出透明裁切而非修补)、以及支持卡拉 OK 和逐词样式的复合字幕编排。非协商规则包括:统一使用引擎而不得在各工作流中重新实现音频逻辑;语音 ID 与提供商绑定(如 Kokoro 的 `am_michael` 与 HeyGen UUID 不兼容);始终向 `transcribe` 传递 `--model` 避免英语默认模型对非英语音频的无声翻译;以及 BGM/SFX 默认检索,无匹配时跳过而非阻塞渲染,SFX 默认音量约为 0.35。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/whyiloveher2411/_biong_backend_FE/tree/HEAD/agent/skills/hyperframes-media

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 凭证存在凭证缺失
TTSHeyGen Starfish REST(原生逐词时间戳)→ ElevenLabs → Kokoro(链式调用 transcribe 以获取词)
BGMHeyGen 音乐检索Lyria → MusicGen 本地生成(分离式)
SFXHeyGen 音效检索(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 "..."):

顺序提供商检测条件逐词时间戳
1HeyGen (Starfish)$HEYGEN_API_KEY / hyperframes auth login是,原生——传递 --words narration.words.json 以捕获
2ElevenLabs$ELEVENLABS_API_KEY 已设置否——之后链式调用 transcribe
3Kokoro-82M (本地,54 种语音)始终可用(无需密钥)否——之后链式调用 transcribe

已发布的 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 相同的凭证,并在无凭证时使用上方开关中的后备方案:

资产HeyGen type存放位置后备(无凭证)
BGMmusicassets/bgm/track.mp3 (检索) · track.wav (生成)Lyria / MusicGen 生成
SFXsound_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
转录处理——输入格式、质量门控、清理、APIreferences/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。

相关技能