AnmolChandiok/ae-editable-project

Proyecto After Effects editable a partir de un video generado con código

El objetivo es un proyecto que un diseñador de movimiento pueda abrir y trabajar como si lo hubiera creado a mano. El texto es texto real, las trayectorias son capas de forma, cada objeto es una precumposición con nombre y la cámara es un null que pueden re-animar. Lo opuesto es una secuencia de fotogramas renderizados metidos en una composición, que no se puede editar, así que nunca entregues eso como la animación principal.

El enfoque tiene tres pasos:

1. Exportar la escena desde los mismos datos que dibuja el renderizador.
2. Escribirla como scene.json.
3. Hacer que After Effects construya el proyecto por sí mismo, ejecutando un ExtendScript generado.

Nunca escribes un archivo .aep binario a mano.

datos del renderizador ──exportar──▶ scene.json + assets/ ──make_jsx.js──▶ build.jsx ──After Effects──▶ project.aep (+ stills de verificación)

Scripts incluidos (en scripts/):

• aelib.jsx: el constructor que se ejecuta dentro de After Effects. Lee la escena y crea composiciones, capas, fotogramas clave, máscaras, efectos, mate, marcadores y audio, luego guarda el .aep y un registro de construcción.
• make_jsx.js: node make_jsx.js [--portable] scene.json build.jsx. Verifica la escena (assets faltantes, padres incorrectos, orden de precumposiciones) y escribe un build.jsx autocontenido. Con --portable, las rutas son relativas a build.jsx, por lo que la carpeta se puede comprimir y ejecutar en otra computadora, incluido Windows. Úsalo para todo lo que entregues.
• run_in_ae.sh: run_in_ae.sh build.jsx /abs/path/Project.aep [timeout]. En macOS, ejecuta la construcción en After Effects instalado, espera a que termine y muestra el registro.

Lee references/scene-spec.md antes de escribir el exportador. Define cada campo, la interpolación, los nombres de efectos verificados y los rangos de valores, y los errores que cuestan tiempo.

Flujo de trabajo

1. Inventario de lo que dibuja el video

Lee el renderizador y enumera todo lo que aparece en pantalla y cómo se mueve:

• El mundo o fondo.
• Cada objeto o documento.
• Cada texto.
• El movimiento de la cámara.
• Momentos sincronizados con palabras o ritmos.
• El aspecto: grano, brillo, viñeta, desenfoque de movimiento, fundidos.
• El audio.

Para cada elemento, anota de dónde vienen sus números (constantes, funciones de geometría, archivos de temporización).

2. Mapear cada elemento a su forma nativa en After Effects

Elige la forma que un diseñador de movimiento crearía a mano:

