Communitygithub.com

documentary-maker

Créez un court documentaire 2D animé (30 s à 3 min) à partir d'une phrase : recherche sourcée, script narratif, voix hors-ligne (Kokoro), timings des mots (Whisper), scènes animées où chaque élément visuel coïncide avec une parole, effets sonores et musique générés par code, et une vidéo MP4 1080p.

Qu'est-ce que documentary-maker ?

Cette compétence transforme n'importe quelle phrase en un documentaire animé complet, en gérant de bout en bout la recherche, l'écriture, la narration, l'animation et le montage, le tout localement sur la machine de l'utilisateur. Elle est conçue pour les agents AI comme Claude Code, qui orchestrent six étapes : recherche et vérification des faits avec sources, rédaction d'un script concis (environ 2,4 mots par seconde), synthèse vocale via Kokoro (voix multiples, hors-ligne), alignement des paroles aux animations avec Whisper, création de scènes animées en SVG/GSAP où chaque mot prononcé déclenche un élément visuel, et enfin rendu audio (effets sonores et musique) et vidéo (1080p30). La sortie est un fichier MP4 accompagné d'une fiche récapitulative. L'outil supporte Windows, macOS et Linux, nécessite Node, FFmpeg et un navigateur Chromium. C'est idéal pour produire rapidement des vidéos explicatives, historiques ou éducatives sans frais supplémentaires (hors abonnement Claude).

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mehedi11234/claude-documentary-maker/tree/HEAD/documentary-maker

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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.md avec 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 avec WA('mot', 'alternative') (début) et WEnd(...) (fin) ; terminez par B.end = endAfterVoice(2.0); _wc = 0;. Ensuite build() 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 cartes card() + fly(), stamp() / warnStamp(), counter(), burst(), suspectCard(), quoteCard(), timeline(), dateTag(), typeText(). Voir engine/lib.js et engine/doc.js pour 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.KEYWORDS pour 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 avec RND(i), jamais Math.random().
  • Pièges : animez x/y avec GSAP, ne définissez jamais de transformation CSS sur un élément que GSAP anime aussi ; une scène sc(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 :

  1. python render.py check → doit afficher err: null et miss: []. (Avant que la voix n'existe, vous pouvez disposer les scènes sur des timings factices : python engine/fake_words.py.)
  2. 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.

Skills associés