HyperFrames Media
Crie os ativos de áudio e mídia que uma composição precisa — narração (TTS), música de fundo + efeitos sonoros, transcrição, legendas, remoção de fundo — e então consuma e anime esses dados em HTML. Para colocar ativos em composições, veja hyperframes-core.
O motor de áudio — uma única fonte para TTS · BGM · SFX
Os workflows NÃO criam áudio manualmente ou fazem cópias avulsas. Existe um único motor — scripts/audio.mjs — que recebe um audio_request.json neutro e escreve audio_meta.json (mais ativos sob assets/voice|bgm|sfx):
# <MEDIA_DIR> = diretório deste skill
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
Todas as três capacidades dependem de UMA ÚNICA CHAVE — se uma credencial HeyGen está presente (resolvida de $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen, não da CLI):
| Capacidade | Credencial HeyGen presente | ausente |
|---|---|---|
| TTS | HeyGen Starfish REST (timestamps nativos por palavra) | → ElevenLabs → Kokoro (encadeie transcribe para palavras) |
| BGM | Busca de música HeyGen | Geração local Lyria → MusicGen (desanexada) |
| SFX | Busca de efeitos sonoros HeyGen (min_score 0.4) | Biblioteca integrada de 21 arquivos (assets/sfx/) |
- Requisição (
audio_request.json):{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [nomes] }], bgm: { mode?, query?, prompt? } }.idliga cada linha de volta ao modelo do chamador (um número de quadro, um ID de cena, …).bgm.mode=retrieve | generate | none; omita para automático (recupera quando credenciado, senão gera). Umretrieveexplícito é estrito — ele pula em vez de iniciar uma geração desanexada (para chamadores sem etapawait-bgm). - Saída (
audio_meta.json, indexado por 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,sfxexecuta um subconjunto e mescla com um--outexistente (ex.: TTS+BGM no início, SFX depois que as cues existirem).- A geração de BGM é iniciada de forma desanexada (
bgm_pending: true) — executescripts/wait-bgm.mjsantes de montar. scripts/heygen-tts.mjsé uma CLI de uso único sobre o mesmo código (um texto → wav + palavras) para quando você precisar apenas do TTS da HeyGen sem um arquivo de requisição.
A lista completa de flags + o esquema de audio_meta.json estão no cabeçalho de scripts/audio.mjs. As referências abaixo cobrem os detalhes dos provedores e casos extremos por trás de cada capacidade.
Pré-voo — mostrar status de login antes de qualquer áudio
Sempre execute isso antes de gerar voz ou BGM — dentro de um workflow completo ou uma solicitação avulsa de "gere um BGM/narração para mim". Ausência de credencial HeyGen não é motivo para cair silenciosamente nos motores locais: primeiro recomende fazer login e deixe o usuário decidir. Execute o pré-voo compartilhado e transmita sua saída literalmente — não improvise seu próprio prompt de "chave ausente" e não se ofereça para escrever chaves em um .env por repositório:
npx hyperframes auth status
- Logado → imprime a conta; prossiga.
- Não logado (
exit 1é esperado aqui — "não logado" é um estado normal, não uma falha) → imprime orientações de registro. Recomende fazer login:npx hyperframes auth loginé OAuth via navegador — ele faz login e cria uma conta (sempre disponível através da CLI deste repositório). Para usar uma chave de API HeyGen existente (de app.heygen.com/settings/api), executenpx hyperframes auth login --api-key— ele salva no~/.heygencompartilhado (sem.envpor repositório). A saída também lista os motores locais de voz/BGM que serão usados como fallback e uma dicapipquando faltarem dependências. Transmita esta saída como está — não a parafraseie com suas próprias palavras. Então PARE e aguarde o usuário escolher — fazer login, ou dizer "vai" / "local" para continuar offline — antes de gerar qualquer coisa. Este é um ponto de decisão real, não uma nota passageira: não o funda em outra pergunta e não prossiga além dele por conta própria. (Exceção: em modo autônomo / não interativo, anote o status e continue offline.) npx hyperframes auth status --jsonretorna{ configured, recommended_action, offline_engines }para ramificação determinística.- Se a CLI não puder ser executada (não está no PATH e
npxnão consegue buscá-la) → ainda assim recomende fazer login (npx hyperframes auth login) e PARE para a escolha do usuário — não trate "nenhuma credencial" como sinal verde silencioso para geração local.
A resolução de credenciais, a prioridade completa de chaves e a lista de dependências locais estão em references/requirements.md.
Cadeias de provedores (os detalhes por trás do motor)
TTS — o primeiro provedor disponível vence (o motor, ou npx hyperframes tts "..."):
| 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 |
A CLI publicada
hyperframes ttsé frequentemente a versão apenas local (seu--helpdiz "Kokoro-82M", sem--provider/--words) e cai silenciosamente para Kokoro mesmo com$HEYGEN_API_KEYdefinido. É por isso que o caminho HeyGen do motor é oscripts/heygen-tts.mjsautossuficiente (REST), NÃO a CLI; a CLI é usada apenas para o caminho Kokoro. Vejareferences/tts.md.
BGM & SFX — por padrão recuperados da biblioteca de áudio HeyGen (/v3/audio/sounds), mesma credencial do TTS HeyGen, com o fallback sem credencial da chave acima:
| Ativo | Tipo HeyGen | Destino | Fallback (sem credencial) |
|---|---|---|---|
| BGM | music | assets/bgm/track.mp3 (recuperação) · track.wav (geração) | Geração Lyria / MusicGen |
| SFX | sound_effects (min_score 0.4) | assets/sfx/<slug>.mp3 | Biblioteca integrada de 21 arquivos (assets/sfx/* + manifest.json) |
Veja references/bgm.md e references/sfx.md.
Roteamento
| Tarefa | Leia |
|---|---|
O motor de áudio — esquema requisição/meta, --only, a chave | scripts/audio.mjs (comentário de cabeçalho) |
npx hyperframes tts / heygen-tts.mjs — provedores, vozes, palavras | references/tts.md |
| BGM — recuperação HeyGen + geração local Lyria / MusicGen | references/bgm.md |
| SFX — recuperação HeyGen (min_score 0.4) + biblioteca local integrada | references/sfx.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 |
| Tratamento de transcrições — formatos de entrada, gates de qualidade, limpeza, APIs | references/captions/transcript-handling.md |
| Movimento de legendas — karaokê, efeitos de marcador, reativo a áudio | references/captions/motion.md |
| Caches de modelo, dependências de sistema, solução de problemas | references/requirements.md |
Regras inegociáveis
- Um único motor, sem cópias avulsas. Produza áudio via
scripts/audio.mjs(ouheygen-tts.mjspara TTS HeyGen de uso único). Não reimplemente TTS/BGM/SFX dentro de um workflow — escreva um adaptadoraudio_request.jsone chame o motor. - "HeyGen disponível" = credencial resolvível, não a CLI. A chave inteira depende de
heygenCredential(); a CLI publicadahyperframes ttspode ser apenas Kokoro, e não existe nenhum comandohyperframes bgm/hyperframes sfx. - IDs de voz são específicos do provedor.
am_michaelé apenas Kokoro; UUIDs da HeyGen não funcionam no Kokoro. Se você passar--voice, também fixe--providerpara evitar deriva silenciosa 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. O motor encadeia
transcribeautomaticamente para os dois últimos; de forma independente, passe--wordspara a HeyGen ou executetranscribecontra o arquivo de áudio. - Legendas consomem o formato de array de palavras plano com
{ id, text, start, end }. Vejareferences/transcribe.md→ "Formato de Saída". remove-background --background-outputé recorte de buraco, não inpainted. Para "cena sem a pessoa", é necessária uma ferramenta diferente. Vejareferences/remove-background.md→ "QUANDO NÃO é a ferramenta certa".- BGM/SFX usam recuperação HeyGen por padrão; o fallback sem credencial é geração (BGM) ou a biblioteca integrada (SFX).
/audio/soundsclassifica por uma consulta de texto — nomeie efeitos concretamente (glass shatter, nãodramatic sound); uma falta de correspondência pula, nunca bloqueia a renderização. SFX ficam em volume ~0,35 sob voz + BGM. Vejareferences/sfx.md/references/bgm.md. - Trate o HTML de legendas do workflow como saída gerada. Para vídeos com skin predefinida, a fonte da skin reutilizável está em
.hyperframes/caption-skin.htmle o script do workflow escrevecompositions/captions.html; não editecompositions/captions.htmlgerado para corrigir a skin. Reconstrua viacaptions.mjsdo workflow, ou use o mecanismo de substituições explícitas desse workflow quando presente.