Plextrang/story-shorts

Story Shorts : une idée en entrée, un court métrage animé en sortie

Ce skill est à la fois un moteur de film et un flux de travail. Le moteur (engine/) rend chaque image three.js dans Chrome sans tête : des personnages en toile 2D (puppets) dans un monde 3D ombré avec contours à l’encre, des mouvements de caméra et des fondus, une superposition 2D pour les graphiques explicatifs, des sous-titres incrustés et un mixage sonore basé sur des événements temporels. Chaque film écrit uniquement sa couche narrative : qui y figure, où cela se passe, les plans, les graphismes et le plan sonore. Un nouveau film part du modèle vierge (starter/ : deux personnages fictifs, deux lieux, quatre plans). examples/floating-scale/ est un film terminé, pour référence uniquement. Ne réutilisez jamais ses personnages ou son histoire.

Lisez-les selon vos besoins :

• reference/rules.md : les règles de l’histoire et de l’image. Lisez-le en premier.
• reference/story-templates.md : six schémas narratifs. Choisissez-en un par film.
• reference/engine-api.md : comment écrire un film sur le moteur (personnages, poses, mondes, accessoires, plans, graphismes, indications).
• reference/transitions.md : la règle 11 en pratique (mouvements de caméra, mise en scène pour la continuité, coupes maintenues).
• reference/sound.md : voix, musique et effets, avec Epidemic Sound ou les outils gratuits.
• reference/lessons.md : bugs déjà rencontrés et leurs corrections. Consultez-le avant de déboguer quoi que ce soit.

Avant de commencer : posez deux questions

1. L’idée. Une phrase suffit : « un gardien de phare qui a peur du noir », « le marathon olympique de 1904 », « et si la gravité diminuait de moitié pendant un jour ». Demandez-la si l’utilisateur ne l’a pas donnée. Demandez la durée uniquement si cela lui importe (par défaut environ 60 s).
2. Les outils audio. Demandez : « Avez-vous Epidemic Sound (avec son connecteur Claude), ou dois-je utiliser les outils gratuits ? »
   • Epidemic Sound (recommandé) : voix off Epidemic pour le narrateur et les personnages, un morceau de musique Epidemic coupé sur l’histoire, effets et ambiances Epidemic. Nécessite le connecteur MCP Epidemic Sound dans Claude Code.
   • Gratuit : Kokoro TTS pour les voix (scripts/kokoro_voice.py), une musique et des effets synthétisés en code.
   • Ne mélangez pas les deux dans un même film sans le préciser dans le README du film.

Exécutez ensuite python scripts/check_setup.py et corrigez tout ce qui est marqué MANQUANT avant d’écrire du code de film.

Le flux de travail (aucune approbation nécessaire sauf si l’utilisateur le demande)

1. Nouveau projet. python scripts/new_film.py <dossier> "Titre" copie le moteur et le modèle vierge, écrit un scénario temporaire et installe film/node_modules à neuf. Travaillez uniquement dans ce dossier.
2. Histoire (docs/STORY.md, script/lines.json).
   • Choisissez le modèle narratif qui correspond à l’idée (reference/story-templates.md) et dites lequel vous avez choisi et pourquoi.
   • Écrivez le script : une entrée par réplique (id, personnage, début, texte). Narration plus quelques répliques de personnages ; environ 150 mots par minute de film.
   • Écrivez la liste des plans avec une lecture muette par plan : ce qu’un spectateur sans son comprend de l’image seule.
   • Nommez les lieux. Un changement de lieu est la seule raison d’un fondu ; à l’intérieur d’un lieu, la caméra se déplace.
   • Les faits doivent être vrais, avec des chiffres réels. Les personnages, l’histoire et le monde sont originaux.
3. Distribution (film/src/story/cast.js).
   • Une clé par personnage (identique à son identifiant de locuteur). Commencez par un préréglage et modifiez les couleurs, les proportions et les caractéristiques jusqu’à ce qu’ils soient propres à ce film (reference/engine-api.md, « Personnages »). Ajoutez un nouveau look dans character.js derrière un nouveau drapeau feat lorsque l’histoire en a besoin.
   • Rendez node film/tools/charsheet.mjs et regardez chaque fiche avant de construire un plan.
