AnmolChandiok/ae-editable-project

Projet After Effects modifiable à partir d'une vidéo générée par code

L'objectif est d'obtenir un projet qu'un motion designer puisse ouvrir et retravailler comme s'il l'avait construit à la main. Le texte est du vrai texte, les chemins sont des calques de forme, chaque objet est une précomposition nommée, et la caméra est une nulle que l'on peut réanimer. L'inverse est une séquence d'images rendue déposée dans une composition, qui n'est pas modifiable : ne jamais livrer cela comme animation principale.

L'approche comporte trois étapes :

1. Exporter la scène à partir des mêmes données que le moteur de rendu.
2. L'écrire sous forme de scene.json.
3. Laisser After Effects construire le projet lui-même, en exécutant un ExtendScript généré.

Vous n'écrivez jamais un fichier .aep binaire à la main.

données du moteur ──export──▶ scene.json + assets/ ──make_jsx.js──▶ build.jsx ──After Effects──▶ project.aep (+ contrôles d'images)

Scripts fournis (dans scripts/) :

• aelib.jsx : le constructeur qui s'exécute dans After Effects. Il lit la scène et crée les compositions, calques, images clés, masques, effets, caches, marqueurs et pistes audio, puis enregistre le .aep et un journal de construction.
• make_jsx.js : node make_jsx.js [--portable] scene.json build.jsx. Vérifie la scène (ressources manquantes, mauvais parents, ordre des précompositions) et écrit un build.jsx autonome. Avec --portable, les chemins sont relatifs à build.jsx, ce qui permet de zipper le dossier et de l'exécuter sur un autre ordinateur, y compris Windows. À utiliser pour tout ce que vous livrez.
• run_in_ae.sh : run_in_ae.sh build.jsx /abs/path/Projet.aep [timeout]. Sur macOS, exécute la construction dans After Effects installé, attend la fin et affiche le journal.

Lisez references/scene-spec.md avant d'écrire l'exportateur. Il définit chaque champ, les interpolations, les noms d'effets vérifiés et les plages de valeurs, ainsi que les pièges qui font perdre du temps.

Workflow

1. Inventorier ce que la vidéo affiche

Lisez le moteur de rendu et listez tout ce qui apparaît à l'écran et comment cela se déplace :

• Le monde ou l'arrière-plan.
• Chaque objet ou document.
• Chaque texte.
• Le mouvement de la caméra.
• Les moments synchronisés avec les mots ou les battements.
• L'aspect visuel : grain, lueur, vignette, flou de mouvement, fondus.
• L'audio.

Pour chaque élément, notez d'où viennent ses valeurs (constantes, fonctions géométriques, fichiers de synchronisation).

2. Mapper chaque élément à sa forme native dans After Effects

Choisissez la forme qu'un motion designer construirait à la main :

Dans le code	Dans After Effects
Mouvement de caméra dans un monde (translation, échelle, rotation)	Une nulle CAMERA. Point d'ancrage = le point regardé par la caméra, en coordonnées monde. Échelle = zoom. Rotation = roulis. Position = centre de la composition. Associer chaque calque du monde en tant qu'enfant. Alors écran = position + R·échelle·(p − ancrage), ce qui est exactement une transformation de caméra canvas ; les calques du monde conservent donc les coordonnées utilisées par le code.
Tremblement de main, secousses d'impact	Une expression sur la position et la rotation de la nulle, pilotée par des Contrôleurs de curseur nommés d'après leur fonction ("Amplitude tremblement", "Force impact")
Un objet ou document (impression, papier, carte, livre)	Sa propre précomposition contenant une bordure, une photo, du texte, une ombre portée et un solide "Assombrir". Créez-la en 2× et réduisez l'échelle du calque à 50 %. Activez la fusion des transformations. Animez l'apparition sur le calque de la précomposition.
Chemins vectoriels (lignes de côte, règles, cercles, lignes)	Calques de forme, un groupe par élément logique, nommés
Texte	Calques de texte avec la chaîne réelle et le nom de police PostScript. N'utilisez jamais d'images de texte pré-rendues.
Bitmaps générés par le code (photos factices, textures de papier)	Exportez-les en PNG/JPG, nommez-les de manière à ce qu'ils soient faciles à remplacer ("PHOTO — remplacez-moi")
Écriture qui apparaît mot par mot sur la narration	Un calque de texte avec reveal : { times : [...] }. Le constructeur crée des images clés de masque Write-on par mot (mesuré dans AE), et le texte reste modifiable.
Un trait qui se dessine tout seul	Trim Paths avec fin animée de 0 à 100
Claquement / impact	Images clés d'échelle/opacité plus une entrée dans la liste des impacts de la caméra
Focus principal / atténuation des autres	Un solide noir "Assombrir" avec Préserver la transparence à l'intérieur de chaque précomposition, plus un solide d'assombrissement sur l'écran au-dessus de l'arrière-plan, avec des images clés d'opacité
Aspect cinéma	Calques de réglage nommés ("LOOK — Lueur douce", "LOOK — Grain pellicule"), un solide de vignette avec un masque inversé adouci, un solide de fondu, et un flou de mouvement de composition sur les calques du monde. Nommez-les tous pour qu'ils soient faciles à désactiver.
Audio	Pistes séparées (voix, musique/effets) sous forme de calques audio, plus les lignes de narration sous forme de marqueurs de composition

3. Exporter à partir de la source de vérité

Ajoutez un chemin d'exportation au moteur de rendu existant plutôt que de retaper les nombres. Par exemple, exposez ses internes (module.exports, un flag --export, ou importez ses modules) et écrivez export_ae.js / export_ae.py. Il doit produire scene.json et un dossier assets/. Ainsi, le projet AE et la vidéo MP4 ne peuvent pas diverger, et une réexportation après un changement de scénario se fait en une seule commande.

Faire correspondre le mouvement :

• Courbes de la caméra et autres. Placez des images clés aux moments significatifs (début et fin des paliers, atterrissages), pas sur chaque image. Donnez à chaque image clé la vitesse réelle de la courbe à ce point avec 33,333 % d'influence : cela reproduit exactement une cubique d'Hermite. Lorsqu'un mouvement fait aussi quelque chose à mi-parcours (zoom arrière, zoom en espace logarithmique), ajoutez des images clés à ¼, ½ et ¾ du mouvement avec leurs propres dérivées. Calculez les dérivées numériquement à partir de la fonction caméra du moteur de rendu.
• Vitesses signées. Les vitesses de rotation, d'échelle et d'opacité sont signées. Les propriétés spatiales (position, point d'ancrage) ne prennent que la magnitude.
• Images clés par image ne sont acceptables que pour des choses vraiment irrégulières, comme un scintillement. Tout le reste doit être facile à attraper et à déplacer.
• Réajustement temporel. Lisez les synchronisations à partir du même fichier que celui utilisé par le moteur de rendu (par exemple timings.json), afin qu'un réajustement de la voix off réajuste le projet.

Écrivez pour l'humain qui ouvrira le projet :

• Nommez chaque calque pour ce qu'il est ("Cercle d'encre (se dessine sur 'Pointe du Faucon')", "Assombrir carte (focus principal)").
• Ajoutez un commentaire d'une ligne pour tout ce qui n'est pas évident.
• Utilisez des étiquettes pour grouper, et donnez à la nulle caméra une étiquette distincte.
• Les lignes de narration vont dans les marqueurs de composition.

4. Construire et vérifier

node <skill>/scripts/make_jsx.js --portable --quiet scene.json build.jsx   # build.jsx se trouve à côté de assets/
<skill>/scripts/run_in_ae.sh build.jsx "/abs/path/Mon Projet.aep" 1500

• Prérequis (une fois, dans AE) : Réglages → Scripts et expressions → activer "Autoriser les scripts à écrire des fichiers et à accéder au réseau". Sans cela, la sauvegarde et le journal de construction échouent. Si le script expire, ce réglage (ou une boîte de dialogue ouverte dans AE) en est la cause habituelle ; demandez à l'utilisateur de vérifier.
• Il ne supprime pas le travail. Si le projet AE ouvert contient des modifications non sauvegardées, la construction s'arrête et le mentionne dans le journal. Ne contournez jamais cela en supprimant le projet de l'utilisateur ; demandez-lui de sauvegarder ou de fermer. Utilisez --quiet pour les constructions automatisées afin que le message aille dans le journal, pas dans une boîte de dialogue qui bloque AE. Régénérez sans --quiet pour le build.jsx que vous livrez, afin qu'une personne l'exécutant à la main voie le message.
• Le journal de construction (<Projet>.build-log.txt) liste chaque calque, effet ou propriété qui a échoué. Considérez tout problème comme un bug dans la scène et corrigez-le dans l'exportateur, pas dans AE.
• Contrôles d'images. Définissez project.stills sur 5 à 8 moments clés : un moment synchronisé avec un mot, à mi-chute, un plan fixe important, le titre. Le constructeur les rend à partir de la composition principale. Ils sont rendus de manière asynchrone après la sauvegarde, et le script attend leur fin. Ce sont des PNG 16 bits que ffmpeg ne peut pas toujours lire ; visualisez-les avec sips -s format jpeg -Z 1920 in.png --out out.jpg.
• Comparez côte à côte avec des images du rendu original aux mêmes moments. Vérifiez le cadrage, quel objet est au premier plan, si les révélations de texte atterrissent sur le mot, ainsi que les couleurs et la luminosité. Corrigez ensuite l'exportateur et reconstruisez. La lueur dans AE est beaucoup plus forte qu'un "écran d'une copie floutée" dans canvas ; commencez donc avec un seuil élevé (~200 sur 255) et une faible intensité (~0.2).

Si After Effects n'est pas sur cette machine, ou si la personne qui éditera est sur un autre ordinateur, n'essayez pas de le lancer. Livrez le dossier portable (build.jsx, assets/, scene.json, README). Ils l'exécutent avec Fichier → Scripts → Exécuter un fichier de script... et le .aep est enregistré à côté de build.jsx. Le README doit leur dire d'activer d'abord le réglage d'écriture des scripts, et que les polices doivent être installées.

5. Livrer

Livrez un dossier contenant :

• <Nom>.aep
• assets/
• build.jsx et scene.json, pour que le projet puisse être reconstruit
• le script d'exportation
• un court README.md qui explique comment :
  • déplacer la caméra : animer le Point d'ancrage (ce qu'elle regarde) et l'Échelle (zoom) de la nulle CAMERA
  • remplacer une photo : dans le panneau Projet, sélectionnez la ressource et utilisez Fichier → Remplacer les images
  • réajuster un mot : glisser les images clés Write-on de ce calque, ou ré-exporter après avoir changé les synchronisations
  • activer/désactiver les calques d'aspect visuel
  • changer le texte : double-cliquer dessus
  • quelles polices doivent être installées

Dites clairement à l'utilisateur :

• ce qui est correspond exactement (disposition, synchronisation, images clés)
• ce qui est approximatif (la lueur AE, le grain et les couleurs diffèrent un peu du compositing canvas)
• ce que vous avez vérifié avec les images de contrôle et ce que vous n'avez pas vérifié (par exemple, la lecture complète)

Problèmes déjà rencontrés

Ce sont les raisons des conventions ci-dessus :

• Les ombres et les flous sur les calques de forme ou de texte ne s'adaptent pas à la caméra, car leurs effets s'appliquent après la transformation. Utilisez des solides avec des masques pour les lueurs et ombres dans l'espace monde.
• Les précompositions deviennent floues lorsque la caméra zoome. Corrigez avec la fusion des transformations, et créez-les en 2×.
• Les masques adoucis sont coupés au bord du solide. Agrandissez les solides de lueur bien au-delà de la lueur elle-même.
• Les polices doivent être des noms PostScript. Vérifiez les polices inconnues dans AE avec une sonde rapide : définissez textDocument.font et lisez-le en retour.
• ExtendScript est ES3, et il interprète mal les ternaires chaînées (a ? b : c ? d : e) : utilisez une table de correspondance ou if/else à la place. Si vous modifiez aelib.jsx, testez-le d'abord sur une petite scène (un calque de texte, une forme, une précomposition) avant la construction complète.