HyperFrames Media
Crie os ativos de áudio e mídia que uma composição precisa — voz (TTS), música de fundo + efeitos sonoros, transcrição, legendas, remoção de fundo — e consuma e anime esses dados em HTML. Para posicionar ativos em composições, veja hyperframes-core.
O mecanismo de áudio — uma fonte para TTS · BGM · SFX
Os workflows não criam áudio manualmente nem usam cópias avulsas. Existe um mecanismo — scripts/audio.mjs — que recebe um audio_request.json neutro e escreve audio_meta.json (além de ativos em 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 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 (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 embutida de 21 arquivos (assets/sfx/) |
- Solicitação (
audio_request.json):{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }.idvincula cada linha de volta ao modelo do chamador (um número de quadro, um id de cena, …).bgm.mode=retrieve | generate | none; omita para auto (busca quando credenciado, senão gera). Um explícitoretrieveé estrito — ele pula ao invés 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 cedo, SFX quando as cues existirem).- Geração de BGM é desanexada (
bgm_pending: true) — executescripts/wait-bgm.mjsantes de montar. scripts/heygen-tts.mjsé uma CLI de chamada única 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 e o schema de audio_meta.json estão no cabeçalho de scripts/audio.mjs. As referências abaixo cobrem os detalhes dos provedores e casos de borda por trás de cada capacidade.
Pré-voo — mostre o 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 "gere um BGM/voiceover para mim". A ausência de 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 reproduza 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 → ele imprime a conta; prossiga.
- Não logado (
exit 1é esperado aqui — "não logado" é um estado normal, não uma falha) → ele imprime orientação de registro primeiro. 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 mecanismos locais de voz/BGM que serão usados como fallback e uma dicapipquando dependências estiverem faltando. Reproduza essa saída como está — não a parafraseie em suas próprias palavras. Em seguida, PARE e aguarde o usuário escolher — fazer login, ou dizer "vá" / "local" para continuar offline — antes de gerar qualquer coisa. Este é um ponto de decisão real, não uma nota passageira: não o incorpore 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 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 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 mecanismo)
TTS — o primeiro provedor disponível vence (o mecanismo, ou npx hyperframes tts "..."):
| Ordem | Provedor | Detectado quando | Timestamps por palavra |
|---|---|---|---|
| 1 | HeyGen (Starfish) | $HEYGEN_API_KEY / hyperframes auth login | Sim, nativos — 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 compilaçã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 mecanismo é oscripts/heygen-tts.mjsautocontido (REST), NÃO a CLI; a CLI é usada apenas para o caminho Kokoro. Vejareferences/tts.md.
BGM & SFX — por padrão buscados da biblioteca de áudio HeyGen (/v3/audio/sounds), mesma credencial do TTS HeyGen, com o fallback sem credencial da tabela acima:
| Ativo | Tipo HeyGen | Destino | Fallback (sem credencial) |
|---|---|---|---|
| BGM | music | assets/bgm/track.mp3 (busca) · track.wav (geração) | Geração Lyria / MusicGen |
| SFX | sound_effects (min_score 0.4) | assets/sfx/<slug>.mp3 | biblioteca embutida de 21 arquivos (assets/sfx/* + manifest.json) |
Veja references/bgm.md e references/sfx.md.
Roteamento
| Tarefa | Leia |
|---|---|
O mecanismo 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 — busca HeyGen + geração local Lyria / MusicGen | references/bgm.md |
| SFX — busca HeyGen (min_score 0.4) + biblioteca local embutida | 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 voiceover gravado) | references/tts-to-captions.md |
| Autoria de legendas — detecção de estilo, layout, agrupamento de palavras, saída | references/captions/authoring.md |
| Tratamento de transcrição — formatos de entrada, portas 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, resolução de problemas | references/requirements.md |
Regras inegociáveis
- Um mecanismo, sem cópias avulsas. Produza áudio via
scripts/audio.mjs(ouheygen-tts.mjspara TTS HeyGen de chamada única). 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. Toda a chave 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 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 mecanismo encadeia
transcribeautomaticamente para os dois últimos; de forma independente, passe--wordspara o HeyGen ou executetranscribecontra o arquivo de áudio. - Legendas consomem o formato de array de palavras planas com
{ id, text, start, end }. Vejareferences/transcribe.md→ "Formato de Saída". remove-background --background-outputé corte de buraco, não inpaint. Para "cena sem a pessoa", uma ferramenta diferente é necessária. Vejareferences/remove-background.md→ "Quando NÃO é a ferramenta certa".- BGM/SFX padrão é busca HeyGen; o fallback sem credencial é geração (BGM) ou a biblioteca embutida (SFX).
/audio/soundsclassifica por uma consulta de texto — nomeie efeitos concretamente (estilhaço de vidro, nãosom dramático); uma não 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 baseados em preset, a fonte da skin reutilizável fica em
.hyperframes/caption-skin.htmle o script do workflow escrevecompositions/captions.html; não editecompositions/captions.htmlgerado para corrigir a skin. Reconstrua via ocaptions.mjsdo workflow, ou use o mecanismo de sobrescritas explícitas desse workflow quando presente.