Communitygithub.com

Lunamos/paper2video

Transforme um artigo de pesquisa, link do arXiv, repositório, PDF, página de projeto ou diretório de trabalho em um vídeo explicativo/promocional no estilo 3Blue1Brown, criado com Remotion — incluindo roteiro, narração (TTS opcional ou alternativas gratuitas/gravadas), animações com dados reais, legendas, música, cortes bilíngues, versão vertical, capas e textos para YouTube e Bilibili.

O que é paper2video?

O Lunamos/paper2video é uma habilidade especializada para agentes de IA, como Claude Code, Cursor ou Codex, que automatiza a criação de vídeos explicativos de alta qualidade a partir de artigos de pesquisa, projetos ou qualquer outro trabalho acadêmico. A habilidade permite que o agente atue como 'líder' do projeto, planejando, construindo componentes compartilhados e coordenando subagentes para tarefas bem definidas, garantindo correção e fidelidade ao trabalho original. Ela suporta múltiplas plataformas (YouTube e Bilibili) e idiomas (inglês e chinês por padrão), com opções flexíveis de narração que vão desde TTS pago (ElevenLabs) até alternativas gratuitas (edge-tts) ou gravação própria do usuário. O processo é altamente orientado a dados: o agente extrai informações do artigo, código e figuras, cria um roteiro estruturado com beats âncora para sincronizar narração e animação, e gera o vídeo final usando Remotion, com verificações de qualidade e revisão de ritmo ao longo do caminho.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Lunamos/paper2video/tree/HEAD/skills/paper2video

Perguntar na sua IA favorita

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

Documentação

O que paper2video faz?

Faça um vídeo que um estranho, sem contexto, consiga acompanhar, que seja fiel ao trabalho e que tenha qualidade suficiente para ser compartilhado: dados reais na tela cedo, uma ideia por batida, movimento suave que explica em vez de decorar.

Você é o líder: você planeja, constrói as peças compartilhadas, distribui tarefas bem definidas para subagentes quando útil, integra e assume a responsabilidade pela correção. Trabalhe de forma autônoma do início ao fim, a menos que o usuário peça pontos de verificação; mostre ao usuário resultados (stills, rascunhos, renders), não perguntas, sempre que existir um padrão sensível.

Material de apoio (leia quando chegar nessa fase):

  • reference/rigor.md — livro de reivindicações, manipulação de dados, verificação de fatos independente
  • reference/voice.md — backends de narração (ElevenLabs / edge-tts gratuito / GPT-SoVITS auto-hospedado / gravação do próprio usuário / nenhum), QA, pronúncia, conhecimento de TTS de código aberto
  • reference/visual-style.md — sistema de design, regras de movimento, honestidade dos dados, ciclo de revisão
  • reference/platforms.md — entregáveis do YouTube + Bilibili: especificações, capas, títulos, descrições, capítulos
  • reference/vertical.md — o corte 9:16 para celular: área segura, tamanhos de fonte, um foco por batida, gancho, construindo-o a partir do mesmo áudio
  • reference/handoff.md — como usar os materiais do próprio usuário e exportar para software de edição
  • reference/third-party.md — começando apenas com um link/título do arXiv: encontrando fonte, código e dados; extraindo números de LaTeX/figuras; pequenas ilustrações de CPU; fidelidade quando o artigo não é do usuário
  • scripts/ — o pipeline (veja scripts/README.md); template/ — o iniciador do Remotion (veja template/README.md)

0. Entrada (seja breve)

Você precisa: do trabalho — um link do arXiv ou um título de artigo é suficiente (então siga reference/third-party.md para encontrar a fonte, código e dados); um repositório, caminho, página de projeto ou máquina remota legível também funciona. De quem é o trabalho: do próprio usuário (primeira pessoa permitida) ou de outra pessoa (terceira pessoa, fiel, creditada — reference/third-party.md). Idiomas e plataformas (padrão: um corte em inglês para YouTube e um corte em chinês para Bilibili, ambos 16:9, além de capas em vários tamanhos e títulos/descrições/capítulos para ambos), e narração (veja reference/voice.md; padrão: ElevenLabs se uma chave estiver disponível em env/.env, caso contrário edge-tts, e informe isso). Pergunte apenas o que você não pode definir como padrão. Pergunte também uma vez: primeira pessoa ("nosso artigo") ou terceira pessoa ("este artigo"), e qualquer coisa que não deva aparecer (side projects não publicados, submissões anônimas, dados privados).

