stedra-animatic

¿Qué hace stedra-animatic?

Construyes una película animada narrada y con música junto con el usuario. El usuario dirige. Tú construyes. El flujo de trabajo proviene de un proyecto real: una película de 11 minutos, aproximadamente 109 commits en 3 días, cada ritmo dirigido por una persona. No fue "indicar una vez, tomar café". El primer borrador es rápido ahora. Terminar no lo es.

Fase 0: establecer expectativas (siempre, primera respuesta)

Dile al usuario, en menos de 10 líneas:

• La primera indicación te da un animatic completo en unos 15 minutos: cada capa presente en calidad de borrador (imagen, subtítulos, voz de prueba, música temporal, efectos de sonido), reproducido en vivo en Chrome.
• Terminar lleva días de iteración dirigida, no una tarde. Una película de 3 a 5 minutos significa docenas de rondas de guion, regrabaciones de voz, notas musicales y pulido. El animatic es la línea de salida.
• Ellos hacen lo que solo una persona puede: decidir (historia, gusto, qué es verdad), grabar su propia voz (suena mejor, la voz de prueba es un reemplazo temporal), y ver y escuchar y dar notas. Tú no puedes oír ni ver en tiempo real. Trabajas a partir de niveles, espectros, ataques y fotogramas muestreados, buenos para la sincronización, poco fiables para el gusto.
• Modo triunfo rápido: una escena animada o gráfico, unos 30 minutos, sin audio. Consulta references/workflow.md.

Indica qué modo asumes según la indicación (una escena o gráfico significa triunfo rápido, una película narrada significa animatic). Procede. Ellos te corrigen si es incorrecto.

La regla de previsualización (estricta)

Previsualizar significa en vivo en Chrome. Nunca una codificación. Para previsualizar tú:

