yem-hjk6th/explainer-kit

Vidéo explicative

Vous réalisez des vidéos explicatives qu'un spectateur spécifique comprend et qui sont justes. Deux choses déterminent le résultat : les règles dans references/STYLE.md (elles proviennent de retours réels de relecteurs) et l'habitude de calculer et vérifier chaque nombre que vous montrez. Le rendu est la partie facile.

Plan du dépôt : bibliothèque animkit/ (référence API animkit/README.md), outils tools/, exemples examples/, deux épisodes terminés episodes_example/ (copiez leurs formats de storyboard et de plans ; le format REVENDICATIONS est dans references/VERIFY.md), votre travail va dans episodes/<ID>_<sujet>/.

0. Avant toute chose

1. L'environnement fonctionne ? python -I -B -X utf8 tools/selftest.py doit afficher all OK. Si config/animkit.json est manquant, exécutez python -X utf8 tools/setup_config.py (la configuration est propre au checkout : un nouveau clone ou git worktree en a besoin à nouveau, ou définissez ANIMKIT_CONFIG). Problèmes : SETUP.md.
2. Demandez à l'utilisateur uniquement ce que vous ne pouvez pas définir par défaut (un message, court) :
   • le sujet et le matériel source (notes de cours, un article, une page) ; vous avez besoin d'une source pour chaque affirmation ;
   • le public et ce qu'il sait déjà (fixe la profondeur, references/STORYBOARD.md §Public) ;
   • la durée ; version traduite / narration / voix de synthèse souhaitée ?
   • pouvez-vous exécuter de vrais modèles (GPU, téléchargements) ? Par défaut : non, utilisez une scène synthétique avec une vérité terrain connue.
   • Valeurs par défaut si non renseignées : 1080×1440, 30 ips, sous-titres uniquement, pas de voix, une relecture prévue.
3. Créez episodes/<ID>_<sujet>/ avec STATUS.md (étape / prochaine étape / en attente de / temps depuis date).

1. Le pipeline (détails et commandes : references/PIPELINE.md)

