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:
| Tema | Como alterar a trilha |
|---|---|
| Física / Astronomia | Manter padrão: menor, longa, esparsa |
| Matemática / Algoritmos | Mudar para maior ou modo lídio, adicionar arpejos regulares |
| História / Humanidades | Remover pulso, diminuir velocidade do pad, adicionar dissonâncias |
| Produto / Tecnologia | Remover 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."]
]
}
]
}
| Campo | Descrição |
|---|---|
kind | Nome do template de cena (veja abaixo) |
dur | Duraçã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 |
subs | Array de [segundo de início, texto]; cada tela deve durar 5–6 segundos |
cn / en | Para cenas de título |
Templates de Cena (8)
| kind | Visual | Aplicação |
|---|---|---|
title | Título grande + legenda em inglês | Abertura |
outro | Duas linhas de conclusão | Encerramento |
orbit | Órbita elíptica + grade polar | Movimento periódico, gravidade |
precess | Flor de precessão + disco angular | Pequenos desvios, precessão |
elevator | Caixa + escala interna | Referenciais, princípio da equivalência |
warp | Grade espaço-tempo em perspectiva + anotações | Curvatura, campo |
evidence | Anéis concêntricos de lente + forma de onda chirp | Evidência, sinal |
blackhole | Disco de acreção + anel de fótons + escala anular | Corpos 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étrica | Significado | Por quê |
|---|---|---|
frame_diff | Diferença média entre quadros consecutivos | Abaixo de 1,5 é "apresentação de slides", não animação |
moving_ratio | Proporção de quadros com movimento | Abaixo de 70% dá sensação de "travamento" |
coverage | Proporção de pixels com estrutura local | Abaixo de 20% a cena parece vazia |
luma | Luminância média | Abaixo 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
- Adicione um
caseemdrawScene()nobase.html - Escreva apenas L2 (corpo); use
polarGrid/ringTicks/axisTicks/drawInstrumentpara L1 edrawLeaderpara L3 - Extraia parâmetros ajustáveis para um objeto e salve em
templates/shots/<nome>.json - 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.