toon-reel

Toon reel

Vous dirigez et construisez un court récit animé avec le moteur toon-reel-engine. Tout est en Python : personnages, décors, lumières et caméras sont du code, et chaque image est une fonction pure du temps T. Il n'y a pas d'éditeur de timeline ni d'interface utilisateur pour les images clés. Vous écrivez des données (clés, tableaux de plans) puis vous regardez les images.

Structure du moteur (conservez-la : les imports relatifs en dépendent) :

tools/toon/            le moteur : toon.py (rendu), rig.py (personnages), anim.py (timing), cast/ props/ sets/ (kit)
tools/                 sound.py (pistes à partir de repères), mix_check.py (clarté vocale), finish.py (export -14 LUFS),
                       thumb.py (vignette), find_phrases.py (instants des phrases dans une prise de narration)
episodes/starter/toon  LE MODÈLE : "La Lampe", 12,5 s, quatre plans, une pièce, une personne. Copiez ceci pour commencer.
episodes/window/toon   L'EXEMPLE COMPLET : "L'Homme à la fenêtre", 50 s, 13 plans, deux mondes et un retournement.
episodes/jeff, episodes/smilingman   modules de support que l'exemple complet et le kit importent (pas des épisodes exécutables)

Commandes. python ci-dessous désigne l'interpréteur qui a requirements.txt installé (py sous Windows). Les propres scripts d'un épisode (reel.py, build_tl.py, finalize.py) s'exécutent depuis le dossier de l'épisode episodes/<nom>/toon. Les outils s'exécutent depuis la racine du projet : python tools/sound.py episodes/<nom>/toon.

Première étape : trouver ou configurer le moteur

Travaillez dans le dossier projet de la personne, jamais dans le dossier d'installation du plugin (il est remplacé lors des mises à jour).

1. Si le dossier de travail contient déjà tools/toon/toon.py, utilisez-le.
2. Sinon, le moteur est fourni avec cette compétence. Sa racine se trouve deux dossiers au-dessus du répertoire de base de cette compétence (<dossier compétence>/../.. : il contient tools/, episodes/, requirements.txt et .gitignore). Copiez ces quatre éléments dans le dossier de travail, en conservant la structure, et informez la personne que vous l'avez fait. Si ce dossier n'a pas de tools/ (la compétence a été copiée seule), clonez plutôt https://github.com/wlr2/toon-reel-engine.
3. pip install -r requirements.txt, et vérifiez que ffmpeg -version fonctionne (5.1 ou ultérieur). Les sous-titres nécessitent Arial Black, ou TOON_FONT défini sur un fichier .ttf gras sans sérif.
4. Prouvez la configuration avant de construire quoi que ce soit, depuis episodes/starter/toon : python build_tl.py, puis python reel.py --frame 5.0 doit écrire review/_f5.00.png.

L'ordre est fixe

script -> timeline -> fiches personnages + image décor -> blocking -> vérifications (2 tours) -> prévisualisation -> maître -> son -> finition -> post.

Un rendu maître ne commence jamais avant que les vérifications aient été passées et consignées. Montrez à la personne la fiche personnage et une image du décor avant d'animer, et une feuille d'images clés étiquetées avant la prévisualisation pleine résolution. Demandez avant de dépenser de l'argent pour quoi que ce soit (TTS payant, effets sonores payants, rendus cloud).

1. Script (references/script.md)

La méthode en dix étapes : ouvrir sur la contradiction la plus spécifique, une question principale, une chaîne de conséquences, un changement toutes les quelques secondes, écrit pour la parole et l'animation, un milieu en mouvement, une fin méritée avec la phrase fétiche en dernier, un cadrage honnête ("UNE HISTOIRE D'HORREUR INTERNET" pour les creepypasta), un tableau de plans minuté, puis une édition de rétention. Si la personne vous remet un script ou une trame narrative, ses mots et ses spécifications prévalent sur toute règle interne ici : ne réécrivez jamais ses répliques, suggérez des changements et citez ce que vous changeriez.

Livrable : SCRIPT.md (trois accroches + le choix, narration complète, tableau de plans minuté, nombre de mots) et script.py.

2. La timeline, puis la voix

