Manavv007/S.A.R.A.L.-Esquema-de-Acesso-Recuperação-Análise-de-C…

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 motor de áudio — uma fonte para TTS · BGM · SFX

Os workflows NÃO criam áudio manualmente ou fazem cópias avulsas. Há um 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 degradam com base em UM ÚNICO SELETOR — 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 de palavra)	→ ElevenLabs → Kokoro (encadeie transcribe para palavras)
BGM	Recuperação de música HeyGen	Geração local Lyria → MusicGen (desanexada)
SFX	Recuperação 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?: [names] }], bgm: { mode?, query?, prompt? } }. id une cada linha ao modelo do chamador (um número de quadro, um ID de cena, …). bgm.mode = retrieve | generate | none; omita para auto (recuperar quando credenciado, senão gerar). Um retrieve explícito é estrito — ele pula em vez de iniciar uma geração desanexada (para chamadores sem etapa wait-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,sfx executa um subconjunto e funde em um --out existente (ex.: TTS+BGM no início, SFX assim que as deixa existirem).
• BGM gerado é disparado desanexado (bgm_pending: true) — execute scripts/wait-bgm.mjs antes 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 de TTS HeyGen sem um arquivo de requisição.

A lista completa de flags e o esquema do audio_meta.json estão no cabeçalho de scripts/audio.mjs. As referências abaixo cobrem os detalhes do provedor e casos extremos de cada capacidade.

Pré-voo — mostrar status de login antes de qualquer áudio

Sempre execute isto antes de gerar voz ou BGM — dentro de um workflow completo ou uma requisição avulsa de 'gere um BGM/narração para mim'. Não ter 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 na íntegra — 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ção de registro primeiro. Recomende fazer login: npx hyperframes auth login é OAuth pelo 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), execute npx hyperframes auth login --api-key — ele salva no ~/.heygen compartilhado (sem .env por repositório). A saída também lista os motores locais para os quais voz/BGM cairá e uma dica pip quando dependências faltarem. 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 mescle 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 --json retorna { configured, recommended_action, offline_engines } para ramificação determinística.
• Se a CLI não puder ser executada (não no PATH e npx nã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	Timestamps de 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 --help diz 'Kokoro-82M', sem --provider/--words) e cai silenciosamente para Kokoro mesmo com $HEYGEN_API_KEY definido. É por isso que o caminho HeyGen do motor é o scripts/heygen-tts.mjs autocontido (REST), NÃO a CLI; a CLI é usada apenas para o caminho Kokoro. Veja references/tts.md.

BGM e SFX — por padrão recuperados da biblioteca de áudio HeyGen (/v3/audio/sounds), mesma credencial do TTS HeyGen, com o fallback sem credenciais do seletor acima:

Ativo	Tipo type do HeyGen	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 motor de áudio — esquema request/meta, --only, o seletor	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
Criação de legendas — detecção de estilo, layout, agrupamento de palavras, saída	references/captions/authoring.md
Manipulação de transcrição — formatos de entrada, gates 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 de sistema, solução de problemas	references/requirements.md

Regras inegociáveis

• Um motor, sem cópias avulsas. Produza áudio via scripts/audio.mjs (ou heygen-tts.mjs para TTS HeyGen avulso). Não reimplemente TTS/BGM/SFX dentro de um workflow — escreva um adaptador audio_request.json e chame o motor.
• 'HeyGen disponível' = uma credencial resolvível, não a CLI. Todo o seletor depende de heygenCredential(); a CLI publicada hyperframes tts pode ser apenas Kokoro, e não há comando hyperframes 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 --provider para evitar deriva silenciosa de provedor quando o ambiente do usuário mudar.
• Sempre passe --model para transcribe. O padrão da CLI small.en traduz silenciosamente áudio não-inglês. Veja references/transcribe.md → 'Regra de Idioma'.
• HeyGen retorna timestamps de palavra; ElevenLabs / Kokoro não. O motor encadeia transcribe automaticamente para os dois últimos; de forma independente, passe --words para HeyGen ou execute transcribe contra o arquivo de áudio.
• Legendas consomem o formato de array plano de palavras com { id, text, start, end }. Veja references/transcribe.md → 'Formato da Saída'.
• remove-background --background-output é corte de buraco, não inpaint. Para 'cena sem a pessoa', uma ferramenta diferente é necessária. Veja references/remove-background.md → 'Quando NÃO é a ferramenta certa'.
• BGM/SFX padrão é recuperação HeyGen; o fallback sem credenciais é geração (BGM) ou a biblioteca integrada (SFX). /audio/sounds classifica por uma consulta de texto — nomeie os efeitos concretamente (glass shatter, não dramatic sound); uma não correspondência pula, nunca bloqueia a renderização. SFX ficam no volume ~0,35 sob voz + BGM. Veja references/sfx.md / references/bgm.md.
• Trate o HTML de legenda do workflow como saída gerada. Para vídeos baseados em preset, a fonte da skin reutilizável está em .hyperframes/caption-skin.html e o script do workflow escreve compositions/captions.html; não edite o compositions/captions.html gerado para corrigir a skin. Reconstrua via captions.mjs do workflow, ou use o mecanismo de substituições explícitas desse workflow quando presente.