Que fait documentary-maker ?
Vous êtes toute l'équipe de tournage : chercheur, scénariste, narrateur, monteur, animateur, concepteur sonore. Travaillez à travers les six chapitres dans l'ordre. Tout s'exécute sur l'ordinateur de l'utilisateur et ne coûte rien au-delà de son abonnement Claude.
Les outils se trouvent dans ce dossier de compétence (<skill> ci-dessous). Les outils Python s'exécutent avec le venv de la compétence : ~/.documentary-maker/venv/Scripts/python.exe sur Windows, ~/.documentary-maker/venv/bin/python ailleurs (<py>).
0. Configuration (une fois)
Si ~/.documentary-maker/venv ou <skill>/engine/vendor/gsap.min.js est manquant, exécutez python <skill>/tools/setup.py (Python 3.10-3.12 ; sur Windows py -3.12 <skill>/tools/setup.py). Il nécessite Node, FFmpeg et Chrome ou Edge ; si l'un d'eux manque, dites-le à l'utilisateur et arrêtez-vous. Ensuite python <skill>/tools/new_doc.py <project> <theme> dans le dossier de l'utilisateur.
Choisissez le thème en fonction du sujet : midnight (espace, science, tech), ember (histoire, business, personnes), noir (crime, arnaques, mystères), forest (nature, climat, santé), crimson (guerre, catastrophes - ton sérieux). Une couleur d'accentuation fait toute la mise en valeur ; la couleur d'avertissement est réservée au danger, aux pertes d'argent, aux morts, aux échecs.
1. Recherche → facts.md
- Cherchez sur le Web. Chaque nombre, date, nom et citation dans le script doit apparaître dans
facts.mdavec une URL source. Privilégiez les rapports officiels, les documents judiciaires, les pages de l'organisation elle-même et les grands journaux, plutôt que les blogs. - Lorsque les sources divergent (argent, bilans humains), utilisez le chiffre le plus cité et dites « environ » / « autour de » dans le script.
- N'inventez jamais une citation, une pensée, un détail de scène ou un nombre. Si vous ne pouvez pas le sourcer, laissez-le de côté.
2. Script → script.md + voice/script_voice.txt
Longueur : environ 2,4 mots parlés par seconde (30 s ~ 75 mots, 60 s ~ 145, 3 min ~ 430).
- Commencez dans un moment, pas par un résumé : une date, un lieu, une action (« Juin 1996. Une toute nouvelle fusée repose sur le pas de tir. »). Le spectateur doit la voir.
- Phrases courtes. Une idée par phrase : chaque phrase devient une animation.
- Gardez le plus grand nombre pour la fin, et chaque révélation ouvre la question suivante (« La cause ? Pas les moteurs. Pas la météo. Un nombre. »).
- Terminez par une courte ligne qui conclut l'ouverture.
script.md= le script avec un titre.voice/script_voice.txt= les mêmes mots pour la voix : chiffres et symboles écrits comme ils sont prononcés (« mille neuf cent quatre-vingt-seize », « soixante-quatre bits », « trois cent soixante-dix millions de dollars »), pas de titres, pas de [balises] ; une ligne vide entre les paragraphes = une pause (paragraphes de 1 à 3 phrases).- Montrez le script et les faits principaux à l'utilisateur, et attendez son accord avant de générer la voix, sauf s'il a dit de ne pas demander.
3. Voix → voice/voice.wav
cd <project> && <py> voice.py --voice am_michael (autres narrateurs : am_onyx, am_fenrir, bm_george, bm_daniel, af_heart, bf_emma ; --speed 0.95 pour une lecture plus calme). Kokoro s'exécute sur le CPU à environ 2x temps réel.
4. Timings des mots → engine/data.js
<py> words.py. Il affiche une vérification des mots ; si un mot du script est manquant ou erroné, modifiez ce paragraphe (souvent un nom : épelez-le comme il se prononce) et refaites le chapitre 3. Whisper écrit les nombres en chiffres (« 1996 », « 64-bit », « 370 millions $ »), donc les sous-titres affichent les chiffres ; ancrez les animations sur les mots simples.
5. Scènes → engine/scenes.js
Lisez d'abord <skill>/examples/ariane-501/scenes.js : c'est un documentaire complet et fonctionnel. Écrivez le vôtre de la même manière.
anchors()d'abord : cherchez les temps de chaque mot-clé dans l'ordre avecWA('mot', 'alternative')(début) etWEnd(...)(fin) ; terminez parB.end = endAfterVoice(2.0); _wc = 0;. Ensuitebuild()appelle une fonction par mot-clé.- Chaque élément visuel apparaît sur un mot parlé. Rien n'apparaît avant son mot ; l'écran n'est jamais vide plus d'une seconde environ.
- Dessinez l'histoire, ne l'écrivez pas. Illustrations SVG inline dans les couleurs du thème (fusée, bâtiment, forme de carte, pièce de monnaie, silhouette de personne, document) avec mouvements de caméra (échelle/translation d'un calque), plus des titres dynamiques
hd(), des cartescard()+fly(),stamp()/warnStamp(),counter(),burst(),suspectCard(),quoteCard(),timeline(),dateTag(),typeText(). Voirengine/lib.jsetengine/doc.jspour tous les assistants et leurs options. - Gardez le texte court (étiquettes, nombres, titres de 2 à 4 mots). Les sous-titres affichent déjà chaque mot en bas : gardez le contenu au-dessus de y = 930. Définissez
window.KEYWORDSpour que les sous-titres colorent ces mots. - Étiquetez les dessins qui pourraient être confondus avec des images ou documents réels : un petit tag « ILLUSTRATION ».
- Mouvements à l'échelle de la seconde seulement : pas d'animation plus rapide que 0,25 s, rien qui scintille.
- Utilisez uniquement les couleurs du thème (
LIME= accent,LIME2,PAPER,MUTE,DIM,CARD1,CARD2,PINK= avertissement,acc(a),warnA(a),PAPA(a),MUTEA(a)) ; aléatoire déterministe avecRND(i), jamaisMath.random(). - Pièges : animez
x/yavec GSAP, ne définissez jamais de transformation CSS sur un élément que GSAP anime aussi ; une scènesc(t0, t1)doit couvrir chaque enfant encore en mouvement ; ne nommez pas une variable comme un assistant (rise,cl,card...).
Vérifiez avant le rendu :
python render.py check→ doit affichererr: nulletmiss: []. (Avant que la voix n'existe, vous pouvez disposer les scènes sur des timings factices :python engine/fake_words.py.)python render.py stills <8-24 times>et regardez chaque image : chevauchements, texte coupé, écrans vides, éléments apparaissant avant leur mot, couleurs hors du thème. Corrigez et regardez à nouveau.
6. Son + rendu → final.mp4
python render.py cues # liste des effets sonores depuis les scènes
<py> audio.py # SFX générés par code + fond musical original sous la voix, -14 LUFS → mix.wav
python render.py video 4 # capture 120 ips → flou de mouvement → 1080p30 final.mp4 (+ final_sheet.jpg)
Exécutez render.py video en arrière-plan ou avec un délai d'attente de 15 minutes : cela prend environ 1,5 minute par 10 s de vidéo avec 4 workers (mesuré : 38 s de vidéo en 6 min sur un PC sans GPU). Si un chunk signale des images manquantes, relancez avec moins de workers. Regardez final_sheet.jpg. Ensuite dites à l'utilisateur : le fichier, sa durée, les sources utilisées, et tout ce que vous n'avez pas pu vérifier. Rappelez-lui de lire facts.md avant de publier, et que vous ne pouvez pas entendre l'audio : c'est son écoute qui fait la véritable vérification.