HyperFrames 媒体
创建资源的 CLI 命令(tts、bgm、transcribe、remove-background),以及在 HTML 中消费和动画化转录数据所需的一切。如需将资源放入合成中,请参见 hyperframes-core。
提供商链(从环境变量自动检测)
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是仅本地构建(其--help显示 "Kokoro-82M" 且没有--provider/--words标志),即使设置了$HEYGEN_API_KEY,它也会静默回退到 Kokoro。要强制使用 HeyGen(无论 CLI 版本如何),请使用自包含的scripts/heygen-tts.mjs(参见references/tts.md)。
BGM — npx hyperframes bgm --duration N:
| 顺序 | 提供商 | 检测条件 |
|---|---|---|
| 1 | Google Lyria (RealTime) | 已设置 $GEMINI_API_KEY 或 $GOOGLE_API_KEY |
| 2 | MusicGen(facebook/musicgen-small,本地) | 已安装 Python 的 transformers + torch + soundfile |
可通过 --provider <name> 覆盖。
路由
| 任务 | 阅读 |
|---|---|
npx hyperframes tts — 提供商链、声音 ID、words.json | references/tts.md |
| 无需 CLI 的 HeyGen — 自包含 REST 脚本(wav + words) | scripts/heygen-tts.mjs(参见 references/tts.md) |
npx hyperframes bgm — Lyria vs MusicGen、情绪提示、调优 | references/bgm.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 |
不可协商的规则
- 声音 ID 是特定于提供商的。
am_michael仅适用于 Kokoro;HeyGen UUID 不适用于 Kokoro。如果你传递--voice,也应指定--provider,以避免当用户环境变量变化时导致提供商静默漂移。 - 始终向
transcribe传递--model。 CLI 默认值small.en会静默翻译非英语音频。参见references/transcribe.md→ "语言规则"。 - HeyGen 返回逐词时间戳;ElevenLabs / Kokoro 不返回。 当需要字幕时,要么向 HeyGen 传递
--words并直接使用该 JSON,要么对音频文件运行transcribe。不要假定逐词数据始终存在。 - 字幕消费扁平词数组格式,包含
{ id, text, start, end }。参见references/transcribe.md→ "输出形状"。 remove-background --background-output是抠出空洞,而非修复补全。 对于"无人场景",需要使用不同的工具。参见references/remove-background.md→ "何时不适用"。