toon-explainer

Contrat d'activation

Charger lorsque l'utilisateur souhaite un clip explicatif 3D cartoon / cel-shading (couleurs plates, contours noirs, objets qui apparaissent, caméra mobile, grandes légendes), reproduire un style vidéo "Stupy Doo", ou demander d'animer un diagramme dans Blender à partir de texte.

Règles strictes

• Ne jamais générer les visuels avec un modèle d'IA image/vidéo. Le rendu est basé sur de la géométrie 3D + contours Freestyle rendus par Blender.
• Binaire Blender : ~/.local/bin/blender (5.1.x, installation utilisateur). Toujours exécuter en mode headless avec -b -P.
• Le storyboard est la source unique de vérité : storyboard.json (schéma dans references/storyboard-schema.md). Modifier le JSON, re-rendre. Ne jamais modifier manuellement le fichier .blend.
• Toujours inspecter avant de rendre la vidéo complète : lancer le rendu --stills à 3–5 instants, construire une planche contact, la lire, corriger les chevauchements / objets hors cadre.
• Les légendes et l'audio sont traités en post-production (mix.py, captions.py), jamais comme des objets texte Blender.
• Les effets sonores sont calés sur les temps d'action via les références action: dans la section audio, jamais saisis manuellement en secondes si une action existe.
• La narration en espagnol reste neutre ; le texte de l'interface/des légendes suit la langue de l'utilisateur.
• Garder les clips courts : 8–30 s par storyboard. Enchaîner les clips avec ffmpeg concat pour des vidéos plus longues.

Portes de décision

Besoin	Faire
Vidéo narrée	Narration d'abord, légendes calées dessus, puis animation. Voix via voice-video (tts.py) dans audio.narration.
Effets sonores / musique	Section audio : narration, musique, sons avec références action:. Placeholders dans assets/sfx/, sources CC0 dans son README.
Musique fournie	beats.py snap storyboard.json --music track.mp3 --write avant les rendus d'images.
Vérification rapide	--preview --stills t1,t2,t3 (demi-résolution, 8 échantillons).
Rendu final	Pas de --preview ; 1080x1920 par défaut, 30 fps.
Objet non dans les préfabriqués	Préfabriqués : box, plane, cylinder, sphere, panel, panel_row, cable, device, car, charger, transformer, cloud, tree, pole. Sinon primitives ou model (glb/obj).
L'image semble bon marché	Un seul sujet par plan, caméra à 8–13 m, décor avec arbre/poteau/nuage, câbles draw puis flow. Voir references/style-notes.md.
Réglage manuel souhaité	Ajouter --blend, ouvrir out/scene.blend dans l'interface Blender.

Étapes d'exécution

1. Lire references/storyboard-schema.md et references/style-notes.md.
2. Écrire un petit script gen.py qui génère <workdir>/storyboard.json : objets sur un plan au sol à z=0, plans (un sujet chacun), actions, légendes, post, audio.
3. Images : ~/.local/bin/blender -b -P ~/.claude/skills/toon-explainer/assets/build.py -- storyboard.json out --preview --stills 1,3,5. Construire une planche contact avec Pillow et la lire.
4. Corriger le cadrage et le timing dans le JSON. Répéter l'étape 3 jusqu'à ce que chaque plan soit lisible.
5. Vidéo de prévisualisation : même commande avec --preview uniquement. Vérifier out/raw.mp4 avec ffprobe (durée, fps).
6. Audio (si audio présent) : python3 ~/.claude/skills/toon-explainer/assets/mix.py storyboard.json out/mix.wav. Lire la table de repères.
7. Sous-titres + mux : python3 ~/.claude/skills/toon-explainer/assets/captions.py storyboard.json out/raw.mp4 out/final.mp4 --audio out/mix.wav (ou --audio narration.wav sans audio).
8. Final : enlever --preview, réexécuter les étapes 5–7. Ouvrir out/final.mp4 avec xdg-open.

Contrat de sortie

Retourner : chemin de storyboard.json, chemin de out/final.mp4, durée, résolution, et une ligne par plan décrivant ce qui est à l'écran. Rapporter le temps de rendu. Lister tout ce qui n'est pas encore implémenté (synchronisation labiale, concaténation multi-clip).

Références

• references/storyboard-schema.md — Schéma JSON, préfabriqués, actions, conventions de caméra.
• references/style-notes.md — Aspect de référence, problèmes Blender 5, ce qui corrige le rendu bon marché, conception sonore.
• references/external/ — Copies MIT : EL4CTEO blender-stylized-npr, arjun988 camera-cinematography.
• assets/toonlib.py — Bibliothèque bpy (matériaux, préfabriqués, caméra, animations).
• assets/build.py — Storyboard → rendu Blender.
• assets/mix.py — Section audio en un fichier WAV (musique avec ducking, repères d'effets sonores).
• assets/beats.py — Détection de battements + calage des temps d'action.
• assets/sfx/ — Effets sonores de substitution, sources CC0.
• assets/captions.py — Sous-titres ffmpeg + mux audio.
• assets/storyboard.example.json — Exemple de toit solaire, 9 s.