SkelegonDK/code-explainer-video

Vidéo explicative de code

Parcours animés et narrés de code pour les développeurs. Le spectateur est un ingénieur : montrez du vrai code, nommez les vrais fichiers et fonctions, expliquez pourquoi et comment, ne simplifiez jamais avec des analogies pour non-développeurs.

Stack : le template Code Hike de Remotion (code avec coloration syntaxique qui se transforme entre les étapes), Mermaid pour les diagrammes d'architecture, ElevenLabs pour la narration (le connecteur ElevenLabs, ou l'API avec une clé), et des sous-titres incrustés. Chargez la compétence remotion-best-practices lorsque vous modifiez le code Remotion dans template/.

Fichiers à côté de ce SKILL.md ("le répertoire de compétence") :

• template/ : les fichiers source Remotion copiés dans chaque projet vidéo.
• references/voice.md : à lire à l'étape 8, avant de générer la narration.
• references/long-form.md : à lire en premier lorsque la vidéo dure 15 à 30 minutes ; il divise le travail en chapitres qui passent chacun par les étapes 2 à 9.

1. Intake : trois questions, dans cet ordre, avant tout travail

Posez-les une par une (AskUserQuestion si disponible). Ne les sautez pas et ne les fusionnez pas.

1. Qu'avez-vous besoin de comprendre ? Obtenez la cible (une ligne, un bloc, une fonction, un fichier, un flux ou toute une architecture), et la raison (correction d'un bug, ajout d'une fonctionnalité, revue d'une PR, intégration). Si la réponse est vague ("les trucs d'auth"), lisez d'abord le code, puis proposez 2 à 4 angles concrets parmi lesquels choisir, par exemple "comment une requête est authentifiée de bout en bout" vs "comment les sessions sont stockées et expirent".
2. Combien de temps cela devrait-il prendre ? Proposez : ~30 s (une ligne ou un bloc), 1-2 min (une fonction ou un module), ~5 min (un sous-système ou un flux), 15-30 min (intégration à la base de code, construite en chapitres par des agents parallèles). S'ils ne savent pas, recommandez-en une en fonction de ce que vous avez trouvé à l'étape 1.
3. Ai-je bien compris ? Après avoir lu le code, renvoyez :
   • la seule question à laquelle la vidéo répond, en une phrase ;
   • la durée et le nombre de beats ;
   • le plan : une ligne par beat (ce qui est à l'écran + le point qu'il fait) ;
   • tout ce que vous omettez délibérément. Ne construisez qu'après un oui. Révisez et confirmez à nouveau sur un non. Cette étape existe car la narration coûte des crédits ElevenLabs et les rendus prennent des minutes.

Lorsque vous travaillez sans surveillance (personne pour répondre), choisissez la lecture la plus raisonnable, indiquez-la en haut de votre réponse, et continuez.

2. Recherchez le code avant d'écrire un mot

• Lisez le code réel. Suivez les appels jusqu'à leurs définitions ; n'inférez pas le comportement à partir des noms. Pour une grande base de code, déployez un sous-agent en lecture seule par domaine, si votre agent prend en charge les sous-agents, et ne conservez que leurs conclusions.
• Chaque affirmation dans la narration doit correspondre à un fichier et une ligne que vous avez lus. Conservez un notes.md de affirmation → chemin:ligne pendant vos recherches ; vous l'utiliserez pour corriger les problèmes trouvés à l'étape 7.
• Notez ce sur quoi un développeur pourrait buter : effets de bord cachés, hypothèses d'ordonnancement, chemins d'erreur, configuration qui modifie le comportement, noms trompeurs.

3. Planifiez les beats selon le budget de temps

Un beat est un visuel plus 1 à 3 phrases de narration. La narration tourne à environ 150 mots par minute (2,5 mots/s) ; chaque beat reçoit une pause de fin de 0,6 s.

Budget	Beats	Mots
30 s	3-4	~70
1-2 min	6-12	150-280
5 min	20-30	~700
15-30 min	chapitres de 3-5 min, voir references/long-form.md

