raymond9703/AgentMotion

AgentMotion — Marco unificado de generación de vídeos con código puro

Convierte "una frase" en un MP4 dibujado completamente con código. Esta habilidad es la capa de orquestación: te ayuda a elegir el backend, el estilo, el flujo de trabajo y pasar el control de calidad; el conocimiento de dibujo específico está en references/ y styles/.

Invariantes centrales (compartidos por todos los backends)

Cada fotograma es una función pura del número de fotograma: frame = f(t). No uses Math.random() (usa aleatoriedad con semilla), no uses Date.now(), no uses acumulación de estado en rAF. Esta es la premisa que permite el renderizado determinista, la generación paralela de fotogramas y la autoinspección fotograma por fotograma. Violarlo hará que el renderizado y la vista previa no coincidan.

Primer paso: Elegir backend (árbol de decisión)

Escenario	Backend	Referencia
Cortometraje (≤60s), sin素材 externos, ilustración / dibujo a mano / estilizado	HTML Canvas de un solo archivo	references/backends.md §1
Data-driven, personalización por lotes (un vídeo por dato), subtítulos / narración incrustados, ecosistema de gráficos 3D / diagramas	React + Remotion	references/backends.md §2
Animación interactiva para reproducción directa en navegador (no necesita MP4)	HTML de un solo archivo, entrega HTML en lugar de renderizado	references/backends.md §3

Si no estás seguro, elige Canvas de un solo archivo: mínimas dependencias, el agente tiene más probabilidades de escribirlo correctamente a la primera.

Segundo paso: Elegir estilo

Consulta styles/recipes.md (15 recetas de estilos comerciales: paletas de colores / técnicas centrales / patrones de movimiento / trampas a evitar). Cuando el usuario no especifique un estilo, pídele que elija o recomiéndale según el tema; por defecto no reutilices el mismo conjunto visual y banda sonora para dos vídeos diferentes.

Tercer paso: Flujo de trabajo estándar (no pares a preguntar)

1. Leer el problema: Deduce del input del usuario el tipo de vídeo (historia / explicativo / recopilatorio / bucle / datos), duración (por defecto 15-20s), formato (por defecto 1920×1080; para vídeos de datos usa 1080×1920). El idioma de los subtítulos sigue el idioma del input del usuario.
2. Storyboard: Primero define el BPM y los datos de las secciones (SECTIONS/SHOTS/EVENTS). La imagen y la banda sonora leen los mismos datos de tiempo, asegurando una sincronización natural (ver references/storyboard.md).
3. Armar el esqueleto: Copia desde templates/starter.html (para Canvas backend), reemplaza la paleta de colores y el dibujo del mundo. Mantén el contrato: la página expone window.C2V = { fps, frames, width, height, draw(frame) }, donde draw es una función pura.
4. Autoinspección y renderizado (el orden no se puede invertir):

node scripts/render.mjs film.html sheet.jpg --sheet 1          # 1 fotograma/segundo en mosaico, stepping off cuts
node scripts/render.mjs film.html still.png --stills 0,90,300  # Fotogramas estáticos en momentos específicos
node scripts/env-check.mjs                                      # Verificación del entorno
node scripts/render.mjs film.html out.mp4 --audio music.mp3     # Renderizado completo del vídeo (banda sonora opcional)
node scripts/probe.mjs out.mp4 1920x1080 30                     # Afirmar parámetros de codificación

5. Dos rondas de inspección visual (references/qc.md): ① Coincidencia del storyboard — captura fotogramas en los puntos de acción de cada toma y compáralos con las filas del storyboard; ② Ronda del director — revisa el contact sheet, evalúa ritmo / diversidad de planos / fotogramas muertos / si cada acción tiene sonido. Al menos dos rondas; solo re-renderiza los fotogramas que se modifican.
6. Entrega: MP4 + HTML (el HTML se puede reproducir directamente en el navegador). Al final, ofrece opciones de cambio: cambiar estilo, cambiar banda sonora, modificar duración.

Para el backend de Remotion, la renderización y verificación se hacen con npx remotion still → inspección visual → npx remotion render (ver references/backends.md §2).

Reglas para evitar fallos (los fracasos más comunes)

• Función pura. Cualquier acumulación de estado causará errores de fotogramas en el renderizado paralelo.
• Las líneas dibujadas a mano deben "hervir", no "temblar": cambia la semilla de wobble cada 4 fotogramas (≈7.5 veces/segundo); cambiar en cada fotograma se percibe como ruido.
• Usa elipses y rectángulos redondeados para el cuerpo, evita polígonos con muchos puntos que parecen señales de tráfico.
• El orden de dibujo debe ser explícitamente de atrás hacia adelante; la mayoría de los casos de "cara tapada" son problemas de orden de dibujo.
• El texto nunca debe colisionar: asigna espacios (claim) a bloques de texto y objetos clave; revisa el diseño fotograma por fotograma antes de la entrega.
• Los puntos de corte y acción deben caer en el compás, y los saltos de volumen ≤ +6dB; de lo contrario, se percibirán como sobresaltos (ver references/audio.md).

Mapa de archivos

Archivo	Contenido
scripts/render.mjs	Núcleo de renderizado determinista: MP4 / fotograma estático / contact sheet, paralelo con múltiples workers
scripts/env-check.mjs / probe.mjs	Verificación del entorno / Afirmación de codificación MP4
templates/starter.html	Esqueleto de fotograma = f(t): contrato, aleatoriedad con semilla, easing, cámara, compás
styles/recipes.md	15 recetas de estilos a nivel de código
references/*.md	Flujo de trabajo / Storyboard / Técnicas / Control de calidad / Banda sonora / Selección de backend
examples/hello-drop.html	Ejemplo mínimo ejecutable de inmediato

Dependencias

Node 18+, ffmpeg (accesible en PATH), Chrome o Edge; npm i playwright-core (instálalo en el directorio de tu proyecto, no en el directorio de esta habilidad).