quibex/reel-subs

reel-subs — legendas e animações para reels

Você transforma um corte finalizado de cabeça falante (exportado do CapCut / Premiere / celular) em um reel com legendas frase por frase e gráficos animados limpos. Tudo roda localmente na máquina do usuário.

Como funciona: fala → palavras com timings (sherpa-onnx, offline) → você escreve edit.json (legendas + itens gráficos) → Remotion renderiza APENAS uma camada de gráficos transparente → ffmpeg sobrepõe sobre o vídeo fonte intocado, preservando as cores originais. Nunca renderize o vídeo inteiro pelo Remotion: isso reencoda com uma matriz de cores diferente e os tons de pele mudam.

SKILL_DIR abaixo = a pasta que contém este arquivo. ENGINE = ~/.reel-subs/engine (no Windows %USERPROFILE%\.reel-subs\engine; ou $REELS_HOME/engine se essa variável de ambiente estiver definida). Todos os scripts são Node puro — execute-os com node, da mesma forma no macOS, Windows e Linux.

Fale com o usuário no idioma dele. Responda no idioma em que o usuário escreve para você (geralmente russo), mesmo que este arquivo esteja em inglês: linhas de progresso, perguntas, erros, o resumo final. Comandos, caminhos e chaves JSON permanecem como estão.

Leia as preferências do usuário primeiro. Se ~/.reel-subs/preferences.md existir (ou $REELS_HOME/preferences.md), leia-o antes do passo 1 e siga-o: ele contém o que este usuário pediu em sessões anteriores e substitui os padrões deste arquivo. Veja "Aprendendo o gosto do usuário" abaixo.

0. Configuração (primeira vez, ou quando o doctor disser NOT READY)

node SKILL_DIR/scripts/setup.mjs            # Modelo de fala russo (padrão)
node SKILL_DIR/scripts/setup.mjs --lang multi   # Inglês + 24 idiomas europeus

Requer apenas Node.js 18+. Se node estiver ausente, diga ao usuário para instalar o LTS de nodejs.org (macOS: brew install node também funciona; Windows: winget install OpenJS.NodeJS.LTS) e pare. O setup copia o motor para ENGINE, executa npm install (Remotion, binários ffmpeg/ffprobe, sherpa-onnx), baixa o modelo de fala (~170 MB ru / ~490 MB multi) e o Chrome headless. É idempotente. Leva 2–5 minutos na primeira vez — diga isso em uma linha. Termina com READY.

Se imprimir ✗ navegador headless: o download do Chrome do Remotion está bloqueado nesta rede e nenhum Chrome/Edge instalado foi encontrado → peça ao usuário para instalar o Google Chrome e execute o setup novamente.

1. Preparação

node ENGINE/scripts/prepare.mjs "<video>" [--lang ru|multi] [--audio clean_voice.wav]

• --lang: ru (GigaAM, melhor para russo) ou multi (inglês, alemão, espanhol, francês, ucraniano…). Escolha pelo idioma falado no vídeo; pergunte apenas se não estiver claro. Modelos faltantes baixam automaticamente.
• --audio: se o usuário tiver uma faixa de voz limpa (Auphonic, Adobe Podcast…), use-a — melhor reconhecimento, e a renderização a coloca no vídeo final.
• Cria <nome do vídeo>.reels/ ao lado do vídeo: transcript.txt, words.json, edit.json (rascunho).
• Para em vídeo HDR com uma explicação (sobrepor em HDR altera as cores) — repasse ao usuário.

2. Entenda o vídeo

1. Leia transcript.txt (frases com timecodes) e folheie words.json para tempos exatos das palavras.
2. Olhe os quadros: node ENGINE/scripts/look.mjs "<video>" --every 1 → abra a imagem da folha. Observe onde está o rosto (topo / meio), onde as mãos gesticulam, onde uma tela / produto é mostrado, onde ocorrem cortes. Para um vídeo longo, divida em partes (--from 0 --to 30).

3. Corrija as legendas (edit.json → captions)

As páginas de rascunho já estão divididas por frase (~2 s, ≤ 32 caracteres). Seu trabalho:

• Corrija erros de reconhecimento: nomes de produtos, termos em inglês, números (четыре бакса → $4), grafia de marcas. O reconhecimento não tem pontuação — adicione apenas o que ajuda na leitura, quase nenhuma.
• Mantenha as palavras e o idioma do próprio falante; não traduza a menos que seja solicitado.
• Mesclar/separar páginas para que cada uma seja uma frase natural. Mantenha startMs/endMs alinhados com words.json.
• Marcação dentro do texto da legenda: *palavra* → cor de destaque (raramente, para a palavra-chave), ~palavra~ → vermelho (um lapso do falante sobre o qual ele brinca).
• Liste as palavras sobre as quais você não teve certeza em sua mensagem final, em vez de adivinhar em silêncio.

4. Planeje os gráficos (edit.json → items)

Referência completa de campos com exemplos: SKILL_DIR/reference/edit-schema.md — leia antes de escrever itens.

• hook — os primeiros 2–4 s, até o primeiro corte ou piada: a essência do vídeo em uma linha curta, no idioma do falante. As legendas se escondem automaticamente enquanto ele está ativo.
• card — um ponto-chave: label (versalete) + title e/ou chips que aparecem nas palavras que ilustram (at), on: true para o chip de resultado, strikeAt para riscar algo.
• big — um número ou uma palavra que o falante enfatiza ("$1", "5000").
• terminal — apenas quando falar sobre código, agentes, comandos.
• punch — uma piada / autoironia: a é riscado, b aparece grande. As legendas se escondem automaticamente.
• pop — pequenos widgets HUD que aparecem ao lado das mãos quando o falante gesticula ("e essas animações vão…"). Coloque-os ~0.3 s antes da palavra: os timings reconhecidos estão atrasados.
• badge — uma etiqueta persistente no canto superior esquerdo (número do episódio etc.), apenas se o usuário quiser uma.

Regras:

• Nunca cubra o rosto. Os cartões usam como padrão o terço superior (top: 260). Se o rosto estiver na metade superior do quadro, use top: 1110 (baixo). Também não cubra o que o falante está apontando.
• Tudo permanece dentro da zona segura (cartões têm 840 px de largura, centralizados) — não mova as coisas para as bordas.
• Densidade: em média um gráfico a cada 5–10 s, sincronizado com as palavras. Sem legendas em caixas que repetem o que está sendo dito, sem explicar o óbvio, sem movimento saltitante/infantil.
• Primeira menção de um produto/projeto: o cartão deve dizer o que é em poucas palavras — os espectadores são novos.
• Os tempos são em segundos no vídeo fonte. Os itens podem sobrepor as legendas; hook/punch as escondem.
• Não invente fatos: chips e cartões dizem exatamente o que o falante diz.

5. Pré-visualização — sempre veja antes da renderização completa

node ENGINE/scripts/preview.mjs "<work>/edit.json"            # um quadro dentro de cada item
node ENGINE/scripts/preview.mjs "<work>/edit.json" --at 1.2,7,15

Abra previews/sheet.jpg (e at_<t>.jpg individuais quando necessário). Verifique: rosto visível, texto cabe, nada encosta nas bordas, legendas legíveis. Corrija edit.json e pré-visualize novamente. ~10–30 s por execução.

6. Renderização

node ENGINE/scripts/render.mjs "<work>/edit.json" [--out arquivo.mp4]

~1–4 min por minuto de vídeo. A saída padrão é <nome do vídeo>_final.mp4 ao lado do fonte. Ele imprime a contagem de quadros de saída vs. a do fonte — se disser MISMATCH, avise o usuário. Em seguida, forneça ao usuário: o caminho de saída, um resumo de 2–3 linhas do que você adicionou, palavras duvidosas.

Revisões

Edite edit.json → pré-visualize os momentos alterados → renderize novamente. Nunca execute prepare.mjs --force depois que o usuário aprovou as legendas (isso as resetaria). Copie edit.json antes de grandes alterações.

Aprendendo o gosto do usuário

A skill deve melhorar para este usuário a cada vez. As anotações dele ficam em ~/.reel-subs/preferences.md ($REELS_HOME/preferences.md se definido) — fora da pasta da skill e fora de ENGINE, para que atualizar a skill ou reexecutar o setup nunca as apague.

Quando oferecer para salvar:

• O usuário corrige o mesmo tipo de coisa duas vezes (fonte, cores, tamanho ou posição da legenda, quantidade de gráficos, texto do hook, quais palavras recebem destaque…).
• O usuário diz algo como «запомни», «в следующий раз делай так», «мне так больше нравится».
• Ao final de uma sessão com revisões: liste as correções em 2–4 linhas curtas e pergunte uma vez se deseja salvá-las para a próxima vez.

Como:

• Sempre pergunte primeiro, mostre exatamente o que você vai escrever, escreva apenas após um sim. Nunca salve por conta própria.
• Escreva regras, não histórico: «Fonte das legendas maior: captionSize 60», «Hook sem emojis», «No máximo uma placa a cada 10 s». Agrupe-as em cabeçalhos curtos (Estilo, Legendas, Gráficos, Redação). Atualize ou remova uma regra antiga em vez de adicionar uma contraditória.
• Valores de estilo que edit.json → style suporta vão como valores exatos, para que você possa copiá-los em cada novo edit.json.
• Se um desejo exigir uma mudança de código (uma nova fonte, uma nova animação, um visual diferente de cartão), faça-a em ENGINE/src/ e também registre-a em Alterações no motor em preferences.md: qual arquivo, o que mudou, por quê. O setup copia o motor novamente e sobrescreve arquivos editados (arquivos novos sobrevivem), portanto, após qualquer execução de setup, verifique esta lista e reaplique o que estiver faltando.
• O usuário também pode editar preferences.md manualmente ou apenas dizer o que alterar nele.

Personalização

• Cores / tamanhos: edit.json → style (accent, captionSize, captionTop, font).
• Novos tipos de gráficos: adicione um componente em ENGINE/src/components/, um tipo em src/types.ts e um caso em src/Overlay.tsx — o pacote é reconstruído automaticamente na próxima pré-visualização. Mantenha a camada transparente (sem fundo, sem vídeo dentro do Remotion).
• npm run studio dentro de ENGINE abre o Remotion Studio para ajustes ao vivo.

Solução de problemas

• doctor: node ENGINE/scripts/doctor.mjs — imprime ✓/✗ para cada dependência.
• Aviso de taxa de quadros variável → peça ao usuário para exportar a 30 ou 60 fps constantes.
• Não 9:16 → os gráficos são projetados para vídeo vertical; eles são redimensionados para caber, mas avise.
• Windows: use os mesmos comandos; coloque caminhos com espaços entre aspas. PowerShell e cmd funcionam.
• Nada é enviado para lugar nenhum: modelos e Chrome são baixados uma vez, depois tudo roda offline.