Pré-processamento de Mídia HyperFrames
Três comandos CLI que produzem ativos para composições: tts (fala), transcribe (timestamps) e remove-background (vídeo transparente). Cada um baixa um modelo na primeira execução e o armazena em cache em ~/.cache/hyperframes/. Coloque a saída no projeto e referencie-a a partir do HTML da composição — veja o skill hyperframes para as convenções de elementos de áudio/vídeo.
Texto para Fala (tts)
Gere áudio de fala localmente com Kokoro-82M. Sem chave de API.
npx hyperframes tts "Texto aqui" --voice af_nova --output narracao.wav
npx hyperframes tts script.txt --voice bf_emma --output narracao.wav
npx hyperframes tts --list # todas as 54 vozes
Seleção de Voz
Combine a voz ao conteúdo. O padrão é af_heart.
| Tipo de conteúdo | Voz | Porquê |
|---|---|---|
| Demonstração de produto | af_heart/af_nova | Calorosa, profissional |
| Tutorial / guia | am_adam/bf_emma | Neutra, fácil de acompanhar |
| Marketing / promoção | af_sky/am_michael | Energética ou autoritária |
| Documentação | bf_emma/bm_george | Inglês britânico claro, formal |
| Casual / social | af_heart/af_sky | Acessível, natural |
Multilíngue
Os IDs de voz codificam o idioma na primeira letra: a=Inglês Americano, b=Inglês Britânico, e=Espanhol, f=Francês, h=Hindi, i=Italiano, j=Japonês, p=Português Brasileiro, z=Mandarim. A CLI detecta automaticamente a localidade do fonemizador a partir do prefixo — não é necessário --lang quando a voz corresponde ao texto.
npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav
Use --lang apenas para sobrescrever a detecção automática (sotaques estilizados). Códigos válidos: en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh. A fonemização para idiomas não ingleses requer espeak-ng no sistema (brew install espeak-ng / apt-get install espeak-ng).
Velocidade
0.7-0.8— tutorial, conteúdo complexo, acessibilidade1.0— ritmo natural (padrão)1.1-1.2— introduções, transições, conteúdo animado1.5+— raramente apropriado; teste cuidadosamente
Scripts Longos
Para mais de alguns parágrafos, escreva em um arquivo .txt e passe o caminho. Entradas com mais de ~5 minutos de fala podem se beneficiar da divisão em segmentos.
Requisitos
Python 3.8+ com kokoro-onnx e soundfile (pip install kokoro-onnx soundfile). O modelo é baixado no primeiro uso (~311 MB + ~27 MB de vozes, armazenado em cache em ~/.cache/hyperframes/tts/).
Transcrição (transcribe)
Produza um transcript.json normalizado com timestamps ao nível da palavra.
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt # importar existente
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
Regra de Idioma (Innegociável)
Nunca use modelos .en a menos que o usuário declare explicitamente que o áudio está em Inglês. Modelos .en (small.en, medium.en) traduzem áudio não-inglês para Inglês em vez de transcrevê-lo. Isso destrói silenciosamente o idioma original.
- Idioma conhecido e não-inglês →
--model small --language <código>(sem sufixo.en) - Idioma conhecido e inglês →
--model small.en - Idioma desconhecido →
--model small(sem.en, sem--language) — whisper detecta automaticamente
O modelo padrão é small, não small.en.
Tamanhos de Modelo
| Modelo | Tamanho | Velocidade | Quando usar |
|---|---|---|---|
tiny | 75 MB | Mais rápido | Pré-visualizações rápidas, teste de pipeline |
base | 142 MB | Rápido | Clipes curtos, áudio claro |
small | 466 MB | Moderado | Padrão — a maioria do conteúdo |
medium | 1,5 GB | Lento | Conteúdo importante, áudio ruidoso, música |
large-v3 | 3,1 GB | Mais lento | Qualidade de produção |
Música com vocais: comece com no mínimo medium; faixas produzidas geralmente precisam de importação manual de SRT/VTT. Para verificações de qualidade de legendas (obrigatório após cada transcrição), o JS de limpeza, regras de repetição e o caminho de importação da API OpenAI/Groq, veja hyperframes/references/transcript-guide.md.
Formato de Saída
As composições consomem uma matriz plana de objetos de palavra. O campo id (w0, w1, ...) é adicionado durante a normalização para referências estáveis em substituições de legendas; é opcional para compatibilidade reversa.
[
{ "id": "w0", "text": "Olá", "start": 0.0, "end": 0.5 },
{ "id": "w1", "text": "mundo.", "start": 0.6, "end": 1.2 }
]
Remoção de Fundo (remove-background)
Remova o fundo de um vídeo ou imagem para que ele possa ficar como uma sobreposição transparente em uma composição (por exemplo, um avatar flutuando sobre uma placa de fundo).
npx hyperframes remove-background avatar.mp4 -o transparente.webm # padrão: VP9 alpha WebM
npx hyperframes remove-background avatar.mp4 -o transparente.mov # ProRes 4444 (edição)
npx hyperframes remove-background retrato.jpg -o recorte.png # recorte de imagem única
npx hyperframes remove-background avatar.mp4 -o transparente.webm --device cpu
npx hyperframes remove-background --info # provedores detectados
Usa u2net_human_seg (MIT). A primeira execução baixa ~168 MB de pesos para ~/.cache/hyperframes/background-removal/models/.
Formato de Saída
| Formato | Quando |
|---|---|
.webm (VP9 + alpha) | Padrão. As composições reproduzem isso diretamente via <video>. |
.mov (ProRes 4444) | Edição em DaVinci/Premiere/FCP. Arquivos grandes. |
.png | Recorte de imagem única (assunto estático, camada sobre um fundo). |
O Chrome decodifica VP9 alpha nativamente, então o .webm se encaixa em uma composição como qualquer outro vídeo com reprodução automática e mudo — veja o skill hyperframes para as convenções de trilhas <video>.
TTS → Transcrição → Legendas
Quando não há narração pré-gravada, gere uma e transcreva-a de volta para obter timestamps ao nível da palavra para legendas:
npx hyperframes tts script.txt --voice af_heart --output narracao.wav
npx hyperframes transcribe narracao.wav # → transcript.json
Whisper extrai limites de palavra precisos do áudio gerado, então o tempo das legendas corresponde à entrega sem ajustes manuais.