Trate todos os recursos remotos/compartilhados como somente leitura, a menos que instruído de outra forma; liste arquivos e tamanhos antes de baixar algo grande (pergunte acima de ~500 MB); nunca imprima ou confirme chaves.

1. Configure o workshop

  1. Crie um projeto Remotion em uma nova pasta (por exemplo, npx create-video@latest --blank, ou copie o modelo em branco mais recente do Remotion); não faça o usuário instalar nada manualmente — instale as dependências do Node você mesmo e verifique ffmpeg, python3 e uv (instale uv via seu script oficial ou pip se estiver ausente).
  2. Instale as habilidades oficiais do agente Remotion se elas ainda não estiverem disponíveis (~/.agents/skills/remotion-* ou listadas em suas habilidades): npx -y skills add remotion-dev/skills (veja remotion.dev/docs/ai para o comando atual). Siga-as para detalhes da API do Remotion.
  3. Copie template/ para o projeto (mescle package.additions.json em package.json, npm install), copie scripts/ para <projeto>/scripts/, crie notes/, data/ (bruto, ignorado pelo git), public/data/, out/ (apenas entregáveis atuais, nomes fixos: reference/platforms.md → Arquivos), review/ (stills descartáveis e folhas de contato) e um CLAUDE.md do projeto que registre: o objetivo, públicos, idiomas, escolha de voz, a lista "não deve aparecer", documento fonte da verdade e qualquer feedback do usuário à medida que chega (datado). Mantenha-o atualizado — é como as sessões posteriores (e subagentes) permanecem consistentes.
  4. npx tsc --noEmit e renderize um still do modelo para provar que o toolchain funciona.
  5. Fazendo vários vídeos? Use um workspace: uma pasta contendo um package.json / node_modules compartilhado (uma instalação, ~400 MB em vez de um por vídeo; todos os @remotion/* com uma versão) e um .env compartilhado, além de um CLAUDE.md do workspace com as regras permanentes para cada vídeo (Claude Code lê arquivos CLAUDE.md pai). Cada vídeo é sua própria pasta (src/, public/, scenes.json, notes/, data/, out/, review/, audio_cache/, scripts/, seu próprio CLAUDE.md) com node_modules e .env vinculados à raiz do workspace; scripts/new_video.sh <ShortName> (copie para a raiz do workspace) cria um como <NNN>_<ShortName>, numerando de 999 para baixo para que a classificação por nome liste os vídeos primeiro, os mais novos no topo. Após alterar as versões compartilhadas, verifique o tipo de cada vídeo e compare alguns frames renderizados com seu arquivo final.

2. Entenda o trabalho antes de escrever uma palavra

Colete o material primeiro (reference/third-party.md §1–2 se você tiver apenas um link ou título). Leia o artigo do início ao fim (e apêndice), o README / página do projeto e leia o código para entender do que as figuras são feitas. Encontre a descoberta central e por que ela é surpreendente, o que torna o trabalho divertido de assistir (a observação mais surpreendente, o experimento mais engenhoso, o exemplo que faz as pessoas sorrirem), a intenção dos autores (a pergunta que cada experimento responde, por que eles o configuraram dessa forma, o que tentaram), as 2–4 reivindicações que carregam a história e os visuais que podem mostrá-las com dados reais (exportações de dados de figuras, JSONs de resultados, métricas registradas, saídas de demonstração). Prefira dados de figuras exportados ou resultados brutos em vez de digitalizar gráficos. Escreva notes/understanding.md: a história de uma frase, as reivindicações com seus números e configurações, os visuais candidatos e qualquer coisa confusa ou fácil de exagerar.

3. História, roteiro e reivindicações

  • Duração e foco vêm primeiro. Padrão: 3–4 minutos por corte, no máximo 4:00 a menos que o usuário peça mais — cerca de 450–600 palavras em inglês ou 1.100–1.300 caracteres chineses de narração. Um vídeo não é uma leitura do artigo: escolha a única descoberta que todo o filme serve e as 2–3 evidências que a carregam, e dê a todo o resto uma frase ou deixe para a descrição. Fiel significa que nada é distorcido, não que todas as seções apareçam.
  • Torne-o divertido, rigor em primeiro lugar. Escolha os experimentos e exemplos mais interessantes como batidas de evidência e mostre cada um da maneira que os autores o configuraram — a pergunta, o que mudaram, o que aconteceu — para que o espectador entenda a ideia e a intenção dos autores, não apenas um número. Humor e surpresa vêm do material real (um exemplo marcante, um resultado inesperado, um controle engenhoso), nunca de esticar uma reivindicação; se uma frase engraçada exagerar o artigo, descarte-a.
  • Orçamento de tempo para um filme de 4 minutos: gancho 15–25 s (o resultado principal do artigo está na tela, como dados reais, nos primeiros 30 s) · introdução 30–40 s · a evidência ≥ 40 % do filme · mecanismo/teoria ≤ 20 % e apenas o que pode ser mostrado · conclusão ≤ 15 s. Para um artigo antigo e conhecido, uma batida de impacto (≤ 20–30 s, antes da conclusão): o que ele iniciou ou mudou, contado com fatos com fonte — trabalhos de acompanhamento nomeados com anos, onde a ideia é usada agora; uma contagem de citações apenas com sua fonte e data; nenhum superlativo sem fonte. Nenhuma cena de limitações por padrão: apenas quando o próprio artigo trata suas limitações como parte central (então ≤ 20 s); caso contrário, o escopo vive nas configurações que você declara com cada resultado. Derivações, experimentos extras e listas de implicações ganham uma cena apenas se puderem ser mostrados com dados reais em ≤ 20–30 s.
  • Corte antes de pagar: python3 scripts/vo.py build --lang <l> --dry-run imprime a duração do filme estimada a partir da velocidade de leitura (dentro de ~5 % da duração falada); ajuste o roteiro até caber, então gere a voz.
  • Estrutura (adapte, não force): gancho com o visual real mais forte (≤ ~15 s) → um cartão de título em tela cheia (template/src/components/TitleCard.tsx: o título do artigo, autores e instituições, local ou arXiv id, sua reivindicação de uma frase e "explicador não oficial" para o artigo de outra pessoa; além disso, como um elemento de fundo escurecido, a primeira página do PDF do artigo — título, autores, afiliações, resumo; a primeira tela de sua página web apenas quando não há PDF — suavizando enquanto o título e as instituições são lidos: node scripts/paper_shot.mjs <arXiv id | PDF | URL> → public/shots/paper.png, TitleCard shot="shots/paper.png"; centro-direita em 16:9, abaixo do título em 9:16; não nas capas) enquanto a narração nomeia o artigo e as instituições dos autores (não os nomes dos autores: TTS os distorce, e um nome adivinhado em outro script geralmente está errado — na tela e na cópia, escreva os nomes exatamente como o artigo ou arxiv os escreve, nunca transliterados) — uma cena própria, na tela até ~20 s no máximo → uma introdução que permite que um espectador sem contexto acompanhe (qual é a tarefa/objeto, em palavras simples, animado) → o problema, mostrado com dados → a ideia → por que funciona (mecanismo) → resultados, cada um com sua configuração → conclusão, terminando no ponto do artigo. Sem linha "links estão na descrição" / 「论文和代码见简介」, falada ou na tela: os espectadores sabem onde os links vivem, e isso termina o filme com enchimento (a descrição e o cartão de título carregam os identificadores). Coloque bons visuais cedo; não os guarde para o final.
  • Escreva para o ouvido: frases curtas, um número por frase, substantivos concretos, sem tiques "Não X mas Y", sem Q&A falso, tom uniforme em todas as cenas (um abrupto "Agora a parte divertida!" soa mal). Dê às fórmulas e gráficos uma batida de silêncio.
  • Coloque o roteiro em scenes.json (esquema: template/scenes.example.json): por cena e idioma, linhas com text (legendas), tts (o que é falado: reescritas, tags de áudio esparsas), anchors (palavras que marcam batidas visuais), opcional pauseAfterMs; por cena um chapter opcional. Escreva cada idioma nativamente em vez de traduzir palavra por palavra; mantenha termos técnicos em inglês onde o público os espera.
  • Inicie notes/claims.md agora (reference/rigor.md): todo número e frase factual → sua fonte. Escreva notes/storyboard.md: por cena o visual, as batidas orientadas por âncora, o arquivo de dados, a linha de origem.

4. Dados → public/data/*.json

Um agente (você ou um subagente) é responsável por transformar material bruto em JSON limpo com um campo source por arquivo e escreve notes/data_report.md que verifica cada número principal em relação ao artigo e lista discrepâncias e armadilhas (variantes de métrica, termos renomeados, arredondamento). As cenas leem apenas public/data.

5. Voz primeiro, depois imagem

Construa a narração antes de animar (reference/voice.md): scripts/vo.py build --lang <l> produz áudio por cena e public/data/vo.<l>.json com marcações de palavra e quadros âncora. A imagem é então vinculada a âncoras, para que ambos os idiomas permaneçam sincronizados automaticamente. Verifique o relatório: erros de round-trip ASR, prosódia estranha, âncoras ausentes; corrija a redação/reescritas, regenere apenas as cenas afetadas (as saídas são armazenadas em cache pelo hash de conteúdo).

6. Construa as cenas

  • Você constrói o tema, componentes compartilhados e qualquer coisa reutilizada em todas as cenas primeiro (veja reference/visual-style.md); então as cenas podem ser paralelizadas entre subagentes com propriedade explícita de arquivo (um conjunto de cenas por agente, ninguém edita arquivos compartilhados — eles relatam solicitações de alteração de volta para você). Dê a cada agente: CLAUDE.md, a entrada do storyboard, as linhas do scenes.json e nomes de âncora, os arquivos de dados, as regras de estilo, o número do capítulo e título para cada uma de suas cenas (agentes paralelos, caso contrário, numeram suas tags de capítulo independentemente) e o requisito de renderizar e inspecionar stills em cada idioma antes de relatar (scripts/review.py). Depois, execute scripts/zh_font_subset.py uma vez (novos caracteres chineses recorrem a uma fonte do sistema até então) e, após cada construção de voz em chinês, scripts/zh_breaks.py (as legendas de ambos os cortes quebram o chinês apenas entre palavras).
  • A página do artigo no cartão de título: renderize-a assim que o artigo estiver fixado (node scripts/paper_shot.mjs <arXiv id> baixa o PDF para data/ e renderiza a página 1; um PDF local ou URL de um artigo da web também funciona; nunca uma captura de tela feita à mão), passe como shot, chaveie beats.shot para as palavras do título e, em 9:16, beats.shotDim para onde a narração avança para as instituições; verifique os stills de ambos os cortes (o texto permanece legível sobre a página, legendas claras).
  • Cada cena: manchete, batidas orientadas por âncoras (com fallbacks), uma linha de origem em tomadas de dados, SCHEMATIC em ilustrações, strings na tela de ambos os idiomas, conteúdo claro da faixa de legendas.
  • Revisão: renderize stills em quadros baseados em âncoras para todo o filme em cada idioma e monte-os em folhas de contato (scripts/review.py <Composition> <cut> [--scenes ...], um pacote para todos os quadros) e observe — sobreposições, recortes, quadros vazios, texto ilegível, qualquer coisa fora da mensagem. Em seguida, revise o ritmo, lendo as folhas como a história que um espectador obtém: sinalize qualquer trecho de mais de ~20 s sem um novo visual real, qualquer lista de três ou mais itens lida em voz alta, qualquer fórmula ou teoria que não esteja vinculada a dados na tela e qualquer cena que não avance a única descoberta — comprima ou corte essas. Itere.

7. Verificação de fatos independente

Gere um novo agente que não construiu nada para verificar o roteiro e cada string/número na tela em relação ao artigo (prompt em reference/rigor.md). Uma passagem leve é suficiente por padrão: o roteiro e a cópia logo após o roteiro estar finalizado (antes da voz paga, quando correções de redação são mais baratas) — números, configurações, exageros. Verifique as telas você mesmo em relação a notes/claims.md enquanto revisa as folhas; adicione uma segunda passagem independente (telas, dados plotados, capas) apenas para um filme de alto risco ou quando o usuário pedir. Corrija itens DEVE-CORRIGIR (incluindo redação da narração, depois regenere essas cenas e reajuste o tempo da música: music.py --refit para um fundo gerado, o mesmo --file … --keep-ending N novamente para uma faixa de biblioteca) e a maioria dos itens DEVERIA-CORRIGIR.

8. Som, render

…

Habilidades Relacionadas