Règles des beats :

• Ouvrez avec la question à laquelle on répond et fermez avec un récapitulatif d'une ligne. Pas d'introduction superflue, pas de "dans cette vidéo".
• Architecture d'abord, puis zoom : diagramme, puis le code du point d'entrée, puis la ligne intéressante.
• Expliquez le but, pas les lignes. Chaque beat de code dit à quoi sert le code et comment il se connecte au beat précédent, puis pointe les une ou deux lignes qui comptent. Ne parcourez jamais un bloc ligne par ligne.
• Beats de code : au maximum 16 lignes (le bas du cadre est réservé aux sous-titres) et 80 caractères par ligne. Coupez les lignes non pertinentes et remplacez-les par un commentaire // .... Les beats consécutifs qui montrent le même extrait avec une surbrillance différente s'animent en douceur, donc réutilisez les extraits et déplacez la surbrillance.
• Mettez en surbrillance ce dont parle la narration avec un commentaire Code Hike directement au-dessus : // !mark (ligne suivante) ou // !mark(1:4) (quatre lignes suivantes). Utilisez la syntaxe de commentaire du langage (# !mark en Python).
• Beats de diagramme : Mermaid flowchart avec au maximum 8 nœuds. Utilisez TD pour les chaînes de plus de quatre nœuds. Gardez les nœuds identiques entre les beats de diagramme consécutifs et déplacez uniquement la ligne class X hot, afin que la disposition ne saute pas.
• La narration est écrite pour l'oreille : phrases courtes, dites les identifiants comme le font les développeurs ("la fonction handle-request"), ne lisez pas le code à voix haute symbole par symbole, ne prononcez pas les numéros de ligne.

4. Configuration du projet (une fois par vidéo)

Définissez SKILL_DIR sur le répertoire de compétence, puis :

npx create-video@latest --yes --code-hike explainer && cd explainer
npx remotion add @remotion/media && npm rm twoslash-cdn && rm public/code*
rm src/calculate-metadata/process-snippet.ts src/annotations/Callout.tsx src/annotations/Error.tsx src/ProgressBar.tsx src/ReloadOnCodeChange.tsx
cp -R "$SKILL_DIR/template/." .
command -v mmdc || npm i -g @mermaid-js/mermaid-cli

Twoslash est supprimé délibérément : il marque chaque import non résolu dans un extrait de code comme une erreur rouge. Les fichiers copiés remplacent la composition du template par une pilotée par beats/ :

• scripts/build.mjs transforme beats/ en public/beats/ (audio, diagrammes rendus, manifest.json) et mesure la durée audio de chaque beat.
• src/Main.tsx joue les beats en séquence : titre, code ou diagramme, audio, sous-titres.
• src/annotations/Mark.tsx implémente la surbrillance !mark. src/Captions.tsx synchronise les morceaux de sous-titres tout au long de l'audio de chaque beat.

5. Écrivez les beats

Une paire de fichiers par beat dans beats/, numérotés pour qu'ils se trient (01, 02, … 10) :

• NN.txt : première ligne facultative # <titre à l'écran> (utilisez chemin/vers/fichier.ts:42-60 pour les beats de code, un titre court pour les diagrammes), puis la narration.
• Un visuel : NN.<ext> avec l'extrait de code (l'extension définit le langage de coloration : .ts, .py, .go, …) ou NN.mmd avec un diagramme Mermaid. Mettez en surbrillance un nœud de diagramme avec classDef hot fill:#facc15,color:#000,stroke:#facc15 et class NodeId hot.

Exemple de paire :

beats/04.txt
# src/auth/session.ts:31-44
Les sessions sont renouvelées paresseusement. La vérification d'expiration n'a lieu que lorsqu'une requête arrive, donc une session inactive n'est jamais nettoyée ici.

beats/04.ts
export async function getSession(id: string) {
  const s = await store.get(id);
  // !mark(1:3)
  if (s && s.expiresAt < Date.now()) {
    return renew(s);
  }
  return s;
}

