Communitygithub.com

code-animation-skill

Convierte un concepto abstracto en un video animado de 1 a 2 minutos. **No es video generativo**—cada cuadro es gráficos vectoriales calculados en el navegador, reproducible cuadro por cuadro y modificable localmente.

¿Qué es code-animation-skill?

Esta habilidad permite a un agente de IA generar videos animados explicativos de 1 a 2 minutos sobre conceptos abstractos (ciencia, matemática, tecnología, etc.). A diferencia de los videos generativos (como los de modelos de difusión), cada cuadro es renderizado como gráficos vectoriales en el navegador, lo que garantiza reproducibilidad total y la posibilidad de modificar elementos específicos sin regenerar todo el video. El flujo de trabajo consta de tres pasos: 1) validación del storyboard, 2) construcción y renderizado del HTML a video (MP4), y 3) control de calidad automático con métricas cuantitativas (diferencia entre cuadros, proporción de movimiento, cobertura y luminancia). Opcionalmente se puede agregar una banda sonora generada algorítmicamente con Python/numpy, también sin muestras de bibliotecas. La habilidad está diseñada para plataformas como Claude Code, Cursor o Codex, y se basa en una arquitectura de seis capas (fondo, estructura, contenido principal, anotaciones, texto y post-procesamiento) para lograr un aspecto profesional de 'instrumento científico'. Incluye 8 plantillas de tomas predefinidas (título, órbita, precesión, ascensor, deformación, evidencia, agujero negro, outro) y un proceso claro para extender con nuevas tomas.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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:

TemaCómo cambiar la música
Física / AstronomíaMantener predeterminado: modo menor, notas largas, disperso
Matemáticas / AlgoritmosCambiar a modo mayor o lidio, añadir arpegios regulares
Historia / HumanidadesQuitar pulsos, ralentizar pads, añadir algunos intervalos disonantes
Producto / TecnologíaQuitar 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."]
      ]
    }
  ]
}
CampoDescripción
kindNombre de la plantilla de toma (ver tabla abajo)
durDuración de la toma en segundos (se recomienda 12–20)
chapter[número, Español, ENGLISH], se muestra permanentemente en la esquina superior izquierda
subsArreglo de [segundo de inicio, texto]; se recomienda 5–6 segundos por pantalla
cn / enSolo para tomas de título

Plantillas de Tomas (8)

kindVisualCuándo usarla
titleTexto grande + subtítulo en inglésApertura
outroDos líneas de conclusiónCierre
orbitÓrbita elíptica + cuadrícula polarMovimiento periódico, gravedad
precessPétalos de precesión + dial de ángulosDesviaciones pequeñas, precesión
elevatorCaja + escala interiorSistemas de referencia, principio de equivalencia
warpCuadrícula espacio-temporal en perspectiva + anotacionesCurvatura, campo
evidenceAnillos concéntricos de lente + forma de onda chirpEvidencia, señales
blackholeDisco de acreción + anillo de fotones + escala circularObjetos 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étricaSignificadoPor qué
frame_diffDiferencia promedio entre cuadros consecutivosPor debajo de 1.5 es una "diapositiva", no una animación
moving_ratioProporción de cuadros con movimientoPor debajo del 70% da sensación de "atorado"
coverageProporción de píxeles con estructura localPor debajo del 20% la imagen se ve vacía
lumaLuminancia promedioPor 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

  1. Añade un case en drawScene() dentro de base.html
  2. Solo escribe L2 (contenido principal); usa polarGrid / ringTicks / axisTicks / drawInstrument para L1, y drawLeader para L3
  3. Extrae los parámetros ajustables a un objeto y guárdalo en templates/shots/<nombre>.json
  4. 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.

Skills relacionados