motion-build

Construction Papercut

Construisez chaque épisode à partir de la bibliothèque plutôt que d'écrire un projet Remotion de zéro. Lisez $MOTION_LIB/core/README.md une fois.

Pré-vol

• Installation : Standard ou Complète. Nécessite la bibliothèque, node 20+, npm, ffmpeg, les outils Python (numpy, Pillow, soundfile) et Chrome ou Chromium pour le rendu audio. Testez avec les commandes dans motion-explainer ; si quelque chose manque, exécutez ./install.sh --doctor et confiez à motion-setup.
• Bibliothèque : $MOTION_LIB, sinon la ligne MOTION_LIB= dans ~/.config/motion-explainer/config.env, sinon demandez une fois. Sans bibliothèque du tout, construisez à partir des croquis dans $MOTION_LIB/style/$MOTION_STYLE/remotion/RECIPES.md.
• Chargez d'abord le skill des bonnes pratiques Remotion uniquement pour le moteur Remotion (remotion-best-practices, depuis le plugin Remotion, ou npx skills add remotion-dev/skills -g -y -a <votre id de harnais> ; install.sh --mode standard le fait) et suivez son routage pour le marquage, les sous-titres et le Studio. Pour kyfram, chargez le skill kyfram à la place.
• Nécessite video/STORYBOARD.md et narration/script.json des étapes précédentes.
• Test de fumée de toute la chaîne d'outils : $MOTION_LIB/core/tools/selftest.sh construit examples/hello-reel/ dans un dossier jetable et rend une image fixe.

1. Générer la structure et vérifier le moteur

Le projet d'épisode doit déjà avoir été structuré à partir de l'étape d'absorption / motion-strategy. Vérifiez video/episode.json pour le engine enregistré :

• Si ce n'est pas encore fait, demandez à l'utilisateur (remotion, fframes ou kyfram) et exécutez :

  $MOTION_LIB/new_episode.sh <series-dir> NN-slug CompId [out-name] --engine remotion|fframes|kyfram
  

• Commandes d'aperçu depuis video/ :

  • fframes : cargo run --release -- preview (ou installez le CLI : cargo install --locked cargo-fframes)
  • kyfram : rendez une fois, puis kyfram view out/cache/kyfram/build/<Scene>.lgv (le script compilé : préludes + en-tête généré + votre scène)
  • remotion : npx remotion studio (ou npm run dev)

• fframes : le projet d'épisode est un crate Rust (media/, src/main.rs). Rendez avec cargo run --release -- render ou $MOTION_LIB/core/tools/render.sh.

• kyfram : le projet d'épisode est constitué de scripts .lgv (scenes/, media/fonts/, src/plan.json). Rendez avec $MOTION_LIB/core/tools/render.sh (il met en cache par scène et concatène). Invoquez d'abord le skill kyfram.

• remotion : projet React (src/, package.json). Rendez avec npx remotion render <CompId> out/<out>.mp4 ou render.sh.

2. Planifier : episode.json, voix, timing

À partir du storyboard, remplissez video/episode.json :

• scenes : [["S01Hook", "l1_hook", 0], ["S02Name", "l2_name", "called"], ...] (id de scène, id de ligne de narration, premier mot comme indice ou mot exact).
• banners : {"S01Hook": "TAKEAWAY IN CAPS"}. hook : voir motion-hook. cuts : la colonne Cut du tableau Camera / Cut. bed, whipScene, cutSfx, gaps (temps supplémentaire après une ligne, en secondes).

Exécutez ensuite motion-voice jusqu'à son étape de timing (elle se termine par build_vo.py et timing_md.py). Ensuite, depuis video/ :

python3 $MOTION_LIB/core/tools/stubs.py        # génère les stubs de scène multi-fichiers basés sur le moteur

build_vo.py signale toute scène de moins de 1,2 s ; fusionnez-la dans une voisine. timing_md.py écrit la section Timing de STORYBOARD.md (images absolues et repères de mots), de sorte que les agents n'ouvrent jamais plan.json.

3. Assets

