Communitygithub.com

paper-explainer

Cria vídeos explicativos animados verticais (9:16) no estilo 'recorte de papel', com narração em qualquer idioma, legendas em inglês em papel rasgado, adereços planos, fundos de meio-tom e efeito visual granulado — usando um pipeline multiagente planejado (agente de pesquisa/roteiro → locução → 3 agentes de cena paralelos → revisão → renderização → publicação). Use quando solicitado para criar um vídeo explicativo, 'faça um vídeo como este Short', um reel de 'como X foi construído / por que X deu errado / como X aconteceu', ou mais episódios desta série.

O que é paper-explainer?

Este é um sistema multiagente para criar vídeos explicativos verticais (1080×1920, 9:16) no estilo 'recorte de papel'. Ele é ideal para desenvolvedores que desejam gerar vídeos explicativos animados com narração, música de fundo com redução de volume durante a fala, e efeitos visuais consistentes. O pipeline planejado inclui: (1) um agente de pesquisa e roteiro que verifica fatos na web e produz um roteiro com 14-17 falas curtas, tabela de legendas e referências; (2) geração de locução (preferencialmente ElevenLabs, com fallback gratuito via edge-tts); (3) três agentes de cena paralelos que criam arquivos JavaScript independentes para animações baseadas em HTML/SVG, usando um mini motor de renderização; (4) revisão manual via folhas de contato; (5) renderização, mixagem de áudio e publicação. Cada agente de cena recebe seu trecho exato do timeline, as falas com timestamps, um storyboard e os assets compartilhados. O sistema suporta múltiplos idiomas para narração, embora as legendas visuais em papel rasgado sejam em inglês. Plataformas suportadas: qualquer ambiente com Python, Playwright (Chrome headless), ffmpeg e Node.js. O código das cenas é gerado como JavaScript puro, garantindo determinismo e consistência visual.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sknitd/paper-explainer-skill/tree/HEAD/skills/paper-explainer

Perguntar na sua IA favorita

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

Documentação

Vídeos explicativos 'recorte de papel' (multiagente)

Saída: 1080×1920, 24 fps, 60–95 s MP4 com narração, música com redução de volume e efeitos sonoros sincronizados.

Visual: adereços SVG planos com contorno branco de 'adesivo' + sombra projetada, fundos de meio-tom ou explosão solar, legendas em inglês EM CAIXA ALTA em papel rasgado (Bebas Neue), leve separação RGB + granulação de filme + vinheta.

Tudo é renderizado a partir de HTML/SVG pelo Chrome headless quadro a quadro (determinístico), então as cenas são arquivos JS puros escritos por agentes contra um pequeno motor (template/engine.js, documentado em template/ENGINE.md).

Requisitos

  • Ambiente virtual Python 3 com: playwright (usa Chrome do sistema via CHROME_PATH, ou playwright install chromium), numpy, opencv-python-headless (opcional), faster-whisper (temporização/QA), edge-tts (locução gratuita de fallback).
  • ffmpeg, curl, bc. Opcional: conector MCP ElevenLabs para o narrador + música.

Pipeline (siga em ordem)

1. Agente de pesquisa + roteiro (segundo plano)

Crie UM agente de propósito geral com o prompt em references/agent_prompts.md#research. Ele deve verificar cada fato na web, atribuir alegações, sinalizar boatos e retornar: ROTEIRO (14–17 falas curtas, ~950–1.150 caracteres, números escritos por extenso, nomes no roteiro de narração), TABELA (tags de legenda / ideia visual / fundo por linha), FATOS com URLs, INCERTO/NÃO USADO. Para tópicos muito recentes, informe a data de hoje e peça para primeiro confirmar a que o tópico realmente se refere. Enquanto ele executa: scripts/new_project.sh <dir> e desenhe quaisquer adereços compartilhados que a história precisar (um design consistente por objeto/pessoa recorrente) no final de <dir>/engine.js; renderize um quadro de teste para verificá-los.

