BeaverMakerLab/code-to-video

Code-to-Video Explainer Studio (Mecanismo Universal de Vídeo Animado Orientado a Código)

📘 Consulte o livro completo de instruções detalhadas em: README.md (inclui verificação de ambiente, guia de 6 estilos, soluções de narração, guia de montagem entre agentes e manual de solução de problemas comuns).

Esta skill capacita qualquer Agente de Codificação de IA (como Claude Code, Codex, DeepSeek Harness, OpenHands/OpenClaw, Antigravity, Cursor, etc.) com capacidade de leitura/gravação de arquivos e execução de linha de comando a se tornar um diretor de vídeo profissional, programador de animação e produtor. Ao acionar o mecanismo de renderização de vídeo orientado a código local, transforma qualquer texto, repositório de código, artigo ou ideia criativa em vídeos explicativos animados em HD (1080p 60fps) com estética de papel e tinta.

---

Três Regras de Ouro (Todos os Agentes Devem Seguir Rigorosamente)

1. Primeiro aprove o storyboard, depois escreva o código (Human-in-the-Loop): Antes que o usuário confirme explicitamente o storyboard.json, é estritamente proibido escrever código de página específico ou executar a renderização final.
2. O tempo é uma função pura $Visual = f(t)$: O código da página deve ser uma função pura da variável tempo $t$. É estritamente proibido usar Math.random() (números aleatórios devem usar PV.rng(seed)), Date.now(), CSS transitions ou requestAnimationFrame.
3. Zona de segurança para legendas (Safe Zone): O tamanho da tela é 1920×1080. A área inferior $y > 900$ é exclusiva para legendas: é estritamente proibido colocar qualquer forma gráfica ou texto principal; a área de atividade principal do conteúdo deve permanecer em x: 140~1780, y: 180~880.

---

Pipeline de Produção (Método Padrão de Cinco Etapas)

Primeira Etapa: Digestão de Material e Design de Storyboard (Storyboard)

Quando o usuário solicita a criação de um vídeo (ou fornece material):

1. Estabeleça a metáfora central: Extraia uma única metáfora concreta que permeie todo o vídeo (por exemplo, "holofote" para explicar mecanismos de atenção, "post-it na mesa" para cache, "tanque e mangueira" para equações de fluido).
2. Planeje a estrutura narrativa:
   • Hook (gancho nos primeiros 3 segundos): Apresente uma pergunta contraintuitiva ou um ponto de dor central.
   • Intuição (estabelecimento da intuição): Introduza a metáfora central.
   • Mecanismo (análise do princípio): Decomponha a fórmula central ou as etapas.
   • Exemplo e Números (exemplo e cálculo): Execute dados concretos uma vez.
   • Fechamento (sublimação e conclusão): Responda ao gancho inicial, conectando o início e o fim.
3. Gere a estrutura do storyboard: Produza um esboço de storyboard com 4 a 8 páginas, cada uma com id, section, say (resumo do roteiro) e 2 a 4 beats (batidas de ação específicas, incluindo object, action, text, camera).
4. Solicite confirmação do usuário: Apresente o storyboard ao usuário, perguntando: "O esboço do storyboard foi gerado. Por favor, verifique a estrutura de cada página e o ritmo narrativo. Confirmando que está tudo certo, prosseguiremos para a fase de desenho do código."

Para especificações detalhadas e modelo de estrutura, consulte: STORYBOARD_RULES.md

---

Segunda Etapa: Geração de Roteiro e Linha do Tempo (Script & Narration)

Após a confirmação do storyboard, estabeleça o script.js:

1. Extraia o texto de narração específico para cada página, dividindo-o em cues (frases curtas de legenda) com no máximo 16 caracteres chineses cada.
2. Acione o mecanismo de voz (CosyVoice 3 local na porta 9880, Edge-TTS, ou VOLCENGINE_TTS_API_KEY / ELEVENLABS_API_KEY nas variáveis de ambiente) para gerar o áudio de cada frase.
3. Extraia os timestamps reais de leitura, atribuindo a cada cue um ponto físico no tempo (P.c(i) para início do cue, P.cw(i, 'palavra-chave') para momento de batida em nível de palavra).

---

Terceira Etapa: Programação de Animação por Página (Page Drawing Code)

Cada página de tela corresponde a um arquivo pages/pNN.js, usando a API declarativa do mecanismo:

ENGINE.visual('p01', (P) => {
  P.title('① Intuição do Princípio Central', { accent: 'orange' });
  // Vincular o cue 0 da narração para abrir o cartão principal
  P.card(200, 260, 700, 480, { title: 'Características de Entrada', at: P.c(0) });
  // Acionar seta e destaque ao falar uma palavra específica
  P.arrow(920, 500, 1100, 500, { at: P.cw(1, 'transformação') });
  // Derivação passo a passo de fórmula matemática
  P.mathDecompose(1140, 400, 600, {
    title: 'Pontuação de Atenção',
    terms: [
      { latex: 'Q K^T', name: 'Produto da Consulta e Chave', color: 'blue', at: P.c(2) },
      { latex: '\\sqrt{d_k}', name: 'Fator de Escala', color: 'orange', at: P.c(3) }
    ]
  });
});

Dica: Em ambientes de agente que suportam subagentes ou tarefas paralelas, múltiplos subagentes podem ser designados para escrever páginas diferentes simultaneamente, aumentando a velocidade de geração.
Para a lista completa de sintaxe da API e componentes, consulte: API.md

---

Quarta Etapa: Loop Fechado de Verificação Geométrica e Visual (Automated QA Loop)

Após escrever o código, é obrigatório executar a verificação. Nunca pule esta etapa:

1. No diretório do projeto, execute a ferramenta de verificação:

   node engine/tools/check.mjs --only p01
   

2. Processe o feedback:
   • Se aparecer Collision detected ou Safe zone overlap:
   • Extraia a Fix suggestion: ... na saída e ajuste diretamente os valores de coordenadas em pages/pNN.js usando as coordenadas sugeridas.
3. Repita a verificação até que cada página passe (Passed) em verde.

---

Quinta Etapa: Renderização Headless Paralela Multicore 1080p (Render)

Depois que todas as páginas passarem na verificação, execute o comando de renderização paralela:

# Renderização 16:9 widescreen 1080p 60fps (com aceleração de hardware)
node engine/tools/render.mjs --fps 60 --workers 4 --hw

• A saída estará em <diretório_do_projeto>/out/:
  • <nome_do_projeto>-with-subtitles.mp4 (com legendas bilíngues precisas)
  • <nome_do_projeto>-no-subtitles.mp4 (versão limpa sem legendas)
  • Texto de publicação e timestamps de cada capítulo.

---

Modo de Execução Rápida: Vídeo Automático com Um Clique (CLI Run)

Se o usuário deseja gerar um rascunho de vídeo de ponta a ponta automaticamente, também pode chamar a CLI automatizada integrada diretamente no diretório raiz do projeto:

# Execução automática de ponta a ponta (analisa documento -> gera storyboard -> gera páginas -> renderiza)
node apps/cli/dist/cli.js run <caminho_do_arquivo> --style warm-story --duration 60

Ou, quando precisar de uma prévia da linha do tempo em tempo real, inicie o Web Workbench:

node apps/cli/dist/cli.js serve

---

Guia de Chamada entre Plataformas para Agentes Universais (Universal Compatibility)

Esta skill não está vinculada a nenhum ambiente de agente específico; basta ter Node.js e capacidade de leitura/gravação de arquivos:

• Claude Code: Referencie este arquivo no CLAUDE.md na raiz do projeto para torná-lo globalmente ativo, ou use como comando personalizado.
• OpenHands / OpenClaw: Coloque o diretório da skill dentro do projeto e declare no AGENTS.md para montagem automática.
• DeepSeek Harness / Agente Próprio: Injete diretamente como System Prompt ou Contexto de Skill Tool no modelo grande.
• Cursor / Windsurf: Ative no diálogo usando @SKILL.md.