cassieliang6709/tech-explainer-video

Vidéo Explicative Technique

Trois étapes, chaque étape nécessite l'approbation explicite de l'utilisateur ("peux continuer") pour passer à la suivante. Le paramètre global "faire sans confirmation" ne s'applique pas à ces trois étapes : il s'agit d'un processus de révision spécifique demandé par l'utilisateur pour ce skill. Si l'utilisateur dit "ne fais pas la voix pour l'instant / ne fais rien", on reste dans l'étape actuelle.

Valeurs par défaut (utilisées si rien n'est précisé, à inscrire dans le front matter de script.md) :

• Public : des étudiants qui connaissent Python mais ont presque tout oublié du cours concerné. Style selon references/kepu-style.md : d'abord concret puis abstrait, "si tu devais concevoir...", un schéma physique qui traverse toute la vidéo, maximum 6 nouveaux termes par épisode ; les détails de registres et de code source sont placés dans le chapitre "Avancé" à la fin de chaque épisode.
• Objectif : que le spectateur puisse l'implémenter en PyTorch après visionnage.
• Structure : trois parties : principe mathématique → outils PyTorch nécessaires → codage unifié.
• À l'intérieur de chaque épisode : structure "général → détail → général" : début : la question à laquelle répond l'épisode et la carte des sections ; corps : développement section par section (avec une carte dans le coin montrant la progression, la section courante surlignée) ; fin : une phrase de conclusion par section puis bande-annonce du prochain épisode.
• Durée : 8 à 12 minutes par épisode (modifié par l'utilisateur le 2026-10-24 : moins d'épisodes, moins de publications, moins de risque de dépassement des limites des plateformes). Un sujet fait généralement 2 épisodes, 3 maximum.
• Métaphores : autorisées mais seulement pour un point précis : une fois la phrase dite, on revient immédiatement au sujet principal ; un concept au maximum (règle n°5 de kepu-style.md).
• Voix : voice: volc (voix préconfigurée Volcengine zh_female_vv_uranus_bigtts) ; en l'absence de credentials dans ~/.volc_tts.env, tts.py bascule automatiquement sur edge-tts zh-CN-XiaoyiNeural avec un message d'information.

Étape 0 : Collecte du matériel

Quand l'utilisateur mentionne des notes (ex : Obsidian), les trouver, les lire complètement, et se baser sur leur structure, leurs conclusions et leurs chiffres.

Étape 1 : Plan (donné dans la conversation)

La première ligne est une phrase de cadrage : "Cet épisode permettra à [public cible] de [objectif après visionnage]". Pour chaque épisode, ajouter une ligne d'accroche de couverture + visuel associé (cf. references/cover-guide.md), à soumettre en même temps que le plan.

Écrire un tableau court selon references/outline-template.md : problème résolu par chaque chapitre, nouveaux concepts, code à montrer, durée, ainsi que la répartition en épisodes et ce qui ne sera pas abordé.

Lire d'abord references/kepu-style.md. Concevoir le début, le rythme, la terminologie et la fin selon les "formules" de references/script-guide.md (formule de début, rythme, terminologie et seuil, formule de fin) ; indiquer dans le plan où se situe chaque point culminant.

Pour la partie mathématique, donner d'abord l'objectif du calcul (ex : out_i = Σⱼ aᵢⱼ vⱼ), puis en déduire chaque composant, de sorte que le produit scalaire, le softmax, le scaling apparaissent "parce qu'ils sont nécessaires".

Étape 2 : Code → Script mot à mot → Vérification → Annotation → Version finale

Principe de rédaction : d'abord la motivation du design, puis le mécanisme, enfin le résultat. Donner la priorité à l'explication claire du "problème rencontré → solution voulue par le concepteur → pourquoi ce choix → comment ça marche". On peut ajouter des étapes, des exemples et la précision nécessaire, mais n'introduire à chaque fois que les nouveaux concepts indispensables à la compréhension du principe en cours ; à la première apparition d'un terme nouveau, l'expliquer avec des connaissances existantes ou un exemple concret. Le chapitre "Avancé" s'adapte au niveau de connaissance prérequis de ce chapitre.

1. Écrire le code du tutoriel py/tutorial.py et l'exécuter réellement. Utiliser show(key, value) pour exporter py/values.json. Toutes les valeurs numériques, formes, True/False à l'écran viennent de là.
   • Pour les petits exemples ayant un sens interprétable, définir les poids manuellement. Dans les commentaires du code et la narration, préciser "défini manuellement, dans un vrai modèle ce sont les poids appris".
   • Pour démontrer le "pourquoi", utiliser une comparaison réelle : par exemple, allclose entre l'attention avec et sans softmax, norme de Jacobi du softmax avant/après scaling.
2. Selon references/kepu-style.md et references/script-guide.md, écrire script/script.md (format ci-dessous), puis passer les deux listes de vérification. Chaque ligne "画 :" doit décrire clairement ce que le spectateur voit changer, et ce que cette image aide à comprendre ; d'abord déterminer l'objectif d'expression, ne pas verrouiller l'outil de production. Les images peuvent être réalisées avec Canvas web, Remotion, Manim, Blender ou un outil plus adapté, le choix étant fait après la validation finale. Les images nécessitant des valeurs numériques, du code ou des formes doivent rester cohérentes avec py/values.json et py/tutorial.py. Vérifier la durée par épisode : nombre de caractères des lignes numérotées ÷ 4,5 ÷ 60, ajouter environ 0,5 minute pour les cartes de chapitre et les pauses ; si cela dépasse 12 minutes, ajuster la répartition des épisodes à cette étape (ne pas attendre la fin de la voix-off pour découvrir que c'est trop long).
3. Une fois le brouillon terminé, effectuer successivement la vérification à zéro connaissance, la vérification des faits et la révision linguistique : 3b. Vérification du seuil zéro connaissance (obligatoire) : lancer un autre agent, lui donner uniquement script.md et la consigne "tu sais coder en Python mais tu as presque tout oublié de ce cours". Ne pas lui donner le code ni les notes. Lui demander de marquer phrase par phrase : ① les mots incompréhensibles ou les sauts de raisonnement ; ② les endroits où une phrase introduit trop de choses nouvelles et nécessite de revenir en arrière ; ③ les incohérences entre la description visuelle et la narration. Exiger d'indiquer précisément quelle étape d'explication manque, en vérifiant surtout si l'on peut suivre la logique "problème → motivation → mécanisme → résultat". L'agent peut suggérer d'ajouter des étapes, des exemples ou la précision nécessaire, mais sans introduire de concepts nouveaux sans rapport avec le fil principal. Après correction ligne par ligne, relancer la vérification dans les mêmes conditions jusqu'à ce qu'il n'y ait plus de marques de type ① ou ② ; les marques de type ③ doivent également être corrigées. Consigner la liste des modifications et la donner à l'utilisateur lors de la livraison. Le chapitre "Avancé" s'adapte au niveau de connaissance prérequis de ce chapitre. 3c. Vérification des faits (obligatoire) : lancer un autre agent, lui donner script.md et les notes. Lui demander de ne marquer que les erreurs factuelles ou les affirmations qui pourraient induire en erreur, en précisant la raison de l'erreur. Ne pas exiger d'ajouts de connaissances, de conditions aux limites ou de détails supplémentaires. Les simplifications pédagogiques sont autorisées. Si les spectateurs pourraient prendre une simplification pour une définition stricte, ajouter brièvement dans la narration "c'est une simplification". Pour corriger, privilégier des formulations tout aussi simples mais exactes, sans accumuler les qualificatifs. En cas de conflit avec 3b, chercher une expression à la fois exacte et compréhensible ; ne pas conserver d'erreur factuelle, ne pas laisser la précision submerger le fil conducteur de l'explication. Si une correction factuelle affecte la compréhension ou l'image, refaire la vérification 3b correspondante. 3d. Utiliser le skill humanizer-zh pour réviser phrase par phrase les lignes numérotées et les lignes "读:" (éliminer le style IA). Conserver le sens des valeurs numériques, des termes, du code et des lignes "画:". Ne pas ajouter ou supprimer de points de contenu arbitrairement. Après la révision, vérifier la cohérence entre les résultats du code, les descriptions visuelles et la narration, puis recalculer la durée de chaque épisode.
4. Envoyer le fichier à l'utilisateur (SendUserFile), en lui demandant d'écrire des annotations sous chaque phrase en commençant par > (ou > [!批注] dans le format Obsidian). Si l'utilisateur souhaite annoter dans Obsidian, copier le fichier dans son vault, le laisser modifier, puis le relire.
5. Traiter les annotations : modifier point par point → supprimer les lignes d'annotation traitées → lister dans la conversation comment chaque annotation a été prise en compte → demander à nouveau à l'utilisateur, jusqu'à ce qu'il valide la version finale.
6. Avant la version finale, ne pas faire la voix-off ni les images de production. Pour vérifier la faisabilité d'un plan complexe, on peut faire un court prototype ; le prototype ne remplace pas la révision du script.

Format de script.md

---
title: Attention → MHA → GQA
subtitle: Des principes mathématiques à l'implémentation PyTorch
audience: Étudiants avec quelques bases en informatique
voice: volc
volc_speaker: zh_female_vv_uranus_bigtts
volc_resource: seed-tts-2.0
episodes: ch0,ch1,ch2,ep1_end | ep2_start,ch3,ch4,ep2_end | ep3_start,ch5,ch6
episode_titles: Titre du premier épisode | Titre du deuxième épisode | Titre du troisième épisode
---

## ch0 | Ouverture
1. Texte original des sous-titres, une phrase par rythme d'image.
   - 读 : Prononciation TTS (à écrire uniquement si différente du sous-titre ; les symboles sont écrits en toutes lettres, le caractère polysémique 行 (háng) s'écrit comme 航)
   - 画 : Ce qui apparaît à l'écran pour cette phrase (obligatoire, l'agent visuel l'implémente)
> Annotation : écrite par l'utilisateur ici

## ep1_end | Bande-annonce du prochain épisode
1. Le prochain épisode parlera de…
   - 画 : Carte de fin de EP1

• Identifiants de chapitre : ch0, ch1, … ; les cartes de début/fin d'épisode utilisent epK_start / epK_end. Les visuels sont générés automatiquement par le composant EpCard générique. Les nouvelles phrases doivent également être soumises à l'utilisateur.
• Structure “général → détail → général” : epK_start écrit 2–3 phrases : ① la question à laquelle répond l'épisode, ② "Cet épisode abordera N sujets : …" (correspondant un à un aux chapitres de l'épisode). epK_end écrit 2–3 phrases : une conclusion par chapitre + bande-annonce du prochain épisode. Le chapitre d'ouverture (ch0) du premier épisode doit également contenir la carte de l'épisode. Le episodes du front matter détermine quelles sections sont sur la carte ; le nom de chaque section est le titre du chapitre correspondant.
• Les sous-titres n'ont pas besoin d'être découpés manuellement ; tts.py les découpe automatiquement en segments de ≤22 caractères selon la ponctuation.

Étape 3 : Génération de la vidéo

Pour chaque plan, choisir le mode de production qui explique le mieux le principe : relations 2D, code et données avec Canvas web, Remotion ou Manim ; structures spatiales et mouvements de caméra avec Blender ou autre outil 3D. On peut aussi utiliser un nouvel outil plus adapté, sans alourdir l'explication par l'usage d'un outil particulier. Le dossier template/ contient la chaîne de composition Remotion et de livraison ; les plans réalisés avec d'autres outils sont d'abord exportés en vidéo ou en images, puis on vérifie qu'ils peuvent s'intégrer à cette chaîne tout en restant synchronisés avec les sous-titres, la voix et le rythme, avant de les utiliser dans les chapitres officiels. Les composants, chemins et commandes des references/visual-guide.md et references/agent-brief.md ne s'appliquent qu'aux chapitres Remotion. Les autres outils conservent leurs propres principes de mise en page, couleurs, données réelles et auto-vérification visuelle.

1. Copier template/ dans le répertoire spécifié par l'utilisateur (par défaut ~/Videos/<sujet>, demander d'abord). Y placer py/ et script/. Une seule installation des dépendances : pour une série (plusieurs projets dans le même répertoire parent, ex : ~/Videos/nudgecode-algo/<chapitre>/), installer les node_modules une seule fois dans le parent (copier le package.json du template, npm install), puis chaque projet fait ln -s ../node_modules node_modules. Pour un seul projet, installer dans le projet. npm install ne doit être lancé qu'une seule fois à la fois ; le parallélisme corrompt l'installation. Après installation, vérifier que node_modules/react-dom/index.js existe (ce package a déjà été corrompu dans le cache npm ; si des fichiers manquent, copier une version identique depuis un autre projet).
2. python3 tools/md2json.py (refuse s'il y a des annotations non traitées) → python3 tools/scaffold.py → python3 tools/tts.py Génère public/audio/* et src/timeline.json. La voix est mise en cache ; seules les phrases modifiées sont resynthétisées.
3. Faire d'abord l'ouverture et le chapitre 1 pour établir le style visuel (faire d'abord le plan le plus difficile ; pour le rythme et les transitions, se référer à references/plotome-lessons.md). Les plans Remotion sont vérifiés avec node tools/stills.mjs ch1 && tools/sheet.sh ch1 ; les plans faits avec des outils externes sont vérifiés via leurs sources et les frames composites après intégration. Envoyer la preview à l'utilisateur. Si le style visuel a déjà été approuvé par l'utilisateur dans la série (ex : premier projet de la série), ne pas demander à nouveau, continuer directement. stills.mjs réutilise out/bundle (via tools/bundle.mjs, ne re-packe que si les sources ont changé), au lieu de créer un nouveau dossier de ~90 MB dans $TMPDIR à chaque exécution.
4. Après approbation de l'utilisateur, répartir les chapitres restants entre plusieurs agents lancés simultanément dans un seul message (1–2 chapitres par agent) :
   • Pour les chapitres Remotion : remplir references/agent-brief.md dans le fichier AGENT_BRIEF.md à la racine du projet, copier references/visual-guide.md en VISUAL_GUIDE.md. Pour les plans d'outils externes, écrire une brève description de la tâche, en définissant le format des sources, la durée, le chemin du fichier et la responsabilité d'intégration dans Remotion. Ne pas imposer la restriction de ne modifier que ChN.tsx.
   • Si la narration change, envoyer un SendMessage aux agents concernés, en précisant quelles phrases ont changé et que la timeline a été mise à jour.
5. Une fois tous les chapitres reçus, la session principale vérifie les frames composites chapitre par chapitre : chevauchements, superposition des sous-titres, cohérence entre l'image et la description "画:", cohérence des valeurs avec values.json ; pour les sources externes, vérifier la durée et le rythme après import.
6. Après validation par npx tsc, lancer tools/render.sh en arrière-plan : pour chaque épisode, sortie de out/epK.mp4 + out/epK.srt + out/covers/epK.jpg, normalisé à -16 LUFS. Environ 1 minute de rendu par minute de vidéo. Ne pas toucher à l'audio ni au code pendant le rendu : le mixage lit l'audio à la dernière étape ; une modification en cours mélangerait l'ancien et le nouveau. render.sh utilise un verrou machine entier (lockf /tmp/remotion-render.lock) pour garantir qu'un seul épisode est rendu à la fois : lancer plusieurs rendus simultanés ne les accélère pas (le CPU est déjà saturé), cela ne fait que consommer plus de mémoire et de disque. Plusieurs projets peuvent lancer render.sh en même temps ; ils se mettront automatiquement en file d'attente.
7. Couverture : selon references/cover-guide.md, pour chaque épisode écrire src/covers/CoverEpK.tsx et l'enregistrer dans src/covers/index.ts (fond noir, accroche en gros caractères + surlignage jaune, grand visuel à droite) ; render.sh génère automatiquement out/covers/epK.jpg. Les épisodes non enregistrés utilisent une version par défaut. Assembler toutes les couvertures en une seule image et la soumettre à l'utilisateur. Pour régénérer une couverture individuelle : npx remotion still out/bundle cover-epK out/covers/epK.jpg.
8. Livraison : utiliser SendUserFile pour envoyer les mp4, srt, couvertures et py/tutorial.py de chaque épisode. Demander à l'utilisateur de lire les srt une première fois, cela permet souvent de repérer des problèmes.
9. Si nécessaire, passer au skill video-publish. Avant publication, vérifier la checklist de conformité de references/plotome-lessons.md (marquage IA, licence musicale, crédits).

Production en série (projets parallèles)

• Maintenir 3–4 sessions simultanées : en ouvrir trop conduit rapidement à une limite d'utilisation, et le TTS Volcengine déclenchera aussi une limite de concurrence (tts.py intègre déjà une attente avec retry et une concurrence de 2).
• Le parallélisme ne concerne que la rédaction et la production des images ; le rendu est confié à render.sh avec son verrou machine pour la file d'attente.
• Disque : chaque chapitre out/bundle ~90 Mo, les captures d'écran out/check quelques dizaines de Mo, les fichiers vidéo finaux ~15 Mo par épisode. Avant de lancer un nouveau lot, vérifier df -h. Les fichiers $TMPDIR/remotion-webpack-bundle-* sont des restes de versions précédentes et peuvent être nettoyés.
• Quand l'utilisateur accepte le processus "rendre un lot → uploader directement → supprimer les fichiers vidéo", se référer à la section "Pipeline par lots" du skill video-publish.

Pipeline de la session principale (base de connaissances expérimentée du 30-10 au 03-11, deux articles par lot)

1. Agent de rédaction (un par article, deux simultanément) : plan → exécution réelle du tutoriel → export de values.json → script mot à mot → vérification à zéro connaissance (autre agent, max 8 tours, correction complète après le dernier tour) → vérification des faits (autre agent avec les notes) → humanizer-zh → vérification de la durée par épisode → copie du template, lien symbolique vers node_modules → md2json / scaffold / tts → écriture de AGENT_BRIEF.md, VISUAL_GUIDE.md, composant partagé du schéma physique src/lib/<nom>.tsx (d'abord définir les constantes de layout) → faire ch0, ch1. Le rapport doit lister les "incohérences entre les notes et les mesures réelles".
2. La session principale examine les visuels de ch0/ch1. Si le style convient, continuer, sans attendre l'utilisateur.
3. Distribution des plans visuels : remplir references/agent-brief.md en un brief partagé et l'écrire dans /tmp/claude-501/brief_<article>.txt (pour le deuxième article, utiliser sed pour remplacer chemins/noms de composants/verrous, puis ajouter "compléments spécifiques à ce projet"). Le prompt de chaque agent consiste uniquement en "Lis d'abord le brief en entier avec Read et suis-le strictement. Tu es responsable de chX, chY", 2–3 chapitres par agent, la couverture étant confiée au dernier agent. Les lancer tous simultanément dans un seul message.
4. Collecte des problèmes connus : quand chaque agent visuel revient, noter les problèmes qu'il remonte ("problemes connus / valeurs absentes de values.json / modifications non revues").
5. Agent de révision complète (un par article, modèle references/review-brief.md) : reporter ligne par ligne les problèmes de l'étape 4 dans la section "problèmes à corriger".
6. Rendu : lancer tools/render.sh en arrière-plan pour chaque article ; le verrou machine gère la file d'attente. Utiliser une boucle until en arrière-plan pour attendre l'apparition de out/ep3.mp4.
7. Contrôle par sondage (fait par la session principale, ne pas se fier aux rapports) : pour chaque épisode, ffmpeg -af volumedetect (normal : mean ~ −19 dB, max ≤ −1.2 dB). Pour un épisode par article, créer une grille de captures avec -vf "fps=1/60,scale=480:-1,tile=4x3" et la lire avec Read. Vérifier que les trois fichiers out/covers/ sont présents.
8. Upload : créer un lien dur out/parts/P<k> <accroche> : <sujet>.mp4 + out/upload_meta.md (contenant un paragraphe supplémentaire de description courte), puis suivre la procédure du skill video-publish pour "ajouter à un contenu existant". Après upload, mettre à jour PROGRESS.md et le tableau de bord, envoyer les paragraphes de description à l'utilisateur.

Limite d'utilisation / Interruption

• La limite d'utilisation tue tous les agents en cours. Après rétablissement, envoyer SendMessage à chaque agent avec "continue" ; il reprend avec le contexte. Ne pas ouvrir de nouveaux agents (cela provoquerait des doublons et des conflits).
• Limiter le nombre d'agents simultanés à environ 12 (2 articles × 5–6 agents visuels).

Notes vs mesures réelles

• Les notes du vault sont en lecture seule. En cas de divergence entre mesures réelles et notes, la vidéo suit les mesures réelles. Le rapport liste chaque divergence point par point à l'utilisateur, qui décide s'il faut corriger les notes.

Modifications après validation

• Modifier la narration : modifier script.md → md2json → tts (ne resynthétise que les phrases modifiées) → vérifier les chapitres concernés.
• Un changement dans le nombre de phrases provoque un décalage des images : pour les chapitres déjà en images, ne modifier que le wording sans ajouter ni supprimer de phrases. Pour ajouter du contenu, le faire sous forme d'une nouvelle phrase/chapitre (ex : epK_start).
• L'agent visuel se contente d'implémenter selon visual. En cas de doute, il reporte à la session principale, il ne modifie pas la narration.

Voix

• Voix préconfigurée Volcengine (par défaut, voice: volc) : zh_female_vv_uranus_bigtts, ressource seed-tts-2.0. C'est la voix choisie par l'utilisateur pour l'épisode GQA, nettement meilleure que edge-tts. Si volc_speaker n'est pas dans le front matter, c'est celle-ci qui est utilisée. Les credentials se trouvent dans ~/.volc_tts.env (déjà configuré), besoin uniquement de VOLC_APPID / VOLC_TOKEN. Optionnel : VOLC_SPEED (1.0 = normal).
• Changer de voix : écrire volc_speaker: <ID de voix> dans le front matter. Les voix préconfigurées utilisent automatiquement seed-tts-2.0. Les voix clonées commençant par S_ utilisent automatiquement seed-icl-2.0 (ou VOLC_RESOURCE dans l'environnement). On peut aussi spécifier volc_resource explicitement ; écrire v1 pour utiliser l'ancienne interface, auquel cas on peut également définir VOLC_CLUSTER (par défaut volcano_icl).
• La voix clonée de l'utilisateur (VOLC_SPEAKER_ID dans l'environnement, commençant par S_) déclenche actuellement l'erreur resource ID is mismatched with speaker. Avant de l'utiliser, vérifier dans la console Volcengine la version de la voix, son statut d'entraînement et l'ID d'application associé.
• Ne pas imprimer le contenu du fichier d'environnement. Pour un nouveau projet, d'abord synthétiser quelques phrases d'un épisode avec --only pour écouter, puis produire l'épisode complet.
• edge-tts (alternative) : voice: zh-CN-XiaoyiNeural. Autres options : YunxiNeural, YunyangNeural, XiaoxiaoNeural. En l'absence de credentials Volcengine, tts.py utilise automatiquement Xiaoyi.
• Changer de voix ne nécessite que de relancer tts.py. Les images se recalent automatiquement sur le nouveau rythme ; vérifier avec un collage d'écran.

Voix en anglais (2026-11-03)

• edge-tts en-US-AndrewMultilingualNeural : choisie par l'utilisateur après écoute de 9 voix. Gratuite, sans clé, mais passe par l'interface non officielle de Edge Reader : peut être débitée ou déconnectée, pas claire pour un usage commercial, et peut changer du jour au lendemain. Front matter : voice: en-US-AndrewMultilingualNeural.
• Autres options Volcengine seed-tts-2.0 : en_male_tim_uranus_bigtts, en_female_dacey_uranus_bigtts (alternatives). Les voix anglaises seed-tts-1.0 avec *_mars_bigtts renvoient une erreur 403 sur ce compte (non activées). La voix chinoise vv peut aussi lire de l'anglais, mais avec un accent marqué.
• Pour une écoute comparative : produire un mp3 d'environ 20 secondes du même extrait d'ouverture en anglais pour chaque voix, puis les concaténer avec ffmpeg concat (avec un silence de 1,2 s entre chaque) en un seul fichier pour l'utilisateur.

Bilingue chinois-anglais (phase pilote)

• Projet pilote : ~/Videos/basedeconnaissances/llm-13-rag-agent-en : narration en anglais oral nouvellement écrite (pas une traduction du chinois), chaque phrase avec traduction chinoise, sous-titres sur deux lignes en bas (anglais au-dessus, chinois légèrement plus petit en dessous), étiquettes visuelles en anglais.
• Les modifications du composant de sous-titrage et de md2json seront documentées ici et dans le template une fois le pilote terminé.
• La version anglaise ne doit pas être ajoutée à une compilation chinoise. Le lieu de publication (nouvel article sur Bilibili / YouTube) est décidé par l'utilisateur.

Liste des fichiers (template/)

Fichier	Rôle
tools/md2json.py	script.md → script.json (vérifie les annotations, analyse les épisodes)
tools/scaffold.py	Génère les composants de placeholder pour les chapitres et src/chapters/index.ts
tools/tts.py	Voix-off phrase par phrase, découpage des sous-titres, écriture de timeline.json ; supporte edge-tts / Volcengine
tools/stills.mjs + sheet.sh	Capture d'écran à 80% de chaque phrase et assemblage en grille 3×3
tools/render.sh	Rendu épisode par épisode + fusion des sous-titres + normalisation du volume
src/lib/beat.tsx	Synchronisation des temps (useBeat), cartes de titre de chapitre, sous-titres
src/lib/ui.tsx	CodePanel / Matrix / Fade / Tag / H / Tex (formules KaTeX)
src/lib/EpCard.tsx	Cartes de début/fin d'épisode
src/lib/Cover.tsx + src/covers/	Composants de couverture (CoverFrame / Hl / CodeVisual / BigNumber) + enregistrement des couvertures personnalisées
src/lib/algo.tsx	Composants d'algorithmes : grille de tableaux, dict, table de trace, carte d'énoncé
tools/bundle.mjs	Empaquetage unique réutilisant out/bundle
src/lib/library.tsx	Optionnel : composants de métaphore "bibliothèque" de tenseurs (Building / Corridor)

Documents de référence

• references/script-guide.md : guide d'écriture du script ; outline-template.md : tableau de plan
• references/visual-guide.md / agent-brief.md : normes visuelles, instructions pour les agents visuels
• references/cover-guide.md : normes de couverture
• references/plotome-lessons.md : rythme, transitions, musique, conformité (inspiré de plotome)
• references/production-retro-2026-10.md : retour d'expérience sur la production en série de 13 chapitres de nudgecode, pièges et solutions
• references/production-retro-2026-11.md : retour d'expérience sur le pipeline de deux articles par lot pour la base de connaissances
• references/review-brief.md : modèle pour l'agent de révision complète
• rethinkfun-style.md / cishoon-style.md : analyse des créateurs préférés de l'utilisateur

Pièges rencontrés

• say sur macOS est trop mécanique, utiliser edge-tts.
• Le code et les symboles doivent être écrits en toutes lettres dans les lignes "读:" ; le caractère polysémique 行 (háng) s'écrit comme 航.
• Avant de donner des chiffres sur un modèle réel, vérifier sa structure (ex : Llama-2-70B utilise déjà GQA ; si on le traite comme MHA avec 64 têtes et 10 Go, préciser "en supposant MHA").
• L'attention initialisée aléatoirement est trop uniforme, sans intérêt. Soit définir les poids manuellement, soit changer de graine aléatoire pour obtenir un contraste net.
• Les captures d'écran avec tools/stills.mjs (un seul empaquetage) sont bien plus rapides que remotion still. Le premier rendu télécharge headless Chrome.
• Dans Bash, ne pas écrire cat > fichier sans entrée, cela attend le stdin et bloque.
• Les captures à 80% de chaque phrase : les animations qui apparaissent après 80% (croix rouges, grands caractères tardifs) ne sont pas capturées ; il faut les capturer séparément ou avancer leur apparition.
• Quand les agents visuels sont parallélisés, une erreur de syntaxe dans un autre chapitre peut faire échouer le bundle. Attendre 1–2 minutes et réessayer ; ne pas modifier les fichiers des autres.
• Un agent de révision a déjà "nettoyé" les anciennes captures : le brief doit impérativement mentionner "ne supprimer aucun fichier (l'écrasement des captures est accepté)".
• Disque : chaque projet d'article ~0,5 Go, fichiers finaux ~15 Mo par épisode ; un disque plein pendant le rendu provoque l'erreur No space left on device. Avant de lancer un nouveau lot, exécuter df -h. Si l'espace est inférieur à ~15 Go, lister les éléments nettoyables (caches des outils, conda clean, etc.) et les soumettre à l'utilisateur ; la suppression nécessite son accord.
• Les cartes de titre de chapitre et de début/fin d'épisode ajoutent environ 10 secondes par épisode. Estimer la durée finale à durée TTS réelle + 10 secondes.
• Les agents visuels enregistrent spontanément src/covers/index.ts : c'est nécessaire pour les couvertures, autorisé.
• En arrière-plan, ne pas utiliser pgrep -f render.sh pour attendre le rendu : la commande d'attente elle-même contient ce motif, donc pgrep se trouve toujours lui-même, et attend pendant des heures. Attendre simplement l'apparition de out/epK.mp4 (ou une erreur dans les logs).