2. Locução

  • Preferido: ElevenLabs eleven_v4, um narrador documental (ex.: Hindi "Natraj – Apresentador de Documentários Informativos"), 2 tomadas, roteiro com tags [curioso]/[dramático]/[reflexivo] com moderação. Verifique créditos primeiro.
  • Alternativa (gratuita, fornece temporizações exatas por linha): coloque as linhas simples em <dir>/script.txt, execute scripts/edge_tts_lines.sh <dir> hi-IN-MadhurNeural +20% → vo.wav + lines.txt.
  • QA em cada tomada: Modelos TTS podem distorcer números/datas. Transcreva com scripts/words.py; o próprio Whisper formata incorretamente números em Hindi, então re-verifique anos suspeitos com dígitos suprimidos (veja references/qa.md). Escolha a tomada que diz todos os números corretamente.
  • Temporizações de linha para um arquivo de tomada única: detecção de silêncio (ffmpeg -af silencedetect=n=-38dB:d=0.15) + temporizações de palavras; scripts/align_lines.py fornece uma primeira estimativa. Escreva lines.txt (lNN inicio= fim= | texto) com o deslocamento de vídeo que você usará (ex.: +0,25 s) e um words.txt deslocado.

3. Três agentes de cena em paralelo (segundo plano)

Divida a linha do tempo nas quebras de linha em partes de ~25–30 s. Crie três agentes de propósito geral em UMA mensagem usando references/agent_prompts.md#scene — cada um possui apenas scenes_N.js, recebe seu intervalo de tempo exato, suas falas de narração com horários de início/término, batidas de palavras-chave, um storyboard (da TABELA), os assets compartilhados e as regras: IIFE + prefixos pN_, as cenas cobrem o intervalo exatamente, tag superior ~0,1 s após um corte, algo novo a cada ~1 s, renderize quadros de teste e OLHE para eles, exclua os PNGs.

4. Integre + revise (você)

  • Renderize ~30 quadros uniformemente espaçados em uma folha de contato (render_html.py ... 999 t1,t2,... em seguida ffmpeg -pattern_type glob -i 'test_*.png' -vf scale=170:-1,tile=11x3) e Leia.
  • Corrija: números/alegações inventados na tela (agentes às vezes os adicionam — remova), mapas/fronteiras imprecisos, logotipos, caricaturas de pessoas reais, sobreposições, texto fora da tela, quadros vazios.

5. Renderize, misture, publique

scripts/render_video.sh <dir> <duração> <narração> <música> <vo_atraso_ms> <saida.mp4> renderiza todos os quadros, constrói a trilha de efeitos sonoros a partir de eventos do motor, reduz o volume da música sob a voz (~-14 LUFS), e multiplexa. Para re-dublar um vídeo existente sem reconstruir as cenas, renderize com WARP=anchors.json (mapeia novos inícios de linha → inícios de linha antigos; veja references/qa.md). Entregue pelo canal preferido do usuário.

Regras de conteúdo (sempre)

  • Fatos apenas da lista com fontes do agente de pesquisa; números de dinheiro/bilheteria/votação rotulados como "RELATADO"/com fonte; contagens incertas mostradas como valores mínimos ("250+").
  • Pessoas reais: busto A.fig genérico + tag de nome em inglês, nunca caricatura; nenhuma divindade religiosa desenhada — use motivos abstratos; sem logotipos de marcas/partidos (desenhe emblemas/pássaros/letras genéricos).
  • Mapas: evite mapas de contorno de países com fronteiras contestadas/sensíveis; use quadros sem bordas ou grades de blocos, e rotule visuais ilustrativos como tal.
  • Política: neutro, atribuído, sem zombaria ou previsões.

Arquivos

  • template/ — index.html, engine.js (motor + pacotes de assets), ENGINE.md (API para agentes), scenes_1..3.js
  • examples/ — código de cena de quatro vídeos finalizados (Efeito Streisand, Estátua da Liberdade, selo azul do Twitter, eleições de meio de mandato dos EUA em 2026): a referência de qualidade/ritmo para agentes
  • scripts/ — renderização, SFX, alinhamento, transcrição, TTS gratuito, inicialização de projeto, mixagem final
  • references/agent_prompts.md, references/qa.md

Habilidades Relacionadas