hyperframes-media

HyperFrames Media

创建资产（tts、bgm、transcribe、remove-background）的 CLI 命令，以及消费和动画化 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 与 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 → "何时不是正确的工具"。