Suivez $MOTION_LIB/style/$MOTION_STYLE/docs/asset-prompts.md : un outil d'image (tout ce qui produit des PNG transparents) pour les arrière-plans et les accessoires statiques complexes, du code pour les personnages, tout le texte, les étiquettes, les jauges, les boutons et l'interface utilisateur. Pas de texte à l'intérieur des images générées. Sans outil d'image, construisez chaque accessoire en code avec le filtre papier ; le style tient le coup. Toiles de fond : utilisez l'ensemble <Backdrop> de la bibliothèque (style/$MOTION_STYLE/remotion/public/bg/backdrops/_sheet.jpg) ; générez-en une nouvelle uniquement lorsqu'un épisode nécessite un endroit que la bibliothèque ne possède pas. La capture d'écran de preuve : node $MOTION_LIB/core/tools/capture.mjs <url> public/proof/x.png, affichée avec le RealShot du kit.

4. Scènes (Architecture multi-fichiers stricte)

NE mettez JAMAIS toutes les scènes dans un seul fichier. Chaque scène doit vivre dans son propre fichier isolé pour permettre le travail parallèle des agents, les tests indépendants et des diffs Git propres.

Vérifiez engine depuis video/episode.json :

Pour Remotion (engine: "remotion")

• Structure de fichiers :
  • src/scenes/<Scene>.tsx (ex. S01Hook.tsx, S02Name.tsx) — exactement un fichier par scène.
  • src/scenes/<Scene>.parts.tsx (optionnel) — pour les sous-composants privés de cette scène uniquement.
  • src/scenes/index.ts — tableau d'enregistrement SCENES géré automatiquement par stubs.py. N'écrivez jamais les corps de scène ici.

1. Construisez S01Hook vous-même d'abord dans src/scenes/S01Hook.tsx, à partir du bloc HOOK. C'est la scène de référence que les agents font correspondre (constantes de repères, la caméra, interpolate limité).
2. Confiez le reste aux agents de scène en parallèle, regroupés par scène (2-3 scènes chacun). Le brief est style/$MOTION_STYLE/remotion/AGENT_BRIEF.md.
3. Propriété des fichiers : un agent n'écrit que src/scenes/<Scene>.tsx, un <Scene>.parts.tsx optionnel et tools/cue_sheet.d/<Scene>.json. Ne modifiez jamais d'autres scènes ou index.ts.
4. Les agents lisent style/$MOTION_STYLE/remotion/CATALOG.md et $MOTION_LIB/core/audio/CATALOG.md.

Pour fframes (engine: "fframes")

• Structure de fichiers :
  • src/scenes/<scene_snake>.rs (ex. s01_hook.rs, s02_name.rs) — exactement un fichier par scène, définissant sa structure et impl Scene for <Scene>.
  • src/scenes/mod.rs — enregistre automatiquement tous les modules de scène via stubs.py (pub mod s01_hook; pub use s01_hook::*;).
  • src/main.rs / lib.rs — ne fait que monter les scènes via Video::define_scenes(). N'écrivez jamais de code de dessin de scène dans main.rs.

1. Construisez s01_hook.rs d'abord comme scène de référence.
2. Confiez les scènes restantes aux agents en parallèle (chaque agent ne possède que src/scenes/<scene_snake>.rs).
3. Lisez style/$MOTION_STYLE/fframes/src/ pour les structures de caméra, de plateau et d'accessoires disponibles au lieu des composants TSX.

Pour kyfram (engine: "kyfram")

