yt-film

yt-film : films narrés à partir d'images fixes

Une chaîne de production pour films narratifs : l'utilisateur crée ~150 images fixes à partir d'un guide écrit par Claude, Claude écrit le script à partir de ces images, une voix le lit, et le moteur Python anime chaque image en synchronisation avec les paroles. Le film de référence est l'exemple Chadwick (examples/chadwick/, Carnegie's Daughter : la femme qui a emprunté des millions en se faisant passer pour la fille secrète d'Andrew Carnegie) : ses images, script, voix, musique, listes de plans et la vidéo test d'effets de 70 secondes (examples/chadwick/video/chadwick_effects_test.mp4) montrent chaque technique.

REPO ci-dessous désigne le dossier de cette compétence (où se trouve ce fichier). PY est son Python : REPO/.venv/bin/python sur macOS/Linux, REPO\.venv\Scripts\python.exe sur Windows. Exécutez toujours les commandes du moteur avec PY depuis le dossier tools/ du projet. Si .venv n'existe pas, configurez d'abord : suivez le manuel d'installation (pour Claude) dans references/install.md étape par étape (demandez avant toute installation système ; l'utilisateur colle sa propre clé API).

Règles de base

• Ne jamais lancer de rendu sans l'accord de l'utilisateur. Vérifiez avec stills.py (une planche contact en ~30 s). Les rendus par lots, les prévisualisations, la fin et l'assemblage final prennent de quelques minutes à plusieurs heures : dites ce que vous allez rendre et combien de temps cela peut prendre, puis attendez un oui. Ne re-rendez rien qui a déjà été rendu sauf si cela a changé et que l'utilisateur le souhaite.
• Demandez les choix de l'utilisateur une fois par projet : quel outil d'images (references/image-generation.md), voix (Gemini TTS ou la sienne : references/voice.md), musique (Lyria ou la sienne : references/music.md), sa niche et le nom de sa chaîne, et les trois choix qui rendent la chaîne unique : le style d'image (l'ouverture : gouache, éditorial plat, noir, craie, bande dessinée, livre d'histoires, plan technique, ou le sien ; personnages ou non), le rendu moteur (YTF_LOOK : gouache, clean, noir, craie, bande dessinée, livre d'histoires, plan technique ; look.json pour les valeurs uniques) et le format (story, explainer, countdown, rise-fall, storytime, kids, summary, case-study, news) : references/art-styles.md, references/formats.md. Ne choisissez pas par défaut le style pastel true-story de l'exemple ; si l'utilisateur n'a pas de préférence, présentez les options dans un court tableau et recommandez celle qui correspond à sa niche.
• La niche de l'utilisateur lui appartient : ne l'orientez pas vers l'histoire ou le sujet de l'exemple. L'exemple est une référence pour les techniques, pas un modèle pour les sujets.
• Windows : les chemins avec des barres obliques fonctionnent ; les longs travaux s'exécutent en arrière-plan ; les réglages de vitesse dans references/performance.md. Ne supposez jamais d'outils exclusifs à macOS.
• Pas de clés API dans d'autres fichiers que .env. Téléchargez des photos ou fichiers sonores réels uniquement après l'accord de l'utilisateur (indiquez le fichier, la source, la taille et la licence).

La pile technique

Tâche	Outil	Où
Recherche	recherche web, liste de faits vérifiés avec sources ; signalez ce qui ne peut être confirmé	OUTLINE.md
Images	l'outil d'images de l'utilisateur, à partir du guide de Claude	IMAGE_GUIDE.md (+ IMAGE_PROMPTS.jsonl pour l'API), incoming/
Script	Claude, écrit à partir du guide d'images, un passage ## par beat, notes [SHOTS: …]	SCRIPT.md
Voix	Gemini TTS (voix Orus, lecture lente → 1.25x, pauses limitées) ou l'audio de l'utilisateur via import_voice.py	tools/voice.py, tools/import_voice.py
Synchronisation mots	Whisper : mlx-whisper (Apple Silicon) ou faster-whisper (Windows/Intel/Linux)	voice/<batch>_words.json
Musique	Lyria (Gemini API), un cue par section, ou les pistes sous licence de l'utilisateur	tools/music.py → audio/music/
Moteur film	Python (OpenCV, Pillow, NumPy, SciPy), pas d'After Effects	tools/film.py, fx2.py, seq.py, signature.py, wr.py, kit.py
Listes de plans	un fichier par lot dans seq.py, déclenché sur les temps des mots du lot	tools/<story>.py + tools/shots_bN.py
Rendu	parallèle, adapté à la machine, faible priorité	tools/render_all.py
Fin	la signature animée personnalisée de l'utilisateur (exemple : cta.py)	renders/cta.mp4
Assemblage final	lots + fin, une musique continue, −14 LUFS / −2 dBTP	tools/final.py
Doublage	Espagnol + Français par défaut : traduction Gemini + TTS en segments ~3 min, ajustés aux créneaux anglais	tools/dub.py
Miniatures	l'outil d'images de l'utilisateur, à partir d'un guide	references/thumbnails.md

