HyperFrames Media
Comandos CLI que criam assets (tts, bgm, transcribe, remove-background), além de tudo que é necessário para consumir e animar dados de transcrição em HTML. Para colocar assets em composições, veja hyperframes-core.
Cadeias de provedores (detectados automaticamente por env)
TTS — npx hyperframes tts "..." seleciona o primeiro provedor disponível:
| Ordem | Provedor | Detectado quando | Timestamps por palavra |
|---|---|---|---|
| 1 | HeyGen (Starfish) | $HEYGEN_API_KEY / hyperframes auth login | Sim, nativo — passe --words narration.words.json para capturar |
| 2 | ElevenLabs | $ELEVENLABS_API_KEY definido | Não — encadeie transcribe depois |
| 3 | Kokoro-82M (local, 54 vozes) | sempre (nenhuma chave necessária) | Não — encadeie transcribe depois |
Se o
hyperframes ttsinstalado for a versão apenas local (seu--helpdiz "Kokoro-82M" e não possui as flags--provider/--words), ele cai silenciosamente para Kokoro mesmo com$HEYGEN_API_KEYdefinida. Para forçar HeyGen independentemente da versão da CLI, use o script autossuficientescripts/heygen-tts.mjs(vejareferences/tts.md).
BGM — npx hyperframes bgm --duration N:
| Ordem | Provedor | Detectado quando |
|---|---|---|
| 1 | Google Lyria (RealTime) | $GEMINI_API_KEY ou $GOOGLE_API_KEY definido |
| 2 | MusicGen (facebook/musicgen-small, local) | Python transformers + torch + soundfile instalados |
Substitua qualquer um com --provider <nome>.
Roteamento
| Tarefa | Leia |
|---|---|
npx hyperframes tts — cadeia de provedores, IDs de voz, words.json | references/tts.md |
| HeyGen sem a CLI — script REST autossuficiente (wav + palavras) | scripts/heygen-tts.mjs (veja references/tts.md) |
npx hyperframes bgm — Lyria vs MusicGen, prompts de mood, ajustes | references/bgm.md |
npx hyperframes transcribe — Whisper, regras de modelo, formato de saída | references/transcribe.md |
npx hyperframes remove-background — recortes transparentes | references/remove-background.md |
| TTS → transcrição → legendas (sem narração gravada) | references/tts-to-captions.md |
| Criação de legendas — detecção de estilo, layout, agrupamento de palavras, saída | references/captions/authoring.md |
| Manipulação de transcrições — formatos de entrada, portões de qualidade, limpeza, APIs | references/captions/transcript-handling.md |
| Movimento de legendas — karaokê, efeitos de marcador, áudio-reativo | references/captions/motion.md |
| Caches de modelo, dependências do sistema, solução de problemas | references/requirements.md |
Regras inegociáveis
- IDs de voz são específicas de cada provedor.
am_michaelé exclusivo do Kokoro; UUIDs do HeyGen não funcionam no Kokoro. Se você passar--voice, também fixe--providerpara evitar desvio silencioso de provedor quando o ambiente do usuário mudar. - Sempre passe
--modelparatranscribe. O padrão da CLIsmall.entraduz silenciosamente áudio não-inglês. Vejareferences/transcribe.md→ "Regra de Idioma". - HeyGen retorna timestamps por palavra; ElevenLabs / Kokoro não. Quando você quiser legendas, ou passe
--wordspara HeyGen e use esse JSON diretamente, ou executetranscribecontra o arquivo de áudio. Não presuma que dados de palavra estão sempre presentes. - Legendas consomem o formato de array plano de palavras com
{ id, text, start, end }. Vejareferences/transcribe.md→ "Formato de Saída". remove-background --background-outputé corte de furo, não preenchimento. Para "cena sem a pessoa", outra ferramenta é necessária. Vejareferences/remove-background.md→ "Quando NÃO é a ferramenta certa".