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 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 (mais 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 dependem de UMA ÚNICA CONDIÇÃ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 (timestamps nativos) | → ElevenLabs → Kokoro (encadeie transcribe para palavras) |
| BGM | HeyGen recuperação de música | Lyria → MusicGen geração local (desanexada) |
| SFX | HeyGen recuperação de efeitos sonoros (min_score 0.4) | biblioteca local de 21 arquivos (assets/sfx/) |
- Requisição (
audio_request.json):{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [nomes] }], bgm: { mode?, query?, prompt? } }.idconecta cada linha de volta ao modelo do chamador (um número de frame, um id de cena, …).bgm.mode=retrieve | generate | none; omita para auto (recuperar quando credenciado, senão gerar). Um modo explícitoretrieveé estrito — ele ignora em vez de iniciar uma geração desanexada (para chamadores sem a 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 faz merge em um--outexistente (ex.: TTS+BGM no início, SFX quando as deixas existirem).- A geração BGM é iniciada 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ê só precisa do TTS HeyGen sem um arquivo de requisição.
A lista completa de flags + o esquema 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.
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 em uma solicitação avulsa 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 repasse 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 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 para os quais a voz/BGM cairão e uma dicapipquando as dependências estiverem faltando. Repasse 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 de passagem: não o dobre 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 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 mecanismo)
TTS — o primeiro provedor disponível vence (o mecanismo, ou npx hyperframes tts "..."):
| Ordem | Provedor | Detectado quando | Timestamps de palavras |
|---|---|---|---|
| 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 após |
| 3 | Kokoro-82M (local, 54 vozes) | sempre (nenhuma chave necessária) | Não — encadeie transcribe após |
A CLI publicada
hyperframes ttsgeralmente é 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.mjs(REST) autocontido, 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 | HeyGen type | Vai para | Fallback (sem credencial) |
|---|---|---|---|
| BGM | music | assets/bgm/track.mp3 (recuperar) · track.wav (gerar) | Lyria / MusicGen geração |
| SFX | sound_effects (min_score 0.4) | assets/sfx/<slug>.mp3 | biblioteca local de 21 arquivos (assets/sfx/* + manifest.json) |
Veja references/bgm.md e references/sfx.md.
Roteamento
| Tarefa | Leia |
|---|---|
O mecanismo de áudio — esquema de requisiçã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 compacta | 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 |
| 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 mecanismo, nenhuma cópia avulsa. 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 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 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 de palavras; ElevenLabs / Kokoro não. O mecanismo encadeia
transcribeautomaticamente para os dois últimos; de forma independente, passe--wordspara HeyGen ou executetranscribeno 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 é recuperação HeyGen; o fallback sem credencial é geração (BGM) ou biblioteca local (SFX).
/audio/soundsclassifica por uma consulta de texto — nomeie os efeitos concretamente (glass shatter, nãodramatic sound); uma não correspondência ignora, nunca bloqueia a renderização. SFX ficam em volume ~0,35 acima da voz + BGM. Vejareferences/sfx.md/references/bgm.md. - Trate o HTML de legendas do workflow como saída gerada. Para vídeos baseados em predefinições, o código-fonte da pele reutilizável está em
.hyperframes/caption-skin.htmle o script do workflow escrevecompositions/captions.html; não edite ocompositions/captions.htmlgerado para corrigir a pele. Reconstrua viacaptions.mjsdo workflow ou use o mecanismo de substituições explícitas desse workflow quando presente.