Communitygithub.com

code-animation-skill

Transforme um conceito abstrato em um curta de animação de 1–2 minutos. **Não é vídeo generativo** — cada quadro é um gráfico vetorial calculado no navegador, reproduzível quadro a quadro e editável localmente.

O que é code-animation-skill?

Esta habilidade permite que um agente de IA crie animações científicas e educacionais em formato de vídeo de 1 a 2 minutos, usando código para gerar cada quadro vetorial no navegador. Diferente de vídeos gerativos tradicionais, cada frame é produzido de forma determinística, permitindo reprodução e edição local. O fluxo de trabalho inclui: (1) validação de um storyboard JSON, (2) construção e renderização em HTML, (3) conversão para MP4 e (4) verificação de qualidade com métricas quantitativas como diferença entre frames, proporção de movimento, cobertura e faixa de luminância. A habilidade também suporta a geração de trilha sonora sintética usando NumPy, sem amostras de bibliotecas externas. É ideal para explicar conceitos de física, matemática, astronomia, história e tecnologia. O sistema é composto por seis camadas de renderização (L0 a L5) e oito templates de cena predefinidos, mas facilmente extensíveis. Funciona em qualquer plataforma que suporte execução de scripts Python e HTML Canvas, como Claude Code, Cursor, e Codex.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Shang-en-yee/code-animation-skill/tree/HEAD

Perguntar na sua IA favorita

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

Documentação

Code Animation (Oficina de Animação com Código)

Transforme um conceito abstrato em um curta de animação de 1–2 minutos. Não é vídeo generativo — cada quadro é um gráfico vetorial calculado no navegador, reproduzível quadro a quadro e editável localmente.

O produto é um MP4, mais um storyboard.json reutilizável.


Fluxo em Três Etapas

# 1. Validar storyboard
python scripts/lint.py storyboard.json

# 2. Construir + renderizar (~0,5 s/quadro)
python scripts/build.py storyboard.json out.html
python scripts/render.py --html out.html --duration 117 --fps 30 --out film.mp4

# 3. Verificação de qualidade; retorna não zero se falhar
python scripts/measure.py film.mp4 --thresholds reference/thresholds.json

Se a verificação falhar, corrija — não aceite baseado em "parece bom".

Adicionar trilha sonora (opcional, mas fortemente recomendado)

O áudio também é calculado, sem amostras de nenhuma biblioteca — mesmo princípio que o visual.

# 1. Sintetizar trilha sonora (numpy, ~40 segundos)
python scripts/make_audio.py score.wav --storyboard storyboard.json

# 2. Mixar ao vídeo e converter para H.264 para reduzir tamanho
python scripts/mux.py --video film.mp4 --audio score.wav --out final.mp4 --crf 23

A trilha padrão é para temas de espaço/física: base longa em Ré menor + acordes que mudam a cada cena + pulso cardíaco a cada 8 segundos + harpejos esparsos, com varreduras de ruído nas transições e batida grave nos capítulos.

Para outros temas, ajuste os parâmetros da trilha, não use o padrão:

TemaComo alterar a trilha
Física / AstronomiaManter padrão: menor, longa, esparsa
Matemática / AlgoritmosMudar para maior ou modo lídio, adicionar arpejos regulares
História / HumanidadesRemover pulso, diminuir velocidade do pad, adicionar dissonâncias
Produto / TecnologiaRemover pad longo, mudar para groove sintetizado a 90–110 BPM

Os parâmetros estão nas constantes SCALE / ROOT / bpm no topo do make_audio.py e no array chords em build().


storyboard.json

{
  "title": "Gravidade",
  "fps": 30,
  "palette": { "bg": "#08090F", "ink": "#E6DCCB", "dim": "#8A8177", "accent": "#E0813C" },
  "scenes": [
    {
      "id": "open",
      "kind": "title",
      "dur": 6.0,
      "cn": "引力",
      "en": "GRAVIDADE"
    },
    {
      "id": "newton",
      "kind": "orbit",
      "dur": 16.0,
      "chapter": ["I", "苹果与月亮", "A MAÇÃ E A LUA"],
      "subs": [
        [0.6,  "Em 1687, Newton uniu a maçã e a Lua com uma única equação."],
        [7.4,  "A gravidade é proporcional à massa e inversamente ao quadrado da distância."]
      ]
    }
  ]
}
CampoDescrição
kindNome do template de cena (veja abaixo)
durDuração da cena (segundos), recomendado 12–20
chapter[número, título em chinês, TÍTULO EM INGLÊS], fixo no canto superior esquerdo
subsArray de [segundo de início, texto]; cada tela deve durar 5–6 segundos
cn / enPara cenas de título

