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 fluxos de trabalho NÃO criam áudio manualmente nem fazem uma cópia de fornecedor. Existe um único motor — scripts/audio.mjs — que recebe um audio_request.json neutro e escreve audio_meta.json (mais ativos em assets/voice|bgm|sfx):
# <MEDIA_DIR> = diretório desta habilidade
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
Todas as três capacidades degradam com base em UMA 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 (timbros de palavras nativos) | → ElevenLabs → Kokoro (encadeie transcribe para palavras) |
| BGM | Recuperação de música do HeyGen | Geração local Lyria → MusicGen geração (desanexada) |
| SFX | Recuperação de efeitos sonoros do HeyGen (min_score 0.4) | biblioteca integrada com 21 arquivos (assets/sfx/) |
- Solicitação (
audio_request.json):{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [nomes] }], bgm: { mode?, query?, prompt? } }.idvincula cada linha ao modelo do chamador (um número de quadro, um id de cena, …).bgm.mode=retrieve | generate | none; omitir para auto (recuperar quando credenciado, senão gerar). Umretrieveexplícito é estrito — ele ignora em vez de iniciar uma geração desanexada (para chamadores sem uma etapawait-bgm). - Saída (
audio_meta.json, chaveado 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 em um--outexistente (ex.: TTS+BGM no início, SFX quando houver dicas).- A geração BGM é iniciada desanexada (
bgm_pending: true) — executescripts/wait-bgm.mjsantes de montar. scripts/heygen-tts.mjsé uma CLI de tiro único sobre o mesmo código (um texto → wav + palavras) para quando você precisa apenas de TTS HeyGen sem um arquivo de solicitação.
A lista completa de flags + o schema de audio_meta.json estão no cabeçalho de scripts/audio.mjs. As referências abaixo cobrem os detalhes do provedor 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 fluxo de trabalho completo ou uma solicitação única de "gere um BGM/narração para mim". Não ter credencial HeyGen não é motivo para cair silenciosamente em mecanismos locais: primeiro recomende fazer login e deixe o usuário decidir. Execute o pré-voo compartilhado e retransmita sua saída literalmente — não improvise seu próprio prompt de "chave faltando" e não ofereça escrever chaves em um .env por repositório:
npx hyperframes auth status
- Conectado → ele imprime a conta; prossiga.
- Não conectado (
exit 1é esperado aqui — "não conectado" é um estado normal, não uma falha) → ele imprime orientações de registro primeiro. Recomende fazer login:npx hyperframes auth loginé OAuth do 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 mecanismos locais para os quais a voz/BGM cairão e uma dicapipquando dependências estiverem faltando. Retransmita esta saída como está — não a parafraseie em suas próprias palavras. Em seguida, PARE e aguarde a escolha do usuário — 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 a transforme em outra pergunta e não prossiga além dela 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 no PATH e
npxnão puder obtê-la) → ainda recomende fazer login (npx hyperframes auth login) e PARE para a escolha do usuário — não trate "sem credencial" como um 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 (o detalhe por trás do motor)
TTS — o primeiro provedor disponível vence (o motor, ou npx hyperframes tts "..."):
| Ordem | Provedor | Detectado quando | Timbros de palavras |
|---|---|---|---|
| 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_KEYdefinida. É por isso que o caminho HeyGen do motor é o autossuficientescripts/heygen-tts.mjs(REST), NÃO a CLI; a CLI é usada apenas para o caminho Kokoro. Vejareferences/tts.md.
BGM e SFX — por padrão recuperados da biblioteca de áudio do HeyGen (/v3/audio/sounds), mesma credencial do TTS HeyGen, com o fallback sem credencial da chave acima:
| Ativo | Tipo HeyGen | Chega em | Fallback (sem credencial) |
|---|---|---|---|
| BGM | music | assets/bgm/track.mp3 (recuperar) · track.wav (gerar) | Geração Lyria / MusicGen |
| SFX | sound_effects (min_score 0.4) | assets/sfx/<slug>.mp3 | biblioteca integrada com 21 arquivos (assets/sfx/* + manifest.json) |
Veja references/bgm.md e references/sfx.md.
Roteamento
| Tarefa | Leia |
|---|---|
O motor de áudio — schema de solicitação/meta, --only, a chave | scripts/audio.mjs (comentário do 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 |
| Autoria 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, reativo a áudio | references/captions/motion.md |
| Caches de modelo, dependências do sistema, solução de problemas | references/requirements.md |
Regras inegociáveis
- Um motor, sem cópias de fornecedor. Produza áudio via
scripts/audio.mjs(ouheygen-tts.mjspara TTS HeyGen de tiro único). Não reimplemente TTS/BGM/SFX dentro de um fluxo de trabalho — escreva um adaptadoraudio_request.jsone chame o motor. - "HeyGen disponível" = uma credencial resolvível, não a CLI. A chave inteira depende de
heygenCredential(); a CLI publicadahyperframes ttspode ser apenas Kokoro, e não há nenhum comandohyperframes bgm/hyperframes sfx. - IDs de voz são específicos do provedor.
am_michaelé apenas 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 timbros de palavras; ElevenLabs / Kokoro não. O motor encadeia
transcribeautomaticamente para os dois últimos; de forma independente, passe--wordspara HeyGen ou executetranscribecontra o arquivo de áudio. - 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 buraco, não inpainted. Para "cena sem a pessoa", uma ferramenta diferente é necessária. 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 (vidro quebrando, nãosom dramático); uma falta de correspondência ignora, nunca bloqueia a renderização. SFX ficam em volume ~0.35 sob voz + BGM. Vejareferences/sfx.md/references/bgm.md. - Trate o HTML de legenda do fluxo de trabalho como saída gerada. Para vídeos baseados em predefinições, a fonte de skin reutilizável vive em
.hyperframes/caption-skin.htmle o script do fluxo de trabalho escrevecompositions/captions.html; não edite ocompositions/captions.htmlgerado para corrigir a skin. Reconstrua através docaptions.mjsdo fluxo de trabalho, ou use o mecanismo de substituições explícitas desse fluxo de trabalho quando presente.