Vidéo documentaire
L'utilisateur donne un sujet. Vous livrez un film terminé : out/<slug>.mp4 (1920x1080, H.264/AAC), plus .srt, CREDITS.md, le script et les sources. L'utilisateur ne doit rien avoir à installer, rechercher, écrire ou rendre lui-même. Arrêtez-vous uniquement lorsqu'une décision lui revient réellement : une génération payante, un téléchargement nécessitant une autorisation, ou une affirmation factuelle qui ne peut être vérifiée.
SKILL_DIR est ce dossier. DOC signifie python3 "$SKILL_DIR/scripts/doc.py".
1. Cadrer avant d'écrire
Posez au maximum deux questions, et seulement si elles changent le film : la durée (par défaut 3 minutes) et l'angle (ce que le film soutient, pas seulement son sujet). Tout le reste, vous décidez.
Un documentaire est un argument avec des images, pas un résumé. Choisissez une affirmation qu'un spectateur peut répéter après avoir regardé — "le gardien de phare n'a pas perdu face à la technologie, il a perdu face à un tableur" — et supprimez tout ce qui ne la sert pas.
Ne faites jamais la liste de faits. Filmez un changement : quelque chose était vrai, puis a cessé de l'être, et voici ce que cela a coûté.
2. Configuration (première utilisation uniquement)
DOC doctor
Nécessite python3 et ffmpeg avec libx264. Termux : pkg install ffmpeg. macOS : brew install ffmpeg. Si seul ffmpeg manque, installez-le et relancez. N'écrivez rien d'autre jusqu'à ce que doctor dise Prêt.
DOC new <project> --title "Le Dernier Gardien de Phare" --subtitle "1985 -- 1997"
Cela crée project.json, shots.json, research.md, script.md, et les dossiers work/img, work/audio, out.
3. Recherche
Utilisez la recherche web. Visez quatre à six sources solides : documents primaires, archives, pages universitaires ou d'agences, journalisme réputé, un livre. Lisez assez pour expliquer le mécanisme, pas seulement le résultat.
Enregistrez dans research.md :
# Recherche
## Thèse
Une phrase que le film soutient.
## Faits (chacun avec une source)
- 1841 : <fait> -- <url de la source>
- <nombre> : <fait> -- <url de la source>
## Contesté / inconnu
- <ce sur quoi les sources divergent et comment le film le formulera>
## Matériel visuel
- <archives, collections, recherches d'images probablement libres de droit>
Chaque phrase de la narration doit renvoyer à une ligne ici. Si deux sources sont en désaccord, soit le mentionnez à l'écran, soit abandonnez le fait. N'inventez pas un chiffre, une date, une citation ou une anecdote. Un fait manquant est un problème d'intrigue ; un fait faux est une fraude.
4. Écrire le script
Lisez references/script-craft.md avant d'écrire. En bref :
- 155 mots par minute. 3 min = ~460 mots. Budgetisez par acte, pas par ambiance.
- Quatre mouvements : le monde d'avant (accroche), le mécanisme (comment le changement a fonctionné), le coût (ce qu'il a fait aux gens), l'écho (retour à l'accroche, modifiée).
- Une idée par phrase. Une respiration par ligne. Pas de phrase de plus de 22 mots.
- Concret plutôt qu'abstrait. "Il a gravi 117 marches deux fois par nuit" bat "le travail était exigeant".
- Présent pour l'histoire, passé pour le verdict.
- La narration porte l'argument ; les légendes portent les preuves (noms, dates, lieux). Ne dites jamais en bande-son ce que la légende prouve déjà.
Écrivez dans script.md par actes, une phrase par ligne, car les lignes de shots.json doivent correspondre textuellement :
## Acte I -- le monde d'avant
Pendant deux cents ans, quelqu'un devait rester éveillé pour que les navires puissent trouver la côte.
...
Montrez ensuite à l'utilisateur le script entier en un seul message — environ 30 lignes — et continuez. N'attendez pas d'approbation sauf s'ils ont demandé à le relire.
5. Liste des plans
Lisez references/shot-list.md pour chaque champ et un exemple complet, puis écrivez shots.json :
{"shots": [
{"id": "s01", "kind": "card", "text": "Le Dernier Gardien de Phare",
"sub": "Un métier qui a disparu en douze ans", "hold": 4.0},
{"id": "s02", "line": "Pendant deux cents ans, quelqu'un devait rester éveillé.",
"img": "work/img/cape-byron-1891.jpg", "motion": "zoom-in",
"caption": "Cap Byron, 1891"}
]}
Règles importantes :
lineest la narration, textuellement du script, dans l'ordre. La durée vient de l'audio, donc une ligne modifiée change le montage.- 3,5 à 6 secondes par plan. Une image fixe a besoin de plus de temps que vous ne le pensez. Jamais moins de 2,5 s sauf pour un flash délibéré.
- Une image, une idée. Si un plan nécessite deux images, ce sont deux plans.
- Déplacez la caméra, pas le monde.
zoom-inpour l'intimité,zoom-outpour la conséquence,pan-*pour les paysages et documents,staticpour les visages et le texte. - Une carte est une coupure de chapitre. Utilisez 2 à 4 dans un film de 3 minutes : titre, une date ou un chiffre, et une dernière carte qui atterrit. Les cartes n'ont pas de narration.
captionest la petite ligne de preuve à l'écran : lieu, année, source. Gardez-la en moins de 6 mots.
6. Images fixes
Privilégiez le matériel d'archives réel. C'est la différence entre un documentaire et un diaporama.
DOC archive <project> --query "Phare du Cap Byron 1900" --n 3
Cela recherche sur Wikimedia Commons, télécharge les images utilisables dans work/img/, et écrit sources.json + CREDITS.md avec l'auteur et la licence. Par défaut, ne conserve que le domaine public, CC0 et CC BY / BY-SA, car un film publié nécessite généralement une utilisation commerciale. Ajoutez --license pd pour un domaine public strict, --license any pour tout voir (puis vérifiez chaque licence vous-même).
Si l'archive ne donne rien, par ordre de préférence :
- Autres collections ouvertes — Bibliothèque du Congrès, Smithsonian Open Access, NASA, Internet Archive, Europeana. Demandez à l'utilisateur avant de télécharger depuis un nouveau site, et enregistrez la licence et l'URL dans
CREDITS.md. - Générez une image avec tout outil d'image à votre disposition, en utilisant
references/image-prompts.md. Marquez les images générées dansCREDITS.mdcomme reconstruction générée par IA, et légendez-les pour qu'un spectateur ne soit jamais induit en erreur en pensant qu'il s'agit de photographies. - Plans typographiques et d'objets — un document, une carte, une page de registre, une plaque abstraite. Honnêtes et économiques.
Ne présentez jamais une image d'IA comme une archive. Cette seule ligne constitue toute l'éthique du format.
7. Narration
DOC tts <project>
Utilise ElevenLabs lorsque ELEVENLABS_API_KEY est définie (meilleur), sinon une voix hors ligne (espeak-ng, Android termux-tts-speak, macOS say). Une seule prise. Écrivez pour l'oreille : phrases courtes, pas de virelangues, nombres épelés comme ils sont dits.
S'il n'y a aucune voix, le film est quand même rendu avec des durées estimées — dites-le, et fournissez le .srt pour que l'utilisateur puisse enregistrer sa propre narration plus tard. Gardez line inchangé afin qu'un réenregistrement s'insère directement.
La qualité d'enregistrement prime sur la qualité du modèle : un enregistrement sur téléphone dans une pièce silencieuse est meilleur qu'une voix synthétique pour la plupart des documentaires. Proposez-le.
8. Construire et regarder
DOC build <project> --draft # passage rapide pour itérer
DOC build <project> --subs # version finale, sous-titres incrustés
DOC sheet <project> # planche contact de 12 images
Regardez out/contact.jpg à chaque fois. Vérifiez :
- rien d'important ne se trouve sous une légende, et aucune légende ne sort du cadre ;
- les coupes tombent sur des fins de phrase, et aucun plan ne s'attarde sur une partie vide ou non pertinente d'une image ;
- l'étalonnage est cohérent, les visages ne sont pas écrasés, et les images de texte sont lisibles ;
- la dernière carte arrive après la fin de la narration, pas par-dessus.
Corrigez en modifiant shots.json (image, mouvement, légende, ordre) et reconstruisez. Les plans intérieurs sont mis en cache par identifiant de plan, donc seuls les plans modifiés sont recalculés.
Vitesse. Le rendu est limité par le processeur. En 1080p, un film de trois minutes prend environ une minute sur un ordinateur portable et 10 à 20 minutes sur un téléphone. Itérez toujours avec --draft (demi-résolution, préréglage rapide), et faites un seul passage complet à la fin. build affiche chaque plan au fur et à mesure, vous pouvez donc arrêter un rendu visiblement erroné.
9. Musique
Demandez avant d'ajouter de la musique. Suggérez une source, vérifiez la licence, placez le fichier dans public/music/bed.mp3, puis :
DOC build <project> --music public/music/bed.mp3
Elle boucle, se place à ~14% et s'atténue automatiquement sous la voix. Le silence est un choix légitime et souvent le meilleur pour un film sérieux.
10. Livrer
Donnez à l'utilisateur :
- le MP4 ;
- le
.srt(utile aussi sur YouTube) ; CREDITS.md— chaque image, auteur, licence, lien ;- le script, un paragraphe sur l'angle, et 3 à 5 liens de sources ;
- une note honnête sur ce qui est d'archives, ce qui est généré, et ce qui a été coupé par manque de preuves.
Proposez ensuite une prochaine étape : un montage plus long, une ouverture différente, un second acte, ou le même film sous forme de coupe verticale de 60 secondes.
Bon jugement
- Le film est l'argument, pas les images. Si les images sont belles mais que l'affirmation est vague, réécrivez.
- Coupez le troisième exemple. Deux prouvent un schéma ; trois sont une liste.
- Sources à l'écran, pas seulement dans la description. Une légende avec une année et un lieu rend un spectateur confiant dans le reste.
- **Dites ce que vous ignorez." "Personne ne s'accorde sur le nombre" est une phrase plus forte qu'un chiffre erroné sûr.
- Respectez les morts. Personnes réelles, événements réels : pas de dialogue inventé, pas de reconstitution présentée comme un enregistrement, pas de visages générés pour des individus nommés.
- La durée est une promesse. Si le matériau ne supporte que 90 secondes, livrez 90 secondes.
Fichiers
scripts/doc.py— tout le pipeline (DOC -hpour chaque option).references/script-craft.md— comment écrire une narration qui sonne comme un film.references/shot-list.md— schéma complet deshots.jsonet exemple pratique.references/sourcing.md— archives, règles de licence, format d'attribution.references/image-prompts.md— instructions pour les images générées qui s'accordent avec les archives.examples/last-lightkeeper/— un exemple terminé (script + plans).