Communitygithub.com

chrislitality-svg/script-to-video

Transforme qualquer documento (relatório de engenharia, paper, manual, conteúdo científico) em um vídeo vertical 3:4 de科普/divulgação (1080×1440, 60–150 segundos). Renderização puramente por código: timeline determinística em HTML único → captura de quadros com Playwright → codificação com ffmpeg. Sem software de edição, sem API de vídeo AI, totalmente offline, baixo custo e reproduzível quadro a quadro.

O que é script-to-video?

Este skill (chrislitality-svg/script-to-video) automatiza a produção de vídeos verticais curtos (3:4, 1080×1440, 60–150s) a partir de qualquer texto, como relatórios, artigos ou manuais. Ele é ideal para transformar conteúdo existente em vídeos de divulgação científica ou storytelling de dados, eliminando a necessidade de softwares de edição ou APIs de geração de vídeo baseadas em IA. O processo é 100% local, reproduzível e auditável. Funciona através de um pipeline de nove etapas: desde a extração de fatos do texto fonte, roteirização e dublagem (com TTS gratuito), até a sincronização da linha do tempo, animação em HTML puro (com funções determinísticas), renderização quadro a quadro com Playwright, mixagem de áudio e codificação final com ffmpeg. A qualidade é garantida por auditorias automáticas (sem sobreposição ou vazamento de texto) e verificações visuais de pontos-chave. O skill é suportado por ferramentas como Claude Code, Cursor, Codex e qualquer LLM com capacidade de programação, e inclui verificações finais rigorosas (7 itens) antes da entrega do vídeo final, legendas SRT e texto de publicação.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add chrislitality-svg/script-to-video

Perguntar na sua IA favorita

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

Documentação

script-to-video · Texto → Vídeo Curto Vertical de Divulgação Científica

Três princípios fundamentais, todas as decisões retornam a eles:

  1. Linha do tempo determinística: A animação é uma função pura setTime(t) — no mesmo instante, renderiza sempre a mesma cena. Isso permite auditoria de quadros arbitrários, captura paralela em segmentos, demonstração cíclica e alteração da velocidade total com uma única constante.
  2. Linha do tempo definida pela duração real da dublagem: Primeiro duble, meça a duração de cada frase, depois organize os limites das cenas — o áudio e o vídeo ficam naturalmente sincronizados, sem necessidade de alinhamento por ASR.
  3. Os olhos do usuário não devem ser a primeira inspeção de qualidade: A auditoria programática (sem estouro de texto/sobreposição) deve ser zero antes da captura; a inspeção visual de quadros-chave é a última etapa de refinamento estético.

Fluxo (Nove etapas, qualquer uma não aprovada volta para a etapa anterior)

Texto ─▶ ① Constituição de dados ─▶ ② Roteiro + divisão de legendas ─▶ ③ Dublagem (duração real)
     ─▶ ④ Sincronização da timeline ─▶ ⑤ Animação anim.html ─▶ ⑥ Auditoria dupla zerada + inspeção visual de quadros-chave
     ─▶ ⑦ Música + mixagem + masterização ─▶ ⑧ Captura quadro a quadro → codificação → composição ─▶ ⑨ Sete verificações → entrega

① Constituição de dados

Leia o texto completo e consolide todos os números, fatos e nomes que entrarão no vídeo em uma lista única (escreva em shots/facts.md). A partir daí, qualquer cena, roteiro ou legenda pode apenas referenciar esta lista, proibida a improvisação.

  • Números verificáveis devem ser destacados; detalhes não verificáveis devem ser omitidos (melhor menos informação do que informação falsa).
  • Cada número é mencionado apenas uma vez, no pico emocional.
  • Os números devem aparecer com um "evento": desenho crescendo, contagem sincronizada, queda.

② Roteiro e divisão de legendas

Escreva o roteiro para locução (shots/vo_lines.json): uma frase por linha, cada uma com 4–12 segundos, total de 8–16 frases.

  • Os primeiros 5 segundos decidem a retenção: escolha entre dinheiro/conflito/suspense e coloque na primeira frase (ex.: "Se te dessem X para construir uma estrada — você aceitaria?").
  • Estrutura de referência: Gancho → Problema → Negação → Solução → Verificação → Resolução → Personagem → Fechamento (pode ser adaptada).
  • Para cada frase, especifique manualmente a divisão das legendas ("cues": [...], cada bloco ≤18 caracteres), mais estável do que cortar mecanicamente por pontuação.

③ Dublagem

python templates/vo_tts.py (padrão: edge-tts, gratuito; com GPU local pode trocar para modelo de clonagem de voz, veja references/audio.md). Cada frase gera um arquivo wav + duração real em audio/vo/vo_dur.json.

  • Números ordinais em chinês devem ser escritos por extenso (2022 → 二零二二); ponto decimal vira "点".
  • TTS ocasionalmente pode retornar vazio: o script deve tentar novamente + permitir retomada.