Les projets se trouvent dans YTF_WORKSPACE (par défaut ~/yt-film-projects/<story>/), créé par PY REPO/scripts/new_project.py <story>, qui copie le moteur dans tools/ et crée chaque dossier. Les réglages sont dans .env (projet d'abord, puis REPO) : GEMINI_API_KEY, YTF_CHANNEL, noms des voix/modèles, boutons de vitesse (.env.example les liste tous). engine/ytf.py trouve les polices, la clé, Whisper et les ressources partagées sur tout OS.

L'ordre de travail

0. Choisissez l'histoire si elle n'est pas donnée : 3 à 5 candidates avec vérification des écarts (references/story-finding.md). Lancez le projet avec son format et son look : PY REPO/scripts/new_project.py <nom> --format <format> --look <look> (écrit le template du format dans OUTLINE.md, YTF_FORMAT et YTF_LOOK dans .env). Testez un nouveau style sur deux images avec stills.py avant d'écrire le guide complet (references/art-styles.md, dernière section).
1. Histoire et faits : recherche ; OUTLINE.md avec sources. Marquez tout ce qui n'est pas confirmé et contournez-le plus tard (« selon des rapports »), ne l'affirmez jamais comme un fait. Décidez de l'accroche (references/hooks.md : jamais le même type que les trois derniers films de l'utilisateur). Ensuite, écrivez la colonne vertébrale en haut de OUTLINE.md (references/storytelling.md) : une question à laquelle le film répond et 8 à 12 beats reliés par « donc » / « mais » ; le premier acte erroné ou moment décisif vers ~15 % du film ; un ou deux passages de contexte par personne principale. Montrez-la à l'utilisateur avant le guide d'images.
2. Guide d'images d'abord (references/image-guide.md, écrit pour la méthode de l'utilisateur). Il suit la colonne vertébrale et la façon dont le film est narré (montrer, puis dessiner : chaque ligne de beat nomme la réplique qu'elle sert et ce qui est dessiné dessus ou après). Visez ~150 images : fiche de style, fiches de personnages, ~100 plans de scène avec couverture (W large, M moyen, F gros plan visage en tant qu'EDIT, D détail, P point de vue), 6 scènes avec versions _lines, 12 feuilles de croquis + _lines, ~10 objets d'histoire vierges (« bases » : un carnet, une vieille carte, une carte postale, un grand livre, une enveloppe, un télégramme, un journal). Noms de fichiers et dossiers exacts. Règles de cohérence : references/consistency.md.
3. Vérifiez les images au fur et à mesure de leur arrivée par groupes (mains, visages, détails d'époque, pas de texte, forme : les images arrivent ~16:9 et sont recadrées au centre en 2:1, donc rien d'important tout en haut/en bas). Téléchargements manuels : scripts/sort_images.py. Puis feuilles quadrillées en px moteur (COLS=4 PY tools/egrid.py out.png IMG ...) et cartographiez les cheminées, lampes, bougies, souffle et zones calmes de chaque image avant d'écrire les plans.
4. Script à partir des images. Chaque image générée est utilisée ; associez chaque passage à ses plans et exécutez la vérification des images inutilisées (exemple : examples/chadwick/tools/script_check.py), puis PY tools/story_check.py (dates prononcées, ouvertures de changement de scène, où tombe le passage [DRIVE], chaque jointure de lot) et les vérifications dans references/storytelling.md (raconter, 15 %, mais/donc, pas d'explications empilées, 5–7 dates prononcées, montrer → dessiner). Pas de limite de longueur : racontez l'histoire complètement et sans précipitation (~150 mots par minute ; Chadwick : 1 780 mots → 12 min). Terminez par la ligne d'appel à l'action de l'utilisateur.
5. Voix : Gemini (voice.py --test d'abord, puis lots ; --pace et SPEEDS pour que chaque lot tourne à ~140–160 mots/min) ou l'audio de l'utilisateur (import_voice.py --full | --passages | --batches). Définissez BATCHES (4 à 7 passages, ~65–100 s chacun, coupés au milieu d'un acte là où l'histoire avance ; seulement 2–3 coupures sur les pauses d'acte ; rien de réintroduit au début d'un lot) et GAPS. Imprimez les mots de chaque lot avant d'écrire ses plans (Whisper entend mal les noms et écrit les nombres en chiffres : basez-vous sur ce qu'il a écrit).
6. Musique : 5 à 7 cues (music.py, ou les fichiers de l'utilisateur dans audio/music/) ; associez les cues aux lots dans MUSIC de final.py.
7. Listes de plans par lot avec seq.py (references/engine.md, examples/chadwick/tools/) : un module film (<story>.py, comme chad.py) contient la table LIVE (les couches vivantes de chaque image) et les réglages de carte ; chaque shots_bN.py fait ~60 lignes de S.at(time, scene(...)/page(...)/drawin(...)/map_shot(...)). Vérifiez chacun avec PY tools/stills.py bN et regardez la feuille avant tout rendu.
8. Rendus (avec l'accord de l'utilisateur) : PY tools/render_all.py exécute tous les lots en parallèle, autant à la fois que la mémoire libre de la machine le permet (environ 1,5 Go par rendu ; plus à la fois ralentit une fois la mémoire épuisée) ; après corrections, render_all.py b3 b7 ou --changed. Lancez-le dans sa propre fenêtre pour que la fermeture de Claude ne l'arrête pas, et suivez references/performance.md lorsqu'un rendu est lent ou que l'ordinateur rame (Windows en particulier). Testez une nouvelle transition ou un nouvel effet sur deux images d'abord (un crash tardif gâche le rendu).
9. Fin une fois par chaîne (references/cta.md), puis assemblage final PY tools/final.py ; vérifiez la durée, les fps, le volume sonore sur le MP4 (−14 LUFS, pic ≤ −1.5 dB) et des images d'échantillon (references/final-render.md).
10. Doublages (references/dubs.md) et miniatures (references/thumbnails.md) si souhaité.

Le look (par défaut de l'exemple ; chaque chaîne choisit le sien)

• L'exemple : personnages à tête d'œuf (tête d'œuf, deux yeux ovales foncés, bouche d'un trait, pas de nez/oreilles/sourcils, mains arrondies simples) dans un monde réel précis historiquement ; trait à l'encre + gouache pastel mate ; look moteur gouache. Les autres chaînes choisissent leur propre style d'image, leurs personnages (ou non) et leur look moteur (references/art-styles.md) ; les règles ci-dessous s'appliquent à tous les styles.
• Le look moteur définit les couches ajoutées : teinte, grain, vignette, encre, papier d'étiquette, accent, polices, son de dessin (engine/look.py : YTF_LOOK, look.json). Ne codez jamais en dur une couleur ou une police dans un fichier de plans lorsque le look en a une (look.rgb("accent"), look.L.type_font) ; le look d'une chaîne doit changer à un seul endroit.
• Pas de 2.5D, pas de découpages, pas de vidéo IA. Images uniques avec des mouvements de caméra progressifs (push-ins, panoramiques, dérive lente).
• Ne tenez jamais une image trop longtemps : passez au plan suivant du moment (W→M→F→D→P) ou à une page dessinée.
• Les explications par croquis sont de vrais dessins, pas des icônes : extraits du line art des feuilles ou dessinés par le moteur là où le code le fait bien (cartes précises, itinéraires, marques, figures simples).
• Les bases vierges sont dessinées en direct dans leur propre médium : graphite sur papier, craie sur tableau, encre au pinceau, photos en demi-teinte s'imprimant dans un journal, routes à l'encre sur une carte.
• Les lignes portent du sens : traits de comptage pour les années, anneaux sonores, chemins de papier tombant, lignes de fumée, figures barrées.
• Les étiquettes (dates, lieux, noms) sont du texte tapé à niveau dans la police du look (machine à écrire pour gouache), tapé une touche à la fois avec un clic doux.
• L'écriture sur un objet repose sur les lignes réelles de cet objet à leur angle ; l'écriture illisible en dessous est d'abord effacée (fx2.clean_text).
• Contraste toujours : rien de sombre sur sombre. Les étiquettes choisissent automatiquement crème/encre avec un halo. Ne forcez jamais color="ink" sans vérifier ce qu'il y a en dessous.
• Le sprite d'outil est petit (échelle 0.28) pour ne jamais détourner l'attention.

Animation signature (tout en code sur les images fixes)

engine/signature.py, engine/fx2.py, aides de plan engine/wr.py, engine/seq.py. Un fixe de chaque dans examples/chadwick/look/ ; tous en mouvement dans la vidéo test d'effets.

• Images vivantes (l'image ne bouge pas ; des couches vivent dessus) : fumée de particules de chaque cheminée, souffle dans le froid, flammes vivantes et la lumière qu'elles projettent, les lampes de l'image trouvées et animées (fx2.lamps), neige, pluie, feuilles tombantes, reflets. Pas de déformation de pixels (sg.Flow) sur la fumée, la vapeur, le feu ou l'eau : cela étale la peinture (look/flow_smear_avoid.png).
• Visages qui agissent, seulement là où cela compte : pas de clignement automatique ni d'expressions. Un visage n'agit que lorsqu'un plan passe act= / talk=, et seulement un visage avec une paire d'yeux appariée (sg.face_audit([...], out.jpg) : n'agissez que là où les deux yeux sont entourés de vert). Indices : blinks, glances, widen, mouth_fx, expr (sourire, grimace, froncement, o, rire, yeux fermés, plissement...), talk=(ta, tb), marques de réaction (sweat, shake, !, ?, zzz). Une poignée de vrais beats par lot, jamais décoratifs.
• Pages de bande dessinée sur le tableau vierge (sg.Comic) : les bordures s'encrent, chaque case s'encolore puis se peint, la caméra visite les cases et plonge dans la dernière. Deux par film (l'accroche, le premier grand morceau). Chaque case dure ≥ 1,8 s.
• Dessins réalisés en direct (fx2.Draw) : une feuille de dessin s'encrène dans son ordre de trait (sprite de stylo et son), puis ses couleurs se lavent ; card=True pose d'abord un lavis crème doux sur les images chargées. Une feuille n'est jamais montrée comme une page de quatre : chaque dessin apparaît quand le narrateur le nomme, lié par des flèches et de courtes étiquettes tapées.
• La carte explicative (une base réutilisée) : noms tapés et barrés, un mécanisme en chaîne de dessins avec flèches, trois dessins avec trois mots.
• Vocabulaire des marques, choisi selon le sens, jamais la même marque à chaque fois : soulignement, coche, croix, parenthèse, lignes de mouvement, anneaux sonores, itinéraire (chemin pointillé + flèche), repère (point, ligne, étiquette tapée), compteur ; sg.Stamp (coup de tampon encreur : FORGÉ, FERMÉ, 14 ANS), sg.Tag (étiquette en papier déchiré), sg.Inset, sg.Flip (panneau à palettes), sg.Pin, fx2.Counter (compteur d'argent qui roule).
• Effets avec poids (quelques moments ressentis par lot) : fx2.Lift (découper un objet de l'image et l'animer, fill_from= clone-remplit le trou), fx2.Tear (l'image se déchire en deux), la transition ("shatter", s, (cx, cy)), sg.Papers (papiers qui tombent), feu + frappe, secousse + bruit sourd, flashs d'appareil photo + obturateur, sg.Rays, sg.Haze.
• La carte vivante (seq.map_shot) : les côtes réelles s'encrènent, l'eau se lave, les frontières s'encadrent en pointillés, les lacs et les villes se tapent, une ligne de voyage rouge...