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 consuma e anime esses dados em HTML. Para colocar ativos em composições, veja hyperframes-core.
O mecanismo de áudio — uma única fonte para TTS · BGM · SFX
Os workflows NÃO implementam áudio manualmente ou fazem cópias de fornecedores. Existe um único mecanismo — scripts/audio.mjs — que recebe um audio_request.json neutro e gera audio_meta.json (mais ativos sob assets/voice|bgm|sfx):
# <MEDIA_DIR> = diretório desta 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 CONFIGURAÇÃO — 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 (carimbos de data/hora nativos por palavra) | → ElevenLabs → Kokoro (encadear transcribe para palavras) |
| BGM | Recuperação de música HeyGen | Geração local Lyria → MusicGen (desanexado) |
| SFX | Recuperação de efeitos sonoros HeyGen (min_score 0.4) | biblioteca integrada de 21 arquivos (assets/sfx/) |
- Solicitação (
audio_request.json):{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }. Oidvincula 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 (recuperar quando credenciado, caso contrário gerar). Um explícitoretrieveé 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 em um--outexistente (ex.: TTS+BGM no início, SFX quando as pistas existirem).- A geração BGM é iniciada desanexadamente (
bgm_pending: true) — executescripts/wait-bgm.mjsantes de montar. scripts/heygen-tts.mjsé uma CLI de disparo único sobre o mesmo código (um texto → wav + palavras) para quando você precisar apenas de TTS HeyGen sem um arquivo de solicitação.
A lista completa de flags e o esquema de audio_meta.json estão no cabeçalho de scripts/audio.mjs. As referências abaixo cobrem os detalhes do provedor e os casos extremos por trás de cada capacidade.
Cadeias de provedores (o detalhe por trás do mecanismo)
TTS — o primeiro provedor disponível vence (o mecanismo, ou npx hyperframes tts "..."):
| Ordem | Provedor | Detectado quando | Carimbo de data/hora 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 — encadear transcribe depois |
| 3 | Kokoro-82M (local, 54 vozes) | sempre (nenhuma chave necessária) | Não — encadear transcribe depois |
A CLI publicada
hyperframes ttsé frequentemente a compilação apenas local (seu--helpdiz "Kokoro-82M", sem--provider/--words) e silenciosamente recai para Kokoro mesmo com$HEYGEN_API_KEYdefinida. É por isso que o caminho HeyGen do mecanismo é oscripts/heygen-tts.mjs(REST) independente, 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 HeyGen TTS, com fallback sem credenciais da chave acima:
| Ativo | HeyGen type | Destino | 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 de 21 arquivos (assets/sfx/* + manifest.json) |
Veja references/bgm.md e references/sfx.md.
Roteamento
| Tarefa | Leia |
|---|---|
O mecanismo de áudio — esquema 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 |
| Script TTS Vietnamita — pontuação, fonética (camada TTS) | references/tts-vi.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, áudio-reativo | references/captions/motion.md |
| Caches de modelo, dependências do sistema, solução de problemas | references/requirements.md |
Regras inegociáveis
- Um único mecanismo, sem cópias de fornecedores. Produza áudio via
scripts/audio.mjs(ouheygen-tts.mjspara TTS HeyGen de disparo único). Não reimplemente TTS/BGM/SFX dentro de um workflow — escreva um adaptadoraudio_request.jsone chame o mecanismo. - "HeyGen disponível" = uma credencial resolvível, não a CLI. A chave inteira depende de
heygenCredential(); ohyperframes ttspublicado pode 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 carimbos de data/hora por palavra; ElevenLabs / Kokoro não. O mecanismo encadeia
transcribeautomaticamente para os dois últimos; de forma independente, passe--wordspara HeyGen ou executetranscribecontra o arquivo de áudio. - Legendas consomem o formato de matriz de palavras plana com
{ id, text, start, end }. Vejareferences/transcribe.md→ "Formato de Saída". remove-background --background-outputé recorte de buraco, não preenchimento. Para "cena sem a pessoa", uma ferramenta diferente é necessária. Vejareferences/remove-background.md→ "Quando NÃO é a ferramenta certa".- BGM/SFX usam por padrão a recuperação HeyGen; o fallback sem credenciais é geração (BGM) ou a biblioteca integrada (SFX).
/audio/soundsclassifica por uma consulta de texto — nomeie os efeitos concretamente (vidro quebrando, nãosom dramático); uma falta de correspondência é ignorada, nunca bloqueia a renderização. SFX ficam no volume ~0.35 sob voz + BGM. Vejareferences/sfx.md/references/bgm.md.