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 faça referência a ela a partir do HTML da composição — veja a 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 | Motivo |
|---|---|---|
| Demonstração de produto | af_heart/af_nova | Caloroso, profissional |
| Tutorial / guia | am_adam/bf_emma | Neutro, fácil de acompanhar |
| Marketing / promo | af_sky/am_michael | Energético 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 fonetizador 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 substituir 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 instalado 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 com cuidado
Scripts Longos
Para mais do que 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 na primeira execução (~311 MB + ~27 MB de vozes, armazenado em cache em ~/.cache/hyperframes/tts/).
Transcrição (transcribe)
Produza um transcript.json normalizado com timestamps em nível de 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 o 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, testar pipeline |
base | 142 MB | Rápido | Clipes curtos, áudio claro |
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 com medium no mínimo; faixas produzidas geralmente precisam de importação manual de SRT/VTT. Para verificações de qualidade de legenda (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
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 legenda; é 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 o sujeito (tipicamente uma pessoa — avatar, apresentador, pessoa falando) 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 passagem
npx hyperframes remove-background sujeito.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/.
Separação de Camadas (--background-output)
Passe --background-output (ou -b) para emitir um segundo vídeo transparente junto com o recorte: mesmo RGB da fonte, alfa é 255 − máscara em vez de máscara. O recorte é o sujeito com fundo transparente; a placa é o ambiente original 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 por cima |
--background-output placa.webm | Inverso — ambiente opaco, região do sujeito transparente | Camada de fundo; coloque texto ou gráficos entre esta e o sujeito |
Ambas as saídas compartilham a mesma predefinição --quality e são executadas a partir de uma única passagem 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 com furo, não uma placa limpa com preenchimento. A região do sujeito em placa.webm é totalmente transparente — componha algo opaco por baixo para preencher o buraco. O único teste para saber se --background-output é a ferramenta certa: alguma coisa ficará visível através da silhueta do sujeito onde o sujeito estava?
| Caso de uso | Ferramenta certa |
|---|---|
| Texto/gráficos entre o recorte e a placa (razão de existir 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 — mesma situação acima |
Se um usuário pedir "a sala com a pessoa removida" e pretender exibi-la sozinha, não use --background-output. Diga a ele que precisa de um inpaint.
Composição típica em camadas (o caso de uso canônico do furo):
<!-- z=1 a placa com 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="headline" style="z-index:2; ...">FAÇA EM HYPERFRAMES</h1>
<!-- z=3 o recorte coloca o sujeito de volta sobre o título -->
<div class="cutout-wrap" 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 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. As composições reproduzem isso diretamente com <video>. |
.mov (ProRes 4444) | Edição em 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 encaixa em uma composição como qualquer outro vídeo com muted-autoplay — veja a 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 solta |
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 recortado é uma cópia recodificada 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 | Ótimo resultado. O RGB do recorte é a única fonte do sujeito — sem duplicação, sem halo nas bordas. É para isso que remove-background foi criado. |
| Recorte sobre seu próprio mp4 de origem (texto-atrás-do-sujeito) | Mesmo mp4 do qual o recorte foi gerado | Duas fontes de RGB para a mesma pessoa. Na predefinição --quality balanced (crf 18) a duplicação é quase invisível; em --quality fast (crf 30) você verá uma leve mudança de cor / halo nas bordas. Use --quality best (crf 12) para masters. |
| Recorte sobre uma tomada diferente da mesma pessoa | Filmagem do mesmo sujeito | Vai parecer duas pessoas diferentes 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="headline" style="z-index:2; ...">FAÇA EM HYPERFRAMES</h1>
<div class="cutout-wrap" 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 essenciais:
- Envolva o vídeo recortado em um
<div>sem temporização e anime a opacidade do wrapper, não do elemento de vídeo. O framework força opacity:1 em clipes ativos (qualquer elemento comdata-start/data-duration), então animar a opacidade do vídeo diretamente é silenciosamente sobrescrito. O wrapper 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 a partir de t=0. Montar o recorte tardiamente (data-start=3.3) introduz uma busca + aquecimento que resulta em um quadro fora do mp4 base — visível como um quadro de desalinhamento no corte.
Em seguida, inverta a opacidade do wrapper com GSAP no corte: tl.set(cutoutWrap, { opacity: 1 }, 3.3).
TTS → Transcrever → Legendas
Quando não há narração pré-gravada, gere uma e a transcreva de volta para obter timestamps em nível de palavra para legendas:
npx hyperframes tts script.txt --voice af_heart --output narracao.wav
npx hyperframes transcribe narracao.wav # → transcript.json
# chain the output