6. Brouillon (aucun crédit)

1. node scripts/build.mjs sans beats/*.mp3 et sans clé écrit un audio de substitution silencieux à la durée estimée et imprime le total. Si c'est plus de 15 % au-dessus ou en dessous du budget, coupez ou ajoutez des beats maintenant.
2. Rendez les images fixes des moments avec le plus de contenu à l'écran, et du moment où chaque surbrillance atterrit (environ 1,5 s après le début d'un beat) : npx remotion still Main out/check.png --frame=<n> --scale=0.5. Regardez-les. Corrigez les lignes qui débordent, les diagrammes illisibles et les surbrillances sur la mauvaise ligne.

7. Vérification indépendante des faits (avant toute génération de narration)

L'auteur d'un script est la pire personne pour le vérifier. Faites-le vérifier par un relecteur qui ne l'a pas écrit, en confrontant chaque affirmation au code. Faites cela même en mode non supervisé.

• Si votre agent prend en charge les sous-agents, démarrez-en un nouveau. Donnez-lui le chemin du dépôt, chaque beats/NN.txt et son visuel, et ce bref, mais pas notes.md ni votre plan, afin qu'il forme sa propre lecture du code :

  Vérifiez ce script explicatif par rapport au code. Listez chaque affirmation factuelle dans la narration et dans les titres à l'écran. Pour chacune, trouvez le code qui la confirme ou la contredit, en suivant les appels jusqu'à leurs définitions. Renvoyez une ligne par affirmation : beat | affirmation | correct / incorrect / invérifiable | chemin:ligne | pourquoi. Signalez également les extraits de code qui diffèrent de la source (autres que les coupes // ... et les commentaires !mark), les titres dont la plage chemin:ligne est erronée, tout élément important concernant ce code que le script énonce de manière trompeuse, et les beats de code dont la narration parcourt les lignes sans dire à quoi sert le code.

• Sinon, faites vous-même une seconde passe : pour chaque affirmation, rouvrez le code cité et vérifiez-le là, pas dans notes.md.

Corrigez chaque affirmation incorrecte, coupez ou adoucissez chaque affirmation invérifiable, et réécrivez les beats ligne par ligne signalés autour de leur objectif. Re-exécutez la construction du brouillon, et renvoyez uniquement les beats modifiés pour une seconde vérification.

8. Voix et rendu

1. Lisez references/voice.md et générez un fichier de narration par beat avec la première option disponible : le connecteur ElevenLabs, une clé API ElevenLabs, un autre fournisseur de synthèse vocale, ou aucun (vidéo silencieuse avec sous-titres). Utilisez une seule voix pour toute la vidéo.
2. node scripts/build.mjs à nouveau. Il utilise beats/NN.mp3 lorsqu'il est présent, donc modifier un beat signifie remplacer uniquement ce fichier.
3. Rendu une fois : npx remotion render Main out/explainer.mp4. Vérifiez que les durées vidéo et audio correspondent (ffprobe -v error -show_entries stream=codec_type,duration -of csv=p=0 out/explainer.mp4) et, sauf si la vidéo est destinée à être silencieuse, que l'audio n'est pas (ffmpeg -i out/explainer.mp4 -af volumedetect -vn -f null - 2>&1 | grep mean_volume ; l'audio de substitution indique environ -91 dB).

9. Avant de remettre

• Regardez, ou au moins écoutez, le premier et le dernier beat ainsi qu'un au milieu. Si un identifiant est mal prononcé, réécrivez-le phonétiquement dans NN.txt et ré-voix uniquement ce beat. Les sous-titres affichent le texte de la narration, donc une réécriture phonétique y apparaît également ; gardez les réécritures lisibles.
• Toute narration qui a changé après l'étape 7 repasse par celle-ci.
• Livrez le mp4 avec un résumé d'une ligne de la question à laquelle il répond. Ne téléchargez ou ne publiez jamais la vidéo nulle part sans autorisation explicite.