4. Monde et accessoires (story/world.js, story/set.js, story/props.js optionnel).
   • Construisez chaque lieu à partir de worldkit.js plus ses propres points de repère. Mettez chaque repère dans SET. Donnez aux accessoires principaux les états dont l’histoire a besoin.
5. Blocage de l’image (story/shots.js, story/overlay.js).
   • Remplacez les quatre plans du modèle par les plans du film. Calculez les durées à partir du scénario (K.wordAt, K.lineAt), jamais à partir de secondes codées en dur. Tant que la voix n’existe pas, python tools/build_timeline.py --placeholder.
   • Mettez en scène pour la continuité dès le début (règle 11) : une performance par personnage par lieu, accessoires à leurs emplacements.
   • Expliquez avec des diagrammes 2D (règle 4). Listez chaque action visible dans CUES.
6. Voix.
   • Générez chaque réplique dans son propre fichier dans audio/vo/raw/<id>.mp3|wav (Epidemic, ou scripts/kokoro_voice.py).
   • python <repo>/scripts/prepare_voice.py (ajoutez --atempo-off pour Kokoro) coupe les fins silencieuses et règle le rythme.
   • python tools/build_timeline.py, python tools/captions.py, puis cd film && node tools/cues.mjs.
   • Ne coupez jamais un fichier aux moments des mots chuchotés. Revérifiez le cadrage : les durées ont changé avec la vraie voix.
7. Révision de l’image avant tout rendu complet :
   • node framecheck.mjs --step 4 doit afficher « framing OK ».
   • node tools/poptest.mjs --out ../render/pop vérifie tous les bords pour les pops ; bash tools/movesheet.sh vérifie les mouvements.
   • bash tools/sheet.sh <nom> "<temps>" génère des planches contact. Regardez-les et vérifiez chaque plan par rapport à sa lecture muette. Effectuez au moins deux séries complètes.
8. Son (audio/sound_plan.json, reference/sound.md).
   • Epidemic : téléchargez le morceau et les effets dans audio/epidemic/, remplissez music, effects et ambience, puis cd audio/epidemic_mix && python mix_film.py && python autolevel.py && python qc.py && python sync_check.py.
   • Gratuit : remplissez synth, puis cd audio/synth && python music.py && python build_fx.py && python mix.py && python cue_presence.py.
   • Objectifs : −14 LUFS, crête réelle ≤ −1,3 dBTP, voix au moins 6 dB claire sur chaque réplique, pas de silence, chaque effet à moins d’une image.
9. Rendu, assemblage, livraison.
   • cd film && node render.mjs --from 0 --to <images-1> --scale 1.5 --workers 2 --jpg --out ../render/frames.
   • bash tools/assemble.sh écrit out/<Titre>.mp4 et out/contact_sheet.jpg, et mesure le résultat. Il refuse de s’exécuter si un worker planté a laissé une image vide.
   • Si earshot est installé : bash audio/tools/es.sh critique out/<Titre>.mp4, en visant « qualité production ».
   • Écrivez le README.md du film : logline, mesures, chaque coupe maintenue et pourquoi, les sons utilisés, et les points faibles honnêtes. Ne prétendez jamais que le film est bon : vous ne pouvez ni le voir ni l’entendre en vitesse réelle. Listez ce que l’utilisateur doit vérifier visuellement et auditivement, puis arrêtez-vous et attendez son retour.

Incontournables (détails dans reference/rules.md)

• Il se comprend sans le son. Montrez le problème avant la solution. Montrez chaque réplique à l’écran pendant qu’elle est dite.
• Pas de métaphores littérales ; expliquez avec un diagramme 2D clair.
• Les accessoires se lisent en un coup d’œil. Utilisez des plans moyens et larges avec des figures entières, gardez la bande de sous-titres (62–78 % de la hauteur) dégagée, et personne n’est coupé en bas.
• Même lieu signifie un mouvement de caméra, un nouveau lieu signifie un fondu, et une coupe ne reste qu’avec une raison indiquée.
• Chaque action visible a un son audible, et la narration reste claire tout du long.
• Personnages, histoires et mondes originaux uniquement. Ne copiez jamais les personnages ou l’apparence d’un spectacle existant, et ne réutilisez jamais le film d’exemple.
• Travaillez uniquement dans le dossier du film. Installez tout à neuf dedans ; ne faites jamais de lien vers un autre projet.