Taller de Animación con Código (Code Animation)
Convierte un concepto abstracto en un video animado de 1 a 2 minutos. No es video generativo—cada cuadro son gráficos vectoriales calculados en el navegador, reproducibles cuadro por cuadro y modificables localmente.
El resultado es un MP4 y un archivo storyboard.json reutilizable.
Proceso en Tres Pasos
# 1. Validar el storyboard
python scripts/lint.py storyboard.json
# 2. Construir + renderizar (aproximadamente 0.5 seg/cuadro)
python scripts/build.py storyboard.json out.html
python scripts/render.py --html out.html --duration 117 --fps 30 --out film.mp4
# 3. Control de calidad; retorna código distinto de cero si no cumple
python scripts/measure.py film.mp4 --thresholds reference/thresholds.json
Si no pasa el control de calidad, hay que ajustar. No se acepta "se ve bien" como verificación.
Añadir Banda Sonora (opcional, pero muy recomendado)
El audio también se genera mediante código, sin muestrear ninguna librería de sonidos—igual que el video.
# 1. Sintetizar la banda sonora (numpy, aproximadamente 40 s)
python scripts/make_audio.py score.wav --storyboard storyboard.json
# 2. Mezclar con el video y convertir a H.264 para reducir tamaño
python scripts/mux.py --video film.mp4 --audio score.wav --out final.mp4 --crf 23
La banda sonora predeterminada es para temas espaciales/físicos: base de notas largas en Re menor + pads que cambian de acorde por escena + pulso cardíaco cada 8 segundos + punteos dispersos, con barridos de ruido en las transiciones y golpes graves en los capítulos.
Al cambiar de tema, hay que ajustar los parámetros de la banda sonora, no usar la misma directamente:
| Tema | Cómo cambiar la música |
|---|---|
| Física / Astronomía | Mantener predeterminado: modo menor, notas largas, disperso |
| Matemáticas / Algoritmos | Cambiar a modo mayor o lidio, añadir arpegios regulares |
| Historia / Humanidades | Quitar pulsos, ralentizar pads, añadir algunos intervalos disonantes |
| Producto / Tecnología | Quitar pads largos, cambiar a groove de sintetizador a 90–110 BPM |
Los parámetros están en las constantes SCALE / ROOT / bpm al inicio de make_audio.py, y en el arreglo chords dentro de build().
storyboard.json
{
"title": "Gravedad",
"fps": 30,
"palette": { "bg": "#08090F", "ink": "#E6DCCB", "dim": "#8A8177", "accent": "#E0813C" },
"scenes": [
{
"id": "open",
"kind": "title",
"dur": 6.0,
"cn": "引力",
"en": "GRAVEDAD"
},
{
"id": "newton",
"kind": "orbit",
"dur": 16.0,
"chapter": ["I", "La manzana y la Luna", "THE APPLE AND THE MOON"],
"subs": [
[0.6, "En 1687, Newton unió la manzana y la Luna con una sola fórmula."],
[7.4, "La gravedad es proporcional a la masa e inversamente proporcional al cuadrado de la distancia."]
]
}
]
}
| Campo | Descripción |
|---|---|
kind | Nombre de la plantilla de toma (ver tabla abajo) |
dur | Duración de la toma en segundos (se recomienda 12–20) |
chapter | [número, Español, ENGLISH], se muestra permanentemente en la esquina superior izquierda |
subs | Arreglo de [segundo de inicio, texto]; se recomienda 5–6 segundos por pantalla |
cn / en | Solo para tomas de título |
Plantillas de Tomas (8)
| kind | Visual | Cuándo usarla |
|---|---|---|
title | Texto grande + subtítulo en inglés | Apertura |
outro | Dos líneas de conclusión | Cierre |
orbit | Órbita elíptica + cuadrícula polar | Movimiento periódico, gravedad |
precess | Pétalos de precesión + dial de ángulos | Desviaciones pequeñas, precesión |
elevator | Caja + escala interior | Sistemas de referencia, principio de equivalencia |
warp | Cuadrícula espacio-temporal en perspectiva + anotaciones | Curvatura, campo |
evidence | Anillos concéntricos de lente + forma de onda chirp | Evidencia, señales |
blackhole | Disco de acreción + anillo de fotones + escala circular | Objetos extremos |
Los parámetros de las plantillas están en templates/shots/*.json.
Arquitectura de Seis Capas (Por qué este orden)
L5 Post-procesamiento bloom → viñeteado → grano
L4 Texto Títulos de capítulo / texto grande / fórmulas / subtítulos
L3 Anotaciones Líneas guía + etiquetas pequeñas + recuadros de lecturas
L2 Contenido principal Gráfico central de la toma
L1 Estructura Cuadrícula / escala / ejes
L0 Fondo Nebulosa / puntos / polvo / estrellas lejanas
L1 y L3 son la fuente de la "sensación profesional", no L2. Una imagen solo con el contenido principal se siente simple; al añadir las capas de estructura y anotaciones, la misma imagen se transforma en una "interfaz de instrumento científico".
base.html ya implementa las seis capas; para una nueva toma solo hay que escribir la función de dibujo de L2.
Umbrales de Aceptación
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 | Diferencia promedio entre cuadros consecutivos | Por debajo de 1.5 es una "diapositiva", no una animación |
moving_ratio | Proporción de cuadros con movimiento | Por debajo del 70% da sensación de "atorado" |
coverage | Proporción de píxeles con estructura local | Por debajo del 20% la imagen se ve vacía |
luma | Luminancia promedio | Por debajo de 16 la estructura se pierde en el negro; por encima de 30 se pierde el tono oscuro de base |
Estos umbrales están calibrados con videos de referencia reales; no los modifiques a la ligera. Ver detalles en reference/findings.md.
Problemas Conocidos (Lecciones aprendidas con dolor)
1. Nunca uses ctx.shadowBlur.
Con decenas de sombras por cuadro en renderizado por software, el tiempo por cuadro pasa de 20 ms a 5 segundos. Usa bloom() de base.html — reduce el lienzo a 1/6 y luego lo superpone ampliado; dos drawImage, casi sin costo.
2. Los parámetros deben ser consistentes.
Hubo un error donde "la partícula se salía de la línea": la línea se calculaba con p² y la partícula con p. La trayectoria y la cabeza de un mismo elemento deben estar impulsadas por la misma variable.
3. El grano determina el tamaño del archivo. El ruido aleatorio cuadro por cuadro tiene una entropía muy alta, el códec de video no logra comprimirlo. Con grano α=0.03 en 1080p30, cada cuadro ocupa ~50 KB—un video de dos minutos sería ~300 MB. Para reducir tamaño, baja α (a ~0.015) o reduce la tasa de cuadros. No esperes que el códec lo haga.
4. Usa JPEG para los cuadros, no PNG. Codificar PNG con grano toma más de 4 veces el tiempo de JPEG (medido: 2.0 s/cuadro vs 0.5 s/cuadro).
5. El brillo no es un filtro.
No uses brightness() de CSS para aclarar—también blanquea el texto. Para aclarar, aumenta el alfa de las capas de contenido (cuadrícula, nebulosa, polvo), siguiendo las proporciones de reference/palette.json.
Cómo Extender con Nuevas Tomas
- Añade un
caseendrawScene()dentro debase.html - Solo escribe L2 (contenido principal); usa
polarGrid/ringTicks/axisTicks/drawInstrumentpara L1, ydrawLeaderpara L3 - Extrae los parámetros ajustables a un objeto y guárdalo en
templates/shots/<nombre>.json - Ejecuta
measure.py; la toma solo se considera completa cuando cumple los tres indicadores
Ejemplo
examples/gravity.storyboard.json — storyboard completo del video de dos minutos "Gravedad", con las ocho tomas listas para usar. Se puede usar como punto de partida y modificar el texto.