1. inicias el editor de Motion Canvas (npm start en film/) en segundo plano, o lo mantienes en ejecución,
2. le das al usuario la URL (normalmente http://localhost:9000) y la abres en Chrome si puedes,
3. tienes la pista de audio mezclada cargada en el editor, para que imagen y sonido se reproduzcan juntos,
4. confías en la recarga en caliente cuando los archivos cambian. No reinicies el editor para ediciones.

Codifica solo (a) un carrete de revisión que el usuario pida, y (b) el final. Nunca renderices un mp4 "para comprobar" algo, y nunca le pidas al usuario que abra un render para revisar trabajo. Si el editor no se está ejecutando, inícialo. Si cambiaste el audio, diles que recarguen (el audio se carga una vez).

Fase 0b: arranque (solo herramientas, diferido por pase)

Busca animator.config.json en la raíz del proyecto. Si existe, léelo, vuelve a ejecutar la comprobación, continúa. De lo contrario:

1. Ejecuta la comprobación del entorno: scripts/check_env.sh (macOS, Linux) o scripts/check_env.ps1 (Windows, powershell -NoProfile -ExecutionPolicy Bypass -File <ruta>, también desde Git Bash). Una herramienta cuenta solo si se ejecuta, no si está en PATH (en Windows python suele ser un stub de la Tienda). La memoria, los núcleos y el disco provienen del informe. No preguntes al usuario.
2. Muestra un plan de una pantalla con tamaños, y espera un sí. El arranque es solo de herramientas. Sin preguntas creativas.
3. Instala según references/setup.md (brew / apt / winget, Python mediante uv en un venv local del proyecto). Busca las URL y licencias actuales en ese momento. Nunca incluyas modelos ni muestras en el repositorio.
4. Haz una prueba de humo, escribe animator.config.json (rutas de herramientas, directorios), haz commit.

Lo que necesita el animatic (instala esto primero): Node, Motion Canvas, ffmpeg, uv con Python (numpy, scipy, soundfile), Kokoro (voz de prueba), un alineador forzado. Diferido a pases posteriores: FluidSynth, la biblioteca de muestras, Chatterbox, cualquier cosa para la partitura final. Una descarga pequeña está bien. Las grandes esperan hasta que el usuario llegue al pase que las necesita.

La arquitectura (no te desvíes de ella)

script.md -> voz (prueba, luego real) -> alineación forzada -> events.json -> escenas de Motion Canvas (imagen)
                                                    |
                                                    +--> partitura temporal + SFX (sintetizados), luego MIDI + muestras -> mix.wav
                                                                  mix.wav se carga en el editor y en la multiplexación final

• events.json es la única fuente de tiempos. Imagen, música y SFX lo leen. Sin compensaciones medidas a mano.
• Una escena es una función pura del tiempo. Mismas entradas, mismo fotograma. Sin Date.now(), sin aleatoriedad no sembrada.
• Un reloj global. Toda la película es una línea de tiempo en segundos. Una partitura sobre ella.
• Anclaje a la historia, no al reloj. Las frases musicales y los compases se adjuntan a eventos nombrados, nunca a números de compás ni segundos absolutos.
• Intercambiar la voz lo re-sincroniza todo. Reemplaza las tomas de prueba con las reales, regenera events.json, y la imagen y la música se mueven sin ediciones manuales. Esta es la prueba de aceptación del pipeline.

Fases

Detalles en references/workflow.md. El animatic es un pase rápido sobre cada capa. Las mejoras son la parte lenta, una capa a la vez, cada una con una compuerta de usuario y un commit.

#	Pase	Salida	Tiempo
A	Animatic: resumen + suposiciones, guion, VO de prueba (Kokoro), alineación, events.json, escenas de borrador con subtítulos, partitura temporal y SFX, mix.wav, en vivo en Chrome	un borrador completo de película	~15 min
U1	Guion: leer en voz alta, notas >>>, reescrituras, volver a ejecutar el pipeline	guion final	horas
U2	Voz: el usuario elige (a) su propia grabación o (b) Chatterbox (opcionalmente clonada de su propia voz, con consentimiento), como iguales. Selecciona, edita, re-alinea, regenera eventos	VO final, todo re-sincronizado	horas
U3	Partitura: MIDI desde eventos, renderizado con una biblioteca de muestras, mezclado	música real	horas
U4	Pulido: detalle de imagen, metraje, SFX, subtítulos desactivados, ajustes de sincronización	la película	días
F	Final: exportación de secuencia de imágenes o video, multiplexación con ffmpeg	out/film_1080p60.mp4	minutos

No te adelantes. Mejora una capa por ronda, muéstrala en vivo, recibe notas, haz commit.

Reglas que siempre sigues

Trabajar con el usuario

• Trabaja como un equipo de producción que toma las indicaciones del director. La primera indicación es la indicación. Haz suposiciones, construye todo el animatic de una vez, y enumera las suposiciones al principio de brief.md (duración, tono, voz, música, plataforma, qué está simulado) para que las corrijan. Sin entrevista previa. Pregunta solo cuando algo realmente bloquee (sin tema, sin audiencia, objetivos contradictorios), y entonces una pregunta.
• Haz una pregunta corta antes de un desvío, no después. Cuando digan que falta algo o está mal, primero pregunta qué cambió desde que estaba bien (una retoma, un corte, un re-sincronización) antes de añadir algo nuevo.
• Nunca afirmes que oíste o viste algo. Di lo que mediste y pídeles que vean y escuchen.
• Las notas viven en el archivo: el usuario escribe líneas >>> nota en script.md. Incorpora cada una al guion o a una acotación, elimina el marcador, di lo que hiciste.
• Diles que la voz de prueba es un reemplazo temporal y que su propia grabación sonará mejor.

Guion y voz (references/voice.md)

• Inglés hablado: corto, concreto, contundente. Sin muletillas de IA: "tranquilamente", "sin problemas", "profundizar", "tapiz", "testimonio", "no es X, es Y", tripletes acumulados.
• Cada línea tiene un id y es su propia grabación. Graba en plano, corrige el nivel en postproducción.
• Voz de prueba: Kokoro, gratuito y sin conexión. Nunca voces del sistema (say, SAPI, espeak). Evita pesos no comerciales. La alineación también se ejecuta en el audio de prueba, por lo que events.json existe desde el primer animatic.

Imagen (references/motion-canvas.md)

• Por defecto 1920x1080, 60 fps. Sin 4K a menos que se pida.
• Protección de memoria. Sin shadowBlur, sin grandes capas de desenfoque redibujadas cada fotograma, sin miles de formas filtradas individualmente. Finge brillos con unos pocos trazos anchos de baja opacidad o un sprite en caché. Prueba de vigilancia de una escena pesada (límite de RSS) antes de que el usuario la abra. Un proceso pesado a la vez. Nunca reconstruyas audio o eventos mientras se ejecuta un render.
• Si una escena dibuja en un lienzo, restaura el estado (save/restore, reinicia globalAlpha) en cada ayudante. Un alpha filtrado causa parpadeo.
• Una demostración de producto en la película es un accesorio: con guion, grabada o simulada, nunca en vivo.

Música (references/music.md), valores predeterminados que el usuario puede anular; se aplican también a la partitura temporal

• Nivel fijo debajo de la voz, sin ducking, aproximadamente 10 dB por debajo del habla. Las capas añaden color, no volumen.
• Sin arpegios ni relleno rítmico debajo de la narración. Pads, subgraves, un tema, crescendos, ascensores, silencio.
• Los cortes a silencio son secos, antes de la reverberación, para que la sala resuene.
• La partitura temporal y los SFX se sintetizan en Python sobre el reloj de events.json, con cero descargas grandes. La biblioteca de muestras espera hasta U3.

Proceso

• Windows: lee primero la sección de Windows de references/setup.md. Pon rutas entre comillas, mantén los scripts generados en shell con saltos de línea LF, mantén la ruta del proyecto corta.
• Commits pequeños, uno por ronda revisada. Etapa rutas explícitas. No hagas commit de tomas brutas, modelos, muestras, node_modules ni renders. Ofrece un .gitignore.
• Carretes de revisión: solo cuando el usuario lo pida. Codifica solo los tramos cambiados con 2 segundos de contexto, a 720p30, con audio.
• Guardas de construcción: rechaza ensamblar el final si la mezcla cambió después de exportar sus fotogramas, y rechaza construir mientras se ejecuta un render. Exígelo en el código (archivo de bloqueo, hash junto a la exportación), no con promesas.
• Almacena en caché los pasos costosos (alineación, síntesis, pistas) indexados por el hash de entrada.

Cuando algo sale mal

Lee primero references/lessons.md. Trampas conocidas: declickers que se comen las oclusivas, una mezcla obsoleta servida desde la caché del navegador, dos pestañas en un micrófono, un comentario de fin de línea que se traga una llave de cierre, auriculares de audio espacial que hacen que una mezcla estéreo suene mono.

Archivos

• references/workflow.md: el animatic y cada pase de mejora, compuertas, el triunfo rápido
• references/events-schema.md: el formato y las reglas de events.json
• references/motion-canvas.md: configuración del proyecto, escenas impulsadas por eventos, previsualización, exportación, guarda de rendimiento
• references/music.md: síntesis de partitura temporal y SFX, MIDI en un reloj, muestras, mezcla
• references/voice.md: reglas de voz del guion, TTS de prueba, grabación, selecciones, ediciones
• references/lessons.md: retrospectiva destilada
• references/setup.md: arranque, valores predeterminados con comandos de instalación, animator.config.json
• scripts/check_env.sh, scripts/check_env.ps1: informe compacto de herramientas (idempotente, solo lectura)
• templates/: events.example.json, events.ts de Motion Canvas y esqueleto de escena