jdrurka/explainer-skill

Explainer

Un explicateur sans visage est une voix off sur un monde animé continu, construit en code (une coupe transversale, un mécanisme grossi, une main tenant un objet), avec des légendes en haut et sans musique. Le résultat est un fichier mp4 en 1080×1920.

À lire avant d'écrire :

• script-craft.md : comment le script est structuré (accroche, rebondissement, imagine, mécanisme, retournement, appel à l'action) et rythmé.
• craft-rules.md : ce qui rend les visuels vivants et dimensionnés. Un premier jet compétent enfreint la plupart de ces règles.

La partie difficile est la métaphore visuelle pour chaque temps. La deuxième plus difficile est de garder chaque image en mouvement et éclairée avec de la profondeur. Le code est la partie facile.

Modes

• One-shot (par défaut) : aller du concept à la vidéo finale sans s'arrêter. Prenez vous-même les décisions et rapportez-les à la fin.
• Review : si l'utilisateur demande une relecture ou une approbation, arrêtez-vous deux fois : après le script, et après le storyboard. Révisez selon ses notes et continuez.

Vérification initiale (une fois)

ffmpeg dans le PATH, remotion/node_modules présent (sinon exécutez npm install dans remotion/), et FISH_API_KEY dans le fichier .env (copiez .env.example). Sans clé, construisez tout avec voice --placeholder et dites à l'utilisateur que la dernière étape est une nouvelle exécution de voice suivie d'un rendu.

Structure

projects/<concept>/ (le concept est un slug, comme how-fridges-work) :

• script.txt, storyboard.md
• composition.tsx (pile de calques), timeline.ts (TL), captions.ts, words.ts (généré), scenes/S01.tsx …
• public/vo.wav, vo/ (prise brute et alignement), out/ (rendus, images fixes)

La bibliothèque centrale est remotion/src/core (les scènes l'importent sous la forme ../../../remotion/src/core) :

• makeTimeline → TL.at("phrase"), TL.end("phrase")
• Captions, Drift, Bokeh, Vignette, handheld, Backdrop, Dust, Footnote
• Camera (WorldSvg, camAt, toScreen), Label, Sparks, Snow / Rain
• assouplissements, ramp, keys, rand, polices SANS / MONO

Outils : python3 bin/explainer.py … (exécutez -h)

Commande	Rôle
new <c>	Crée la structure du projet
voice <c> [--voice-id ID] [--speed 1.0]	Prend la voix avec Fish Audio, génère les horodatages des mots → words.ts, plus public/vo.wav à −14 LUFS. Affiche le nombre de mots par minute
voice <c> --placeholder [--wpm 200]	Audio silencieux et timings synthétiques, sans appel API
stills <c> <sec>…	Images fixes à ces secondes → une planche contact dans out/. Examinez-la
studio <c>	Aperçu en direct dans Remotion Studio (pour l'utilisateur)
render <c> [--blur]	Vidéo mp4 à 60 ips dans out/. --blur effectue un rendu à 240 ips et moyenne à 60 ips pour un flou de mouvement (~4× plus lent)
qa <c>	Vérification de fluidité : images figées < 10 %, pas d'arrêt figé ≥ 0,3 s. Quitte avec le code 1 en cas d'échec et nomme chaque période figée

Flux de travail

1. Script. Exécutez new <c>.

   • Si l'utilisateur a fourni un script, utilisez-le mot pour mot (corrigez uniquement les chiffres et symboles en mots).
   • Sinon, écrivez script.txt à partir de script-craft.md : format objet du quotidien par défaut (270–320 mots), format système pour les produits et réseaux. Exécutez sa liste de vérification.
   • Mode review : arrêtez-vous pour approbation.

2. Voix. Exécutez voice <c>, puis vérifiez le nombre de mots par minute affiché (visez 190–215 ; réexécutez avec le --speed suggéré si ce n'est pas le cas).

   • La voix utilise --voice-id, sinon FISH_VOICE_ID, sinon la voix par défaut de Fish. L'ID d'une voix clonée fonctionne de la même manière.
   • Le modèle utilise --model, sinon FISH_MODEL, sinon s2.1-pro.
   • Travaillez à partir de words.ts, pas de script.txt. La voix épelle les nombres, et les TL.at() ainsi que les phrases des légendes doivent correspondre aux mots prononcés.

3. Storyboard (storyboard.md). Remplissez d'abord la section World, puis une ligne par temps. Pour inventer la métaphore d'un temps, demandez ce que le spectateur verrait s'il pouvait :

   • Grossir : une coupe transversale ou une vue éclatée.
   • Radiographier : à l'intérieur de l'objet.
   • Ralentir le temps : une onde qui se propage, une pièce qui bascule.
   • Mesurer : un affichage qui monte ou descend.

   Le scénario "imagine" devient le monde d'excursion, et chaque temps mécanisme revient au schéma principal. Exécutez les vérifications du storyboard.

   • Mode review : arrêtez-vous pour approbation.

4. Construction. Écrivez un fichier de scène par plan du storyboard dans scenes/ et ajoutez chaque scène à composition.tsx.

   • Chaque scène est une fonction pure de t qui retourne null en dehors de sa fenêtre temporelle.
   • Timing : chaque événement est synchronisé avec TL.at("mots exacts"). N'écrivez jamais de secondes brutes.
   • Continuité : les temps qui partagent un schéma vivent dans UNE scène avec UN seul chemin de caméra (A4).
   • Déplacements : chaque scène entre en se déplaçant, chevauchant la sortie de la scène précédente (A2).
   • Préfixez les identifiants SVG par scène.

5. Itération. Exécutez stills aux mots clés de chaque plan et examinez-les par rapport aux règles de conception A et B. Puis exécutez render et qa. Corrigez chaque période FIGÉE dans son propre plan en lui donnant un porteur de mouvement (A1b). Écrivez les phrases de captions.ts à la main : un nom clé en surbrillance (ambre, apparaît quand il est prononcé) par phrase.

6. Livraison. Le render final doit passer le qa (utilisez --blur si l'utilisateur veut un maximum de finition). Donnez à l'utilisateur :

   • le chemin du fichier mp4
   • le script
   • un résumé une ligne par temps du storyboard
   • toute voix de substitution qui nécessite encore une vraie prise

Drapeaux rouges : arrêtez-vous et corrigez

Pensée	Règle
"Un nouveau décor pour ce temps garde la fraîcheur"	C1 : un schéma principal plus 1–2 mondes d'excursion. Comptez-les
"Restez immobile sur le point culminant pour le suspense"	A1c : arrêtez le sujet, gardez la caméra et l'ambiance en mouvement
"Ajoutez une musique de fond, un grain ou un effet au point culminant"	D, B8 : voix uniquement, pas de grain ; la profondeur vient de l'éclairage
"Fondu d'entrée" / "Fondu enchaîné vers la scène suivante"	A2 : entrez, sortez et transitionnez en vous déplaçant
"Le mouvement global maintiendra la vie"	A1b : chaque plan a besoin d'un élément mobile de taille moyenne à 10–60 px/s
"Passer à une caméra plus proche pour ce temps" (même schéma)	A4 : un monde, une caméra ; transmettez les images clés
"Un éclairage uniforme est acceptable, c'est un schéma"	B1 : dégradé vers l'obscurité, contre-jour, vignette
"Teinter l'ensemble quand il s'active"	B4 : propagez à partir de la cause, avec un avant-plan et un flux
"Un rectangle convient pour l'objet"	B2 : une passe d'anatomie ; construisez ce qu'un zoom arrière révélera
"Ça me semble correct, je saute le qa"	E : qa doit RÉUSSIR ; les yeux ne voient pas les arrêts