Étape	Vous produisez	Garde avant l'étape suivante
A. Étude	digest source ; décomposition vidéo de référence optionnelle (references/REFERENCES.md)	vous pouvez énoncer le mécanisme comme entrée → formule → formes → petit exemple numérique → pourquoi
B. Storyboard	storyboard.md, REVENDICATIONS_a_verifier.md, episode.json (+ elements_necessaires.md si la bibliothèque manque de quelque chose)	accord de l'utilisateur sur le plan pour les longs épisodes ; relecture indépendante tour 1 effectuée et corrections appliquées (references/VERIFY.md)
C. Plans	plans/sNN_*.py, chacun avec @shot.check	--check-only passe ; planche contact inspectée ; rendu complet ; avertissements check.json corrigés
D. Assemblage	rendu/<ID>.mp4 (tools/concat.py), relecture/tour1/relecture.html (tools/review_page.py)	vous avez regardé les planches de chaque plan ; les nombres à l'écran = REVENDICATIONS
E. Tours de relecture	relecture/tourN/retours.md (notes de l'utilisateur), relecture/tourN+1/changements.md, nouveaux rendus	chaque retour est traité ; les nouvelles affirmations sont vérifiées (max 2 tours par élément)
F. Optionnel	version traduite (references/I18N.md), narration (references/NARRATION.md), voix de synthèse (references/TTS.md)	chacune a sa propre vérification

Écrivez les plans directement dans la langue de la vidéo (anglais dans les exemples) : les sous-titres, titres et étiquettes sont des chaînes de caractères simples dans le script. --lang est uniquement pour une deuxième version traduite.

Micro-parcours (≤ 60 s, 1–3 plans). Mêmes étapes, plus légères. Liste de fichiers minimale dans episodes/<ID>_<sujet>/ :

1. storyboard.md : un tableau, une ligne par sous-titre (plage temporelle, sous-titre, ce qui change à l'écran, calculé ou illustratif). Squelette : templates/storyboard_skeleton.md.
2. REVENDICATIONS_a_verifier.md : une ligne par nombre / fait à l'écran (affirmation, source, comment vérifier, mesuré / calculé / inféré / article).
3. plans/s01_<nom>.py à partir de templates/shot_template.py, avec un @shot.check qui vérifie chaque nombre calculé comme la chaîne affichée.
4. Vérification : un nouveau sous-agent avec templates/verifier_prompt.md limité à toutes les lignes REVENDICATIONS ; appliquez ses corrections (ancien libellé barré).
5. Rendu : --check-only → --sheet-only (regardez sheet.jpg) → rendu complet.
6. episode.json + tools/concat.py seulement s'il y a 2 plans ou plus ; tools/review_page.py <EP> --round 1 pour la page de relecture (un tour). Ne sautez pas le tableau des affirmations, le @shot.check, ou l'inspection de la planche contact.

2. Règles qui ne sont jamais optionnelles

• Chaque visuel calculable est calculé (projections, poids d'attention, remodelages, rétro-projections, lignes ajustées) et vérifié dans @shot.check, y compris la chaîne affichée : ck.eq("profondeur à l'écran", f"{z:.3f}", "1.976"). Format à partir de la précision complète ; ne re-arrondissez jamais une valeur affichée. Les visuels illustratifs obtiennent shot.tag("Illustration") ; les dessins en dimension réduite le disent.
• Chaque nombre a une source (article § / tableau / équation, fichier de code officiel + ligne, ou notre propre script) dans REVENDICATIONS_a_verifier.md, étiqueté mesuré / calculé / inféré / article. Les comparaisons indiquent la métrique, l'unité, et si plus bas ou plus haut est mieux ; les pourcentages indiquent leur dénominateur.
• Chaque symbole est défini là où il apparaît, à chaque fois ; les termes que le spectateur pourrait ne pas connaître obtiennent une fenêtre contextuelle (animkit.Popup) qui les explique brièvement et se ferme.
• Un sous-titre = un changement visuel, ≤ 12 mots et pas plus large que le cadre (le rendu avertit ; à 42 px c'est souvent ~8 longs mots par ligne, 2 lignes max), 2–3 s chacun, rien de statique.
• D'abord l'image, puis la formule, éclairée terme par terme, chaque terme coloré ou lié à sa partie de l'image.
• Nos propres tests sont étiquetés comme nôtres (pas l'expérience de l'article) la première fois et avec la même étiquette après.
• Vérification indépendante : celui qui écrit une affirmation ne la vérifie pas ; une correction est une nouvelle affirmation ; au maximum deux tours, puis appliquez telle quelle et vérifiez ponctuellement. L'ancien libellé est barré (~~ancien~~ → nouveau), jamais supprimé silencieusement.
• Aucun fait inventé dans la traduction ou la narration : ils peuvent seulement dire ce que disent les sous-titres / REVENDICATIONS vérifiés.
• Liste de contrôle complète : references/STYLE.md (§A contenu, §B rythme, §C grammaire visuelle, §D avant diffusion, §E retours de relecteurs devenus règles). Lisez-la avant d'écrire le storyboard et à nouveau avant chaque tour de relecture.

3. Style de travail

• Lisez la section API dont vous avez besoin dans animkit/README.md (elle est longue : cherchez l'élément avec grep, puis lisez cette partie). Copiez les motifs du plan le plus proche dans episodes_example/ plutôt que d'inventer des mises en page. templates/shot_template.py est un plan complet minimal.
• Itérez sur un plan avec --still t1 t2 (images PNG) et --sheet-only (planche contact de 12 images) ; les rendus complets en dernier. Regardez la planche vous-même à chaque fois (chevauchements, texte hors du canevas, boîtes = glyphes manquants, sous-titres sur l'image). Les images fixes ne sont pas rafraîchies par les rendus ultérieurs : relancez --still après chaque modification.
• Scènes 3D : animkit/README.md §Scènes 3D (PinholeCam, OrbitCam convention az / el : az=90, el=0 est une vue de côté). Diagrammes 2D tels qu'une vue de côté d'un sténopé : §Vue de côté 2D (Plot2D avec échelle égale).
• Exécutez Python comme python -I -B -X utf8 ; ne modifiez jamais les fichiers de la bibliothèque pendant qu'une autre session rend (references/PITFALLS.md).
• Gardez STATUS.md court et à jour ; enregistrez l'effort dans effort_log.csv (élément,taille,début,fin,render_s,itérations,note).
• Épisodes longs ou nombreux plans : répartissez le travail sur plusieurs sessions / sous-agents comme dans references/DISPATCH.md (budget de contexte ≈ 300k par session principale, ≤ 150k par sous-agent unique, fichier de transition avant de changer).

4. Livraison

Dites à l'utilisateur : le chemin de la vidéo, le chemin de la page de relecture (relecture/tourN/relecture.html, ouvrez dans un navigateur ; elle a une boîte de commentaire par plan et un bouton "copier tout"), ce qui est calculé vs illustratif, ce qui a été vérifié et par qui, les questions ouvertes. Lorsque leurs retours arrivent, sauvegardez-les textuellement comme relecture/tourN/retours.md (une ligne par identifiant de plan, ex. E03-02 : ...), répondez à chacun, et transformez toute préférence générale en une nouvelle ligne dans vos règles locales de l'épisode (ajoutez à un STYLE_locale.md dans episodes/), afin que le prochain épisode commence avec.

Index de référence

Fichier	À lire quand
references/PIPELINE.md	au démarrage ; commandes des étapes, formats de fichiers, gardes
references/STYLE.md	en écrivant le storyboard ; avant chaque tour de relecture
references/STORYBOARD.md	étape B : profondeur du public, formats storyboard + REVENDICATIONS, schémas d'histoire
references/REFERENCES.md	en étudiant les vidéos de référence / articles sources
references/VERIFY.md + templates/verifier_prompt.md	après les REVENDICATIONS, après les exécutions de modèle, après la narration / traduction
references/REVIEW.md	étapes D–E : page de relecture, fichier de retours, tours
references/I18N.md	une version traduite d'un épisode anglais (--lang)
references/NARRATION.md	script parlé par segment visuel
references/TTS.md	voix de synthèse locale, timing, mixage
references/DISPATCH.md	travail multi-session / sous-agent, coût, étiquette de machine partagée
references/PITFALLS.md	quelque chose casse ; avant de modifier la bibliothèque
templates/	prompts pour sessions et sous-agents, fichiers squelettes, un modèle de plan