Pré-processamento de Mídia HyperFrames
Três comandos de 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, depois referencie-a a partir do HTML da composição — veja o skill hyperframes para as convenções de elementos de áudio/vídeo.
Text-to-Speech (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 | Por que |
|---|---|---|
| Demonstração de produto | af_heart/af_nova | Caloroso, profissional |
| Tutorial / instrucional | am_adam/bf_emma | Neutro, fácil de seguir |
| Marketing / promoção | af_sky/am_michael | Enérgico ou autoritário |
| 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 precisa de --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 em idiomas diferentes do inglês 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— intros, transições, conteúdo animado1.5+— raramente apropriado; teste com cuidado
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). 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 no 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 (Não Negociá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 limpo |
small | 466 MB | Moderado | Padrão — a maioria dos conteúdos |
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 no mínimo com medium; faixas produzidas geralmente precisam de importação manual de SRT/VTT. Para verificações de qualidade de legendas (obrigatórias 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
Composições consomem um array plano 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 retroativa.
[
{ "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 o sujeito (tipicamente uma pessoa — avatar, apresentador, cabeça falante) fique como uma sobreposição transparente em uma composição.
npx hyperframes remove-background sujeito.mp4 -o transparente.webm # padrão: VP9 alpha WebM
npx hyperframes remove-background sujeito.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 sujeito.mp4 -o sujeito.webm \
--background-output placa.webm # ambas as camadas em uma passada
npx hyperframes remove-background sujeito.mp4 -o transparente.webm --device cpu
npx hyperframes remove-background --info # provedores detectados
Usa u2net_human_seg (MIT). Primeira execução baixa ~168 MB de pesos para ~/.cache/hyperframes/background-removal/models/.
Separação de camadas (--background-output)
Passe --background-output (ou -b) para emitir um segundo vídeo transparente junto com o recorte: mesmo RGB de origem, alfa é 255 − máscara em vez de máscara. O recorte é o sujeito com fundo transparente; a placa são os arredores originais com um buraco transparente onde o sujeito estava.
| Arquivo | Alfa é… | Use para |
|---|---|---|
-o sujeito.webm | A máscara — sujeito opaco, fundo transparente | Camada de primeiro plano, coloque em cima |
--background-output placa.webm | Inverso — arredores opacos, região do sujeito transparente | Camada inferior; coloque texto ou gráficos entre esta e o sujeito |
Ambas as saídas compartilham o mesmo preset --quality e são executadas a partir de uma única passada de inferência — o custo de codificação aproximadamente dobra, o custo de segmentação permanece o mesmo. Válido apenas para entradas de vídeo e saídas .webm/.mov.
Placa de furo, não uma placa limpa com inpaint. A região do sujeito em placa.webm é totalmente transparente — componha algo opaco abaixo para preencher o buraco. O único teste para saber se --background-output é a ferramenta certa: alguma coisa será visível através da silhueta do sujeito onde o sujeito costumava estar?
| Caso de uso | Ferramenta correta |
|---|---|
| Texto/gráficos entre o recorte e a placa (razão de existência deste comando) | Furo (--background-output) |
| Sujeito sobre uma cena não relacionada | Apenas sujeito.webm; ignore a placa |
| Mostrar a sala sem a pessoa, sozinha sobre nenhum outro conteúdo | Placa limpa — precisa de um inpaint (LaMa, ProPainter, E2FGVI). Não é este comando. |
| Substituir o sujeito por um sujeito diferente | Placa limpa — igual acima |
Se um usuário pedir "a sala com a pessoa removida" e pretender exibi-la sozinha, não recorra a --background-output. Diga a eles que precisam de um inpaint.
Composição em camadas típica (o caso de uso canônico do furo):
<!-- z=1 a placa de alfa inverso preenche tudo exceto a região do sujeito -->
<video
src="placa.webm"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<!-- z=2 gráficos / texto vivem entre as duas camadas -->
<h1 id="titulo" style="z-index:2; ...">FAÇA EM HYPERFRAMES</h1>
<!-- z=3 o recorte recoloca o sujeito sobre o título -->
<div class="envoltorio-recorte" style="position:absolute;inset:0;z-index:3">
<video
src="sujeito.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
Isso é funcionalmente equivalente ao padrão de texto-atrás-do-sujeito abaixo, mas você não precisa do apresentador.mp4 original no projeto — a placa o substitui. Útil quando você quer enviar apenas as duas camadas transparentes e deixar o usuário colocar conteúdo arbitrário entre elas.
Formato de Saída
| Formato | Quando |
|---|---|
.webm (VP9 + alpha) | Padrão. Composições reproduzem isso diretamente via <video>. |
.mov (ProRes 4444) | Edição no DaVinci/Premiere/FCP. Arquivos grandes. |
.png | Recorte de imagem única (sujeito parado, sobreposto a um fundo). |
O Chrome decodifica VP9 alpha nativamente, então o .webm se conecta a uma composição como qualquer outro vídeo de reprodução automática silenciada — veja o skill hyperframes para as convenções de faixa <video>.
Predefinições de Qualidade
--quality fast|balanced|best controla apenas o CRF do codificador VP9 — a qualidade da segmentação é fixa.
| Predefinição | CRF | Quando |
|---|---|---|
fast | 30 | Iterando, arquivo menor, correspondência de cor mais frouxa |
balanced | 18 | Padrão. Visualmente idêntico para a maioria dos usos |
best | 12 | Master / entrega final. Maior arquivo, correspondência mais precisa |
Padrões de composição — escolha o correto
O webm do recorte é uma cópia re-codificada do RGB do mp4 de origem. Essa escolha tem consequências dependendo do que você coloca atrás dele:
| Padrão | O que está atrás do recorte | Resultado |
|---|---|---|
| Recorte sobre uma cena diferente (mais comum) | Imagem estática, gradiente ou vídeo não relacionado | Fica ótimo. O RGB do recorte é a única fonte do sujeito — sem duplicação, sem halo de borda. É para isso que remove-background foi feito. |
| Recorte sobre seu próprio mp4 de origem (texto-atrás-do-sujeito) | Mesmo mp4 do qual o recorte foi gerado | Duas fontes RGB para a mesma pessoa. Na qualidade --quality balanced padrão (crf 18) a duplicação é quase invisível; na --quality fast (crf 30) você verá uma leve mudança de cor / halo de borda. Use --quality best (crf 12) para masters. |
| Recorte sobre uma tomada diferente da mesma pessoa | Filmagem do mesmo sujeito | Parecerá duas pessoas separadas sobrepostas. Não faça isso. |
Texto-atrás-do-sujeito (título atrás de um apresentador):
<video
src="apresentador.mp4"
id="bg"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<h1 id="titulo" style="z-index:2; ...">FAÇA EM HYPERFRAMES</h1>
<div class="envoltorio-recorte" style="position:absolute;inset:0;z-index:3;opacity:0">
<video
src="apresentador.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
Duas regras principais:
- Envolva o vídeo do recorte em um
<div>sem timing e anime a opacidade do invólucro, não a do elemento de vídeo. O framework força opacidade:1 em clipes ativos (qualquer elemento comdata-start/data-duration), então animar a opacidade do vídeo diretamente é silenciosamente sobrescrito. O invólucro não tem atributosdata-*, então é controlado pelo seu CSS/GSAP. - Ambos os vídeos usam
data-start="0"edata-media-start="0"para que o framework os decodifique em sincronia desde t=0. Montar o recorte tardiamente (data-start=3.3) introduz uma busca + aquecimento que chega um quadro atrasado do mp4 base — visível como um quadro de desalinhamento no corte.
Em seguida, inverta a opacidade do invólucro com GSAP no corte: tl.set(invólucroRecorte, { opacity: 1 }, 3.3).
TTS → Transcrever → Legendas
Quando não há narração pré-gravada, gere uma e transcreva-a de volta para obter timestamps no nível da palavra para legendas:
npx hyperframes tts script.txt --voice af_heart --output narracao.wav
npx hyperframes transcribe narracao.wav # → transcript.json