Pré-processamento de Mídia HyperFrames
Três comandos CLI que produzem assets 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 no 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 | Motivo |
|---|---|---|
| Demonstração de produto | af_heart/af_nova | Caloroso, profissional |
| Tutorial / instruções | am_adam/bf_emma | Neutro, fácil de seguir |
| Marketing / promoção | 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 das vozes 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. O 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 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 em 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 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). Os modelos são baixados no primeiro uso (~311 MB + ~27 MB de vozes, armazenados 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 (Inegociá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 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 frequentemente 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/reference/transcript-guide.md.
Formato de Saída
As 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 fundo.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). A primeira execução baixa ~168 MB de pesos para ~/.cache/hyperframes/background-removal/models/.
NÃO use u2net para adesivos recortados com contorno branco
remove-background (u2net) é segmentação de objeto saliente — ele segmenta o corpo do sujeito e corta o contorno branco do recorte, porque o traço branco ao redor da figura não é "o objeto". Para adesivos transparentes de Telegram / mensagens renderizados com um contorno branco sobre um fundo de cor plana conhecida, key o fundo em vez de segmentar o sujeito:
- Preenchimento por inundação do fundo plano.
PIL.ImageDraw.floodfillsemeado a partir de pontos ao longo das quatro bordas (passo ~24px), marque pixels preenchidos → alpha 0, todo o resto opaco. Isso preserva o contorno branco E props internos da mesma cor E ilhas desconectadas (um copo voando separado do corpo mantém seu próprio contorno). Requer que o prompt de geração coloque o sujeito em um fundo uniforme e plano e peça pelo contorno branco recortado explicitamente. - Variante sem contorno (mais limpa do que remover um contorno assado): re-execute cada imagem imagem-para-imagem — passe o render finalizado como
--refe peça "recrie a pose/props idênticos mas REMOVA o contorno branco e coloque em um chroma-key verde puro (#00b140) plano", então key o verde com um chroma key suave, nunca uma máscara binária (alpha = limitar((HIGH-(G-max(R,B)))/(HIGH-LOW),0,1), LOW≈30 HIGH≈95, mais despill globalG = min(G, max(R,B))). Um preenchimento por inundação binário + erosão produz bordas serrilhadas / aliased — desfoque o alpha binário (GaussianBlur(0.8)) para uma borda suave em vez de erodir. - Dimensionamento para adesivos de mensagens: corte para a bbox alpha sólida e dimensione o lado maior para exatamente o alvo (ex. 512) — não preencha para um quadrado 512² (isso deixa o sujeito pequeno com espaço vazio ao redor).
NÃO se aplica a: recortes humanos para sobreposições de vídeo (u2net está correto lá); arte sem contorno recortado; sujeitos em um fundo não uniforme / ocupado (preenchimento por inundação precisa de uma cor chave plana).
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, alpha é 255 − máscara em vez de máscara. O recorte é o sujeito com um fundo transparente; a placa é o entorno original com um buraco transparente onde o sujeito estava.
| Arquivo | Alpha é… | Use para |
|---|---|---|
-o sujeito.webm | A máscara — sujeito opaco, fundo transparente | Camada de primeiro plano, coloque no topo |
--background-output fundo.webm | Inverso — entorno opaco, região do sujeito transparente | Camada inferior; 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 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 com furo, não uma placa limpa inpainted. A região do sujeito em fundo.webm é totalmente transparente — componha algo opaco sob ela 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 (a razão de existir deste comando) | Furo (--background-output) |
| Sujeito em 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 inpaintador (LaMa, ProPainter, E2FGVI). Não este comando. |
| Substituir o sujeito por um sujeito diferente | Placa limpa — mesma que acima |
Se um usuário pedir por "a sala com a pessoa removida" e pretender exibi-la sozinha, não recorra a --background-output. Diga a eles que precisam de um inpaintador.
Composição em camadas típica (o caso de uso canônico de furo):
<!-- z=1 a placa com alpha inverso preenche tudo exceto a região do sujeito -->
<video
src="fundo.webm"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<!-- z=2 gráficos/texto ficam entre as duas camadas -->
<h1 id="headline" style="z-index:2; ...">FAÇA EM HYPERFRAMES</h1>
<!-- z=3 o recorte flutua 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 permitir que o usuário coloque 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 encaixa em uma composição como qualquer outro vídeo com autoplay mudo — 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 solta |
balanced | 18 | Padrão. Visualmente idêntico para a maioria dos usos |
best | 12 | Master / entrega final. Arquivo maior, correspondência mais precisa |
Padrões de Composição — escolha o certo
O webm recortado é uma cópia re-codificada do RGB da fonte mp4. 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 na borda. É para isso que remove-background foi construído. |
| Recorte sobre seu próprio mp4 de origem (texto-atrás-do-sujeito) | Mesmo mp4 de onde o recorte foi gerado | Duas fontes RGB para a mesma pessoa. Na --quality balanced padrão (crf 18) a duplicação é quase imperceptível; na --quality fast (crf 30) você verá uma leve mudança de cor / halo na borda. Considere --quality best (crf 12) para correspondência quase perfeita. |
Para o padrão texto-atrás-do-sujeito sem duplicação, use a separação de camadas (--background-output, descrito acima) — a placa substitui o mp4 de origem, então não há duas cópias do sujeito.
Sobreposição de legenda (overlay-caption)
Adicione uma barra de legenda sobre um vídeo recortado. O desenho acontece no espaço do canvas: --width e --height devem corresponder às dimensões do vídeo de saída. Usa ffmpeg com o filtro subtitles.
npx hyperframes overlay-caption \
-i sem_legenda.mp4 \
-o legendado.mp4 \
--srt legendas.srt \
--width 1200 \
--height 1200
Formato
O SRT de entrada deve seguir o formato de legendas SubRip. A saída é um arquivo de vídeo único com as legendas queimadas no quadro (não separadas).