• Structure de fichiers :
  • scenes/<Scene>.lgv (ex. S01Hook.lgv) — exactement un script par scène, formes uniquement.
  • Le rendu préfixe $MOTION_LIB/core/kyfram/lgv/core.lgv, style/$MOTION_STYLE/kyfram/PRELUDE.lgv et un en-tête généré (SCENE_ID, BANNER, DUR, FPSR, CAPS, et l'appel scene()), donc une scène n'appelle jamais scene(), ne code jamais en dur sa durée ou ses repères de sous-titres, et ne redéclare jamais un helper.

1. Invoquez le skill kyfram. Construisez S01Hook.lgv vous-même d'abord comme scène de référence, et vérifiez-la avec bash $MOTION_LIB/core/tools/render.sh plus bash $MOTION_LIB/core/tools/qa.sh hook 0-<N> 6 0.3 6.
2. Confiez les scènes restantes aux agents en parallèle (chaque agent ne possède que scenes/<Scene>.lgv), avec le skill kyfram nommé dans le brief.
3. Les agents lisent style/$MOTION_STYLE/kyfram/PRELUDE.lgv pour les jetons et le mobilier (drawRoom, drawHero, drawBanner, drawCaptions), et out/cache/kyfram/build/<Scene>.lgv après un rendu pour le script compilé exact.
4. Le câblage SFX et du fond musical suit le flux Remotion ci-dessous ; render.sh --voice multiplexe public/vo/voiceover.wav dans le mp4 une fois que ce fichier existe.

Règles de construction : 1080x1920, 30 ips, scènes enchaînées dans la série de transitions du kit. Calques globaux : VO et musique <Audio>, la bannière adhésive avec <Boil>, <WordTagCaptions>, <GrainOverlay>. Chaque accessoire est enveloppé dans <Paper>, les entrées utilisent <PopIn>, chaque scène se déroule dans sa caméra de storyboard. Pas d'animations CSS. Gardez les 20 % inférieurs dégagés. Les scènes voisines ne partagent jamais une toile de fond. Le héros par défaut est une créature orange boxy (jeton C.hero #D67354, ombre C.heroLo #A9553B, alias you) ; les accessoires et les pilules de nom distinguent les personnages.

5. Son

Choisissez les SFX par nom depuis $MOTION_LIB/core/audio/sfx/*.js et le fond musical par préréglage depuis $MOTION_LIB/core/audio/beds/*.json. Pour kyfram, invoquez d'abord le skill kyfram et écrivez les lignes SFX par scène dans tools/cue_sheet.d/<Scene>.json ; il possède le même pipeline sonore partagé que fframes et Remotion. Depuis video/ :

python3 $MOTION_LIB/core/tools/cues.py && node $MOTION_LIB/core/audio/render.mjs

cues.py fusionne les lignes des agents dans tools/cues.json et imprime une note si les sons aériens dépassent un par 2,5 s. render.mjs écrit public/audio/music.wav et fx.wav.

6. Rendu

Aperçu : cargo run --release -- preview (fframes), npx remotion studio (remotion) ou kyfram view out/cache/kyfram/build/<Scene>.lgv (kyfram). Rendez uniquement lorsque demandé, toujours via le wrapper — il choisit le moteur depuis episode.json :

$MOTION_LIB/core/tools/render.sh        # -> out/<out>.mp4

Drapeaux : --workers N (défaut 3), --conc N, --force, --keep. Chaque scène est mise en cache, donc après une correction, seule la scène modifiée est re-rendue ; une modification du kit, du plan, de la voix ou des sous-titres re-rend tout. Le premier téléchargement lance le Chrome sans tête de Remotion, et out/cache prend plusieurs Go de ProRes.

Pour corriger ou reconstruire une scène : modifiez src/scenes/<Scene>.tsx, vérifiez-la avec motion-qa, puis exécutez render.sh à nouveau.

7. Récolte (après l'épisode)

python3 $MOTION_LIB/core/tools/harvest.py .       # depuis video/ ; rapport en lecture seule
python3 $MOTION_LIB/core/tools/catalog.py         # régénère les deux catalogues

Promouvez les correctifs du kit, les composants réutilisables, les nouveaux SFX et les motifs récurrents comme décrit dans library/HARVEST.md, et ajoutez une entrée dans library/CHANGELOG.md.

• Lorsqu'un mouvement semble rigide ou flou, consultez $MOTION_LIB/style/$MOTION_STYLE/docs/motion-principles.md pour le principe correspondant et son helper du kit.

Transfert

L'étape suivante est motion-qa, qui lit les images fixes du projet et STORYBOARD.md. Exécutez-la par scène pendant la construction et une fois sur l'ensemble du montage avant le rendu final. Après la publication, motion-strategy exécute l'autopsie.