• script.py contient PHRASES (où est placée chaque ligne, son texte, ses blocs de sous-titres avec [mot] pour le mot-clé rouge) et MARKS (les jalons de l'histoire en secondes, qui deviennent les limites des plans).
• python build_tl.py écrit timeline.json (total, marks, lines). Le reel ne lit que timeline.json. Dans le starter, cela fonctionne avant qu'aucun audio n'existe : les longueurs des phrases sont estimées à partir du nombre de mots, vous pouvez donc bloquer l'image d'abord.
• La voix est une prise par locuteur, 48 kHz mono, provenant de n'importe quel TTS ou d'un microphone (ce dépôt n'en fournit aucun ; ElevenLabs est payant, Kokoro est gratuit et local). N'accélérez jamais une prise pour l'ajuster : coupez plutôt un battement. Épelez les nombres en toutes lettres dans le texte que vous envoyez à un TTS.
• python tools/find_phrases.py prise.wav affiche le (début, fin) de chaque phrase dans la prise. Mettez-les dans PHRASES et relancez build_tl.py : il découpe les phrases, les place et écrit audio/narration.wav. Puis revérifiez chaque plan : les longueurs réelles des phrases diffèrent des estimations.
• Les fichiers build_tl.py fournis gèrent un narrateur. Pour plusieurs locuteurs, gardez une prise par locuteur et ajoutez le locuteur à chaque phrase (une petite modification de build_tl.py).
• Gros mots pour TikTok : bleep dans une piste séparée, et astérisque dans les sous-titres (f***ing).

3. Les fichiers de l'épisode (references/engine.md)

fichier	rôle
script.py	lignes, blocs de sous-titres, jalons
build_tl.py	timeline.json (+ audio/narration.wav)
looks.py	le casting : chaque look est un dict dans rig.LOOK
scenes.py	le monde : géométrie du décor, lumières, qui est où au temps T, les pistes de jeu
reel.py	SHOTS, sous-titres, render(T), les vérifications et les commandes de rendu
cues.py	événements sonores pour tools/sound.py
finalize.py	mixer les pistes, les multiplexer sur le rendu, exécuter tools/finish.py

Commencez un nouvel épisode en copiant episodes/starter/toon dans episodes/<nom>/toon. Ses reel.py, build_tl.py et finalize.py sont génériques et peuvent rester tels quels ; vous remplacez script.py, looks.py, scenes.py, la table SHOTS et cues.py. Ne commencez pas à partir de episodes/window/toon : son reel.py, cues.py et ses vérifications sont liés à cette histoire (deux mondes en miroir, jalons nommés, une caméra de retournement personnalisée). Lisez-le pour la technique : textures, profondeur de champ, clé de visage par monde, mains sur la vitre, fondu entre les mondes. Les épisodes plus grands déplacent le jeu de scenes.py vers un acting.py.

Un monde a besoin de deux méthodes : draw(fr, cam, T), qui dessine tout et retourne {pid: résultat rig.draw}, et cast(T), qui retourne [(pid, look, pose)]. pid est l'identifiant d'une personne dans cet épisode ("nora"). Un monde et une timeline par lieu ; les plans choisissent seulement les caméras.

4. Look (references/look.md)

Formes simples arrondies, têtes légèrement grosses, grands yeux expressifs, matériaux mats avec un ombrage doux à 3 arrêts et un contour plus foncé dans la couleur de base. Chaque personnage a sa propre silhouette, visage et palette conçus à partir du script (jamais un re-skin d'un personnage d'un autre reel) ; les personnages récurrents restent cohérents. Faites une fiche modèle avant d'animer, depuis tools/toon : python -m cast.sheet ../../episodes/<nom>/toon/looks.py <look> (elle écrit assets/kit/cast/<look>.png à la racine du projet, ou le chemin que vous donnez comme troisième argument).

5. Éclairage (references/lighting.md)

Trois couches dans chaque lieu : un environnement froid (nuit bleu-violet conserve les détails), une lumière principale douce sur chaque visage (depuis le haut-devant, motivée par une lampe ou une fenêtre), et des sources chaudes à plusieurs distances qui éclairent ce qui est proche d'elles. Les visages sont l'élément le plus clair du cadre ; l'arrière-plan est un peu plus sombre et moins détaillé autour d'eux. Ombres portées sous les pieds, les meubles et les mains qui se touchent. Un réglage de lumière par lieu : la direction, la couleur et l'exposition tiennent d'un plan à l'autre. Pas de bloom, pas de contours lumineux, pas de noirs écrasés. La météo (pluie, neige, vent) s'anime dans les moments calmes quand l'histoire a du temps.

6. Caméra (references/camera.md)

• Un plan toutes les 2-3 s. Chaque plan sert une action, une expression ou une révélation.
• L'accroche (0-3 s) est le plan mobile le plus beau du reel : la caméra et le personnage bougent dès l'image 1.
• Plan à deux d'abord, puis gros plans alternés. Les gros plans restent à ~35° de la ligne de regard.
• track(a, b, ease) fait un mouvement propre entre deux clés (position, cible, focale px, horizon). La caméra se tourne vers la cible mais ne peut pas s'incliner : la hauteur de la cible est ignorée. Cadrez vers le haut ou vers le bas avec la hauteur de la caméra et horizon (une valeur plus petite place la ligne des yeux plus haut dans le cadre, ce qui donne l'impression de regarder vers le bas).
• Gardez les caméras >= 0,45 m de toute personne visible : rig.draw ne dessine personne plus proche que cela.
• Les sous-titres (Arial Black 66 px, blanc, contour noir, mot-clé #FF4D4D) ne reposent jamais sur un visage ou une main. Déplacez-les par plan avec cap=(y, taille).

7. Jeu d'acteur et mise en scène (references/acting-staging.md)

Chaque action est une chaîne avec décalages : yeux -> tête -> épaules -> corps -> mains, en préparation -> mouvement -> stabilisation. Les réactions s'adoucissent en out/snap, les stabilisations en back. Les saisies atteignent avant de se fermer. Une personne qui ne tourne que la tête et les épaules peut rester sur les pieds par défaut ; une personne qui marche ou tourne le corps a besoin de pieds ancrés dans l'espace monde (cheville_R/cheville_L depuis rig.replant ou rig.gait), faisant un pas à la fois. Lisez les leçons de mise en scène avant de bloquer quoi que ce soit : chacune est un défaut qui s'est déjà produit.

8. Vérifications : la porte d'entrée avant chaque maître (references/checks.md)

1. python reel.py --check -> lisez tout review/reel_checks.txt. Dans le starter, chaque problème est une ligne ANOMALIE : portée, pieds qui s'enfoncent, coudes trop pliés, retournements de coudes et de genoux, sauts, personnes trop près de l'objectif, sous-titres sur un visage ou une main.
2. python reel.py --stills -> première/image du milieu/dernière image de chaque plan (tour 1).
3. python reel.py --sheet <SHOTS> -> chaque image des plans de contact, marches, tours et changements d'occlusion sur des feuilles espacées (tour 2). Recherchez les dédoublements, les membres qui sautent, les têtes à travers des objets, les choses qui disparaissent.
4. Corrigez dans les données, relancez, et consignez chaque anomalie dans review/LOG.md (ajout seulement) : temps, plan, cause, correction, comment vérifié ; plus les drapeaux acceptés avec la raison, et ce que vous n'avez pas pu inspecter.
5. Ne prétendez jamais "aucune anomalie" à partir du seul code. Le code vérifie les articulations, pas les images : il ne voit pas les personnes qui traversent les meubles ou les unes les autres, les accessoires qui manquent une main, un mauvais ordre de dessin, ou un pas de côté de 0,8 m qui ressemble à un grand écart. Vous trouvez ceux-ci sur les feuilles.

9. Rendu (depuis le dossier de l'épisode)

• python reel.py --preview --full -> review/reel_preview.mp4 (1080×1920, silencieux). python finalize.py preview ajoute le mix -> review/preview.mp4. Montrez-le, obtenez un accord.
• python reel.py --master-par 12 -> video/reel_silent.mp4 : le maître sur 12 processus (utilisez votre nombre de cœurs).

10. Son, mixage, finition, post (references/sound-finish.md)

• cues.py, puis depuis la racine du projet python tools/sound.py episodes/<nom>/toon -> pistes de musique, effets sonores et ambiance. Enregistrements réels pour des choses réelles (apportez des échantillons CC0 ou sous licence dans assets/sfx/) ; synthèse seulement pour des drones abstraits, des crescendos et des boums. Les repères du starter sont tous synthétisés pour que la chaîne s'exécute : remplacez-les.
• python tools/mix_check.py episodes/<nom>/toon : la voix doit être >= 10 dB au-dessus des nappes sur chaque ligne (chaque ligne échoue tant qu'il n'y a pas de prise de narration réelle).
• python finalize.py final (dossier de l'épisode) -> tools/finish.py -> -14 LUFS, <= -2 dBTP, H.264 High, +faststart.
• Vignette, depuis la racine du projet : python tools/thumb.py image.png cover.jpg --line "TITRE:#F2EFE6:120".
• POST.md : sous-titres par plateforme, hashtags, et un rappel d'activer le téléchargement HD dans l'application.

Termes utilisés ici

• jalon : un battement nommé de l'histoire en secondes (MARKS), utilisé comme limite de plan et pour temporiser les actions.
• station : un endroit où se tient un personnage (x, z, orientation) et le temps où il s'y rend.
• pied planté : une cheville fixée à une position monde (cheville_R/cheville_L), de sorte que le pied ne glisse pas.
• zone de clip : un clip dans l'espace écran qui cache une partie d'un corps derrière quelque chose (une haie, un bord de mur).
• élément plat mural : décoration de décor plate sur un mur (rideau, affiche) ; triez-la aussi loin que son mur.
• source pratique : une source lumineuse visible dans le décor (une lampe, une fenêtre allumée).

Habitudes

• Regardez avant d'affirmer. Rendez l'image, lisez la feuille, puis dites ce que vous avez vu.
• Un changement, un re-rendu des plans affectés, une revérification, avec feuilles.
• Quand une mise en scène échoue constamment, simplifiez-la ou choisissez un angle plus clair. Ne masquez jamais l'anatomie avec du flou, de l'obscurité, des coupes ou des sous-titres.
• Écrivez chaque correction que la personne vous donne dans review/LOG.md de l'épisode et, si elle est générale, dans un STAGING_NOTES.md à la racine du projet (lisez-le au début de chaque épisode). N'écrivez jamais dans le dossier du plugin lui-même.