En el código	En After Effects
Movimiento de cámara sobre un mundo (traslación, escala, rotación)	Un null CÁMARA. Punto de anclaje = el punto al que mira la cámara, en coordenadas del mundo. Escala = zoom. Rotación = giro. Posición = centro de la composición. Haz que cada capa del mundo sea hija de él. Entonces pantalla = posición + R·escala·(p − anclaje), que es exactamente la transformación de una cámara de canvas, por lo que las capas del mundo mantienen las coordenadas que usa el código.
Temblor de mano, sacudidas por impacto	Una expresión en la posición y rotación del null, controlada por Controles deslizantes con nombre según su función ("Cantidad de temblor", "Fuerza del impacto")
Un objeto o documento (impresión, papel, tarjeta, libro)	Su propia precomposición que contiene un borde, foto, texto, una sombra de contacto y un sólido "Oscurecer". Créala al 200% y escala la capa al 50%. Activa la colapsar transformaciones. Anima la entrada en la capa de la precomposición.
Trayectorias vectoriales (líneas costeras, reglas, círculos, líneas)	Capas de forma, un grupo por pieza lógica, con nombre
Texto	Capas de texto con la cadena real y el nombre de la fuente PostScript. Nunca uses imágenes de texto pre-renderizadas.
Mapas de bits que genera el código (fotos de relleno, texturas de papel)	Exportarlos como assets PNG/JPG, nombrarlos para que sean fáciles de reemplazar ("FOTO — reemplázame")
Escritura que aparece palabra por palabra sobre la narración	Una capa de texto con reveal: { times: [...] }. El constructor crea fotogramas clave de una máscara de Revelar por palabra (medida en AE), y el texto sigue siendo editable.
Una línea que se dibuja a sí misma	Fotogramas clave de fin de Trayectorias de recorte 0→100
Golpe / impacto	Fotogramas clave de escala/opacidad más una entrada en la lista de impactos de la cámara
Enfoque principal / oscurecimiento de otros	Un sólido negro "Oscurecer" con Conservar transparencia dentro de cada precomposición, más un sólido oscurecedor a nivel de pantalla sobre el fondo, con fotogramas clave de opacidad
Aspecto cinematográfico	Capas de ajuste con nombre ("ASPECTO — Brillo suave", "ASPECTO — Grano de película"), un sólido de viñeta con una máscara invertida y difuminada, un sólido de fundido, y desenfoque de movimiento de composición en las capas del mundo. Nómbralas todas para que sea fácil desactivarlas.
Audio	Pistas separadas (voz, música/efectos) como capas de audio, más las líneas de narración como marcadores de composición

3. Exportar desde la fuente de verdad

Añade una ruta de exportación al renderizador existente en lugar de volver a escribir los números. Por ejemplo, expón sus internos (module.exports, un flag --export, o importando sus módulos) y escribe export_ae.js / export_ae.py. Debe producir scene.json y una carpeta assets/. De esta forma, el proyecto de AE y el MP4 no pueden divergir, y re-exportar tras un cambio de historia es un solo comando.

Para que el movimiento coincida:

• Cámara y otras curvas. Pon fotogramas clave en los momentos significativos (inicio y fin de pausas, aterrizajes), no en cada fotograma. Dale a cada clave la velocidad real de la curva en ese punto con 33.333% de influencia: eso reproduce exactamente una cúbica de Hermite. Cuando un movimiento también hace algo intermedio (un zoom de alejamiento, zoom en espacio logarítmico), añade fotogramas clave en ¼, ½ y ¾ del movimiento con sus propias derivadas. Calcula las derivadas numéricamente a partir de la función de cámara del renderizador.
• Velocidades con signo. Las velocidades de rotación, escala y opacidad tienen signo. Las propiedades espaciales (posición, punto de anclaje) solo toman magnitud.
• Fotogramas clave por fotograma solo son aceptables para cosas genuinamente irregulares, como un parpadeo. Todo lo demás debe ser fácil de agarrar y mover.
• Re-temporización. Lee las temporizaciones del mismo archivo que usa el renderizador (por ejemplo, timings.json), de modo que re-temporizar la voz en off re-temporice el proyecto.

Escribe para la persona que lo abrirá:

• Nombra cada capa por lo que es ("Círculo de tinta (se dibuja sobre 'Punta del halcón')", "Oscurecer mapa (enfoque principal)").
• Pon un comment de una línea en cualquier cosa no obvia.
• Usa etiquetas para agrupar, y dale al null de cámara una etiqueta distintiva.
• Las líneas de narración van como marcadores de composición.

4. Construir y verificar

node <skill>/scripts/make_jsx.js --portable --quiet scene.json build.jsx   # build.jsx se coloca junto a assets/
<skill>/scripts/run_in_ae.sh build.jsx "/abs/path/Mi Proyecto.aep" 1500

