Communitygithub.com

shinyobjectz/reactable

Pré-processamento de mídia para composições HyperFrames — narração text-to-speech (Kokoro), transcrição de áudio/vídeo (Whisper) e remoção de fundo para sobreposições transparentes (u2net).

O que é reactable?

Este skill fornece três comandos de CLI para pré-processamento de ativos de mídia antes de compor em projetos HyperFrames: `tts` (narração), `transcribe` (timestamps palavra-por-palavra) e `remove-background` (vídeo transparente). Cada comando baixa seu próprio modelo de ML na primeira execução e o armazena em cache em `~/.cache/hyperframes/`, sem necessidade de chave de API. O comando `tts` gera áudio de fala localmente usando Kokoro-82M com suporte multilíngue (detecção automática de idioma pelo prefixo do ID de voz), e o `transcribe` produz um `transcript.json` normalizado a partir de áudio, vídeo ou legendas existentes usando Whisper (com regras críticas sobre modelos `.en` para evitar tradução indesejada). O `remove-background` usa u2net_human_seg para recortar pessoas de vídeos ou imagens, gerando camadas transparentes (VP9 alpha WebM ou ProRes 4444 MOV) e suporta separação de camadas para colocar texto/gráficos entre o sujeito e o fundo. Projetado para desenvolvedores que precisam de uma pipeline de pré-processamento local, confiável e transparente para narrações, legendas e efeitos de sobreposição em composições baseadas em navegador.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/shinyobjectz/reactable/tree/HEAD/skill/vendored/hyperframes-media

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Prévia

Do README da skill

Documentação

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údoVozPor que
Demonstração de produtoaf_heart/af_novaCaloroso, profissional
Tutorial / instrucionalam_adam/bf_emmaNeutro, fácil de seguir
Marketing / promoçãoaf_sky/am_michaelEnérgico ou autoritário
Documentaçãobf_emma/bm_georgeInglês britânico claro, formal
Casual / socialaf_heart/af_skyAcessí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, acessibilidade
  • 1.0 — ritmo natural (padrão)
  • 1.1-1.2 — intros, transições, conteúdo animado
  • 1.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.

  1. Idioma conhecido e não-inglês → --model small --language <código> (sem sufixo .en)
  2. Idioma conhecido e inglês → --model small.en
  3. Idioma desconhecido → --model small (sem .en, sem --language) — whisper detecta automaticamente

O modelo padrão é small, não small.en.

Tamanhos de Modelo

ModeloTamanhoVelocidadeQuando usar
tiny75 MBMais rápidoPré-visualizações rápidas, teste de pipeline
base142 MBRápidoClipes curtos, áudio limpo
small466 MBModeradoPadrão — a maioria dos conteúdos
medium1,5 GBLentoConteúdo importante, áudio ruidoso, música
large-v33,1 GBMais lentoQualidade 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.

ArquivoAlfa é…Use para
-o sujeito.webmA máscara — sujeito opaco, fundo transparenteCamada de primeiro plano, coloque em cima
--background-output placa.webmInverso — arredores opacos, região do sujeito transparenteCamada 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 usoFerramenta 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 relacionadaApenas sujeito.webm; ignore a placa
Mostrar a sala sem a pessoa, sozinha sobre nenhum outro conteúdoPlaca limpa — precisa de um inpaint (LaMa, ProPainter, E2FGVI). Não é este comando.
Substituir o sujeito por um sujeito diferentePlaca 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

FormatoQuando
.webm (VP9 + alpha)Padrão. Composições reproduzem isso diretamente via <video>.
.mov (ProRes 4444)Edição no DaVinci/Premiere/FCP. Arquivos grandes.
.pngRecorte 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çãoCRFQuando
fast30Iterando, arquivo menor, correspondência de cor mais frouxa
balanced18Padrão. Visualmente idêntico para a maioria dos usos
best12Master / 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ãoO que está atrás do recorteResultado
Recorte sobre uma cena diferente (mais comum)Imagem estática, gradiente ou vídeo não relacionadoFica ó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 geradoDuas 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 pessoaFilmagem do mesmo sujeitoParecerá 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:

  1. 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 com data-start/data-duration), então animar a opacidade do vídeo diretamente é silenciosamente sobrescrito. O invólucro não tem atributos data-*, então é controlado pelo seu CSS/GSAP.
  2. Ambos os vídeos usam data-start="0" e data-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

Habilidades Relacionadas