④ Sincronização da timeline

python templates/sync.py: Duração da cena = 0,25s de avanço + duração da frase + respiro final (0,5–1,9s). Escreve automaticamente a TL (timeline) e CUES (legendas) de volta no anim.html, e gera shots/timeline.json para mixagem. Após trocar a dublagem, deve executar novamente, e escalar proporcionalmente os momentos de ação alinhados com a locução dentro das cenas.

⑤ Animação

Copie templates/anim.html e modifique as cenas. O esqueleto já contém: sistema de design estilo blueprint, funções utilitárias, auditoria, transição com scanline, camada de legendas, 3 exemplos de cenas. Modo central:

  • Cada cena defscene(id, cam=>{...; return (t,d)=>{...}}), render é uma função pura.
  • Dois níveis de movimento: ação principal (desenhar linha/cair) + camada contínua (linha pontilhada/flutuar/pulso).
  • A câmera sempre tem um zoom lento de 1,4%–3% — a cena não é estática.
  • "Primeiro sair, depois entrar": elementos antigos saem completamente da tela antes de novos entrarem, evitando sobreposição.
  • Especificações visuais e linguagem de movimento: leia references/design-system.md e references/motion.md.

⑥ Auditoria + Inspeção visual (portão de qualidade, não pode ser pulado)

No navegador, execute auditText() (estouro de texto) e auditOverlap() (sobreposição de elementos). Devem estar zerados para iniciar a captura. O auditor não captura "feiura": para cada cena, capture um quadro no pico de conteúdo para inspeção visual (texto cortado/composição vazia/desvio de cor/forma). Corrija imediatamente. Para sobreposições intencionais por design, adicione data-okov="1" ao elemento.

⑦ Som

python templates/music.py gera música de fundo leve (sem direitos autorais); ou use faixas próprias (cuidado com direitos). python templates/mix.py: Normaliza VO por RMS → ducking na música (abaixa perto da fala) → efeitos sonoros apenas nos acentos (≤2 thuds por cena, sem whoosh de fundo — efeitos sonoros são pontuação, não fundo) → limitador de envelope de pico próprio → ffmpeg loudnorm duas passagens para -14 LUFS / TP -1,5.

⑧ Renderização

python templates/shoot.py 0 <dur> a --html anim.html   # ×N segmentos em paralelo
python templates/render.py                              # codificação → verificação do último quadro → concatenação → composição

Captura quadro a quadro com Playwright (device_scale_factor=2, JPEG q93) → codificação por segmentos x264 crf19 → verificação de cada último quadro vs. imagem fonte (RMS<8, captura segmentos ruins sem erro) → concat → composição áudio-vídeo (pan explicitamente para estéreo, +faststart).

⑨ Sete verificações

python templates/check.py: Loop sem emendas (RMS entre primeiro e último quadro <5) · Trilha de áudio existe · Legibilidade das legendas · Ordem das cores do estilo (por quadro, B>G>R para prevenir desvio) · Quadros em branco · Tamanho/duração · faststart. Todos PASS para entrega. Entregáveis: vídeo final mp4 + legendas srt + texto de publicação (título ≤15 caracteres/descrição de uma linha/tags).

Ambiente

python 3.10+, pip install playwright numpy soundfile pillow edge-tts
playwright install chromium
ffmpeg (disponível no PATH)

Estrutura de diretório (para cada projeto)

<project>/
├── shots/vo_lines.json    # Roteiro + divisão de legendas (única fonte de conteúdo)
├── shots/facts.md         # Constituição de dados
├── shots/timeline.json    # Gerado por sync.py, para mixagem
├── tools/web/anim.html    # Animação (cópia modificada de templates/anim.html)
├── audio/vo|music|mix/    # Som
└── out/                   # Quadros, segmentos, vídeo final

Linhas Vermelhas

  • Não invente: dados, nomes, eventos devem ter fonte; [a verificar] não pode ser zerado antes da dublagem.
  • Vermelho expressa apenas semântica de "julgamento" (aprovação/reprovação), nunca usado como decoração.
  • Ao usar música externa, confirme a autorização; padrão é usar música gerada programaticamente.
  • Para nomes/empresas reais e números de domínio, verifique item por item com a constituição de dados antes da entrega.

Referências

ArquivoConteúdo
references/design-system.mdSistema visual: disciplina de cores, três níveis de fonte, legendas, gramática de desenho
references/motion.mdLista de linguagem de movimento: quando usar qual efeito, parâmetros
references/audio.mdPipeline de áudio: seleção de TTS, fórmulas de mixagem, alvo de masterização
references/pitfalls.mdLista de armadilhas (ordenadas por custo; consulte primeiro em caso de problemas)
templates/Esqueleto executável e scripts de pipeline

Habilidades Relacionadas