• Requisito previo (una vez, en AE): Preferencias → Secuencias de comandos y expresiones → activa "Permitir que los scripts escriban archivos y accedan a la red". Sin ello, el guardado y el registro de construcción fallan. Si el ejecutor agota el tiempo de espera, esta configuración (o un diálogo abierto en AE) suele ser la causa; pídele al usuario que lo verifique.
• No descartará el trabajo. Si el proyecto de AE abierto tiene cambios sin guardar, la construcción se detiene y lo indica en el registro. Nunca evites esto descartando el proyecto del usuario; pídele que lo guarde o cierre. Usa --quiet para construcciones automatizadas para que el mensaje vaya al registro, no a un diálogo que bloquee AE. Regenera sin --quiet para el build.jsx que entregues, para que una persona que lo ejecute manualmente vea el mensaje.
• El registro de construcción (<Proyecto>.build-log.txt) enumera cada capa, efecto o propiedad que falló. Trata cualquier problema como un error en la escena y corrígelo en el exportador, no en AE.
• Stills de verificación. Establece project.stills en 5 a 8 momentos clave: un momento sincronizado con palabras, en medio de una caída, un plano principal, el título. El constructor los renderiza desde la composición principal. Se renderizan de forma asíncrona después del guardado, y el ejecutor espera por ellos. Son PNG de 16 bits que ffmpeg no siempre puede leer, así que visualízalos con sips -s format jpeg -Z 1920 in.png --out out.jpg.
• Compara lado a lado con fotogramas del render original en los mismos momentos. Verifica el encuadre, qué objeto es el principal, si las revelaciones de texto caen en la palabra, y el color y brillo. Luego corrige el exportador y reconstruye. El brillo en AE es mucho más fuerte que una "pantalla de una copia desenfocada" de canvas, así que comienza con un umbral alto (~200 de 255) y una intensidad baja (~0.2).

Si After Effects no está en esta máquina, o la persona que va a editar está en otra computadora, no intentes ejecutarlo. Entrega la carpeta portátil (build.jsx, assets/, scene.json, README). Ellos la ejecutan con Archivo → Secuencias de comandos → Ejecutar archivo de secuencia de comandos… y el .aep se guarda junto a build.jsx. El README debe decirles que activen primero la configuración de escritura de archivos de scripts y que las fuentes deben estar instaladas.

5. Entregar

Entrega una carpeta que contenga:

• <Nombre>.aep
• assets/
• build.jsx y scene.json, para que el proyecto se pueda reconstruir
• el script exportador
• un breve README.md que indique cómo:
  • mover la cámara: fotogramas clave en el Punto de anclaje (hacia dónde mira) y Escala (zoom) del null CÁMARA
  • reemplazar una foto: en el panel Proyecto, selecciona el asset y usa Archivo → Reemplazar material de archivo
  • re-temporizar una palabra: arrastra los fotogramas clave de Revelar de esa capa, o re-exporta después de cambiar las temporizaciones
  • activar/desactivar las capas de aspecto
  • cambiar texto: haz doble clic en él
  • qué fuentes deben estar instaladas

Dile al usuario claramente:

• qué coincide exactamente (diseño, temporización, fotogramas clave)
• qué está aproximado (el brillo, grano y color de AE difieren un poco de la composición en canvas)
• qué verificaste con stills y qué no (por ejemplo, reproducción completa)

Cosas que han salido mal antes

Estas son las razones detrás de las convenciones anteriores:

• Las sombras y desenfoques en capas de forma o texto no escalan con la cámara, porque sus efectos se aplican después de la transformación. Usa sólidos con máscaras para brillos y sombras en el espacio del mundo.
• Las precomposiciones se ven borrosas cuando la cámara hace zoom. Solución: colapsar transformaciones y crearlas al 200%.
• Las máscaras difuminadas se cortan en el borde del sólido. Haz los sólidos de brillo mucho más grandes que el brillo.
• Las fuentes deben ser nombres PostScript. Verifica las desconocidas en AE con una prueba rápida: establece textDocument.font y léelo de vuelta.
• ExtendScript es ES3 y malinterpreta los ternarios encadenados (a ? b : c ? d : e): usa una tabla de búsqueda o if/else en su lugar. Si cambias aelib.jsx, pruébalo primero en una escena pequeña (una capa de texto, una forma, una precomposición) antes de la construcción completa.