Templates de Cena (8)

kindVisualAplicação
titleTítulo grande + legenda em inglêsAbertura
outroDuas linhas de conclusãoEncerramento
orbitÓrbita elíptica + grade polarMovimento periódico, gravidade
precessFlor de precessão + disco angularPequenos desvios, precessão
elevatorCaixa + escala internaReferenciais, princípio da equivalência
warpGrade espaço-tempo em perspectiva + anotaçõesCurvatura, campo
evidenceAnéis concêntricos de lente + forma de onda chirpEvidência, sinal
blackholeDisco de acreção + anel de fótons + escala anularCorpos celestes extremos

Parâmetros dos templates em templates/shots/*.json.


Arquitetura em Seis Camadas (Por que esta ordem)

L5 Pós-processamento    bloom → vinheta → granulação
L4 Texto    Títulos / letras grandes / fórmulas / legendas
L3 Anotações    Linhas-guia + etiquetas + caixas de leitura
L2 Corpo    Gráfico principal da cena
L1 Estrutura    Grade / escalas / eixos
L0 Fundo    Nebulosa / pontos / poeira / estrelas distantes

L1 e L3 são a fonte da "aparência profissional", não L2. Uma cena apenas com o corpo parece simples; adicionar camadas de estrutura e anotações transforma a imagem em "interface de instrumento".

base.html já implementa todas as seis camadas — novas cenas só precisam escrever a função de desenho L2.


Limiares de Aceitação

reference/thresholds.json:

{
  "frame_diff_min": 1.5,
  "moving_ratio_min": 0.70,
  "coverage_min": 0.20,
  "luma_range": [16, 30]
}
MétricaSignificadoPor quê
frame_diffDiferença média entre quadros consecutivosAbaixo de 1,5 é "apresentação de slides", não animação
moving_ratioProporção de quadros com movimentoAbaixo de 70% dá sensação de "travamento"
coverageProporção de pixels com estrutura localAbaixo de 20% a cena parece vazia
lumaLuminância médiaAbaixo de 16 a estrutura se perde no preto; acima de 30 perde o tom escuro

Esses limiares foram calibrados com vídeos de referência reais — não os ajuste levianamente. Veja reference/findings.md para detalhes.


Armadilhas Conhecidas (Lições Dolorosas)

1. Nunca use ctx.shadowBlur. Dezenas de sombras por quadro na renderização por software aumentam o tempo de quadro de 20ms para 5s. Use bloom() do base.html — reduza o canvas para 1/6 e amplie sobrepondo, duas chamadas drawImage, quase de graça.

2. Parâmetros devem vir da mesma fonte. Já houve um bug onde "a partícula corria para fora da linha": a linha era calculada com p², o ponto com p. O caminho e a cabeça de um mesmo elemento devem ser dirigidos pela mesma variável.

3. Granulação determina o tamanho do arquivo. Ruído aleatório quadro a quadro tem entropia altíssima, o codec de vídeo não consegue comprimir bem. Com α=0,03, 1080p30 consome ~50KB/quadro — dois minutos ~300MB. Para reduzir, diminua α (~0,015) ou reduza o fps; não espere que o codec resolva.

4. Use JPEG para quadros, não PNG. PNG com granulação leva mais de 4× o tempo de JPEG (medido: 2,0s/quadro vs 0,5s/quadro).

5. Brilho não é filtro. Não use CSS brightness() para clarear — isso queima o texto junto. Para clarear, aumente o alpha das camadas de conteúdo (grade, nebulosa, poeira), seguindo as proporções de reference/palette.json.


Como Criar Novas Cenas

  1. Adicione um case em drawScene() no base.html
  2. Escreva apenas L2 (corpo); use polarGrid / ringTicks / axisTicks / drawInstrument para L1 e drawLeader para L3
  3. Extraia parâmetros ajustáveis para um objeto e salve em templates/shots/<nome>.json
  4. Execute measure.py — as três métricas devem ser atendidas para considerar concluído

Exemplo

examples/gravity.storyboard.json — storyboard completo do curta de dois minutos "Gravidade", com todos os oito templates funcionais. Pode ser usado como ponto de partida, alterando apenas o texto.

Habilidades Relacionadas