Production Documentaire AI

Première utilisation : d'abord l'environnement

Images : Par défaut, l'utilisateur génère les images avec GPT, l'AI n'appelle pas d'API d'images ; image_mode=agent nécessite une approbation explicite.
Environnement : Python 3.10+, ffmpeg, ffprobe ; contact_sheet.py nécessite Pillow ; pas de dépendance PyYAML.
H3 : Si MiniMax H3 n'est pas configuré, voir d'abord references/00_setup.md :
- Inscription / vérification d'identité / rechargement sur la plateforme ouverte ;
- Création d'une clé API ;
- Variable d'environnement MINIMAX_API_KEY ou fichier de clé ;
- Aligner base_url / nom du modèle / résolution ;
- Tester d'abord avec une vidéo de 4 secondes, puis en batch.
Ne pas inclure la clé dans le code, les logs ou git.
Si H3 n'est pas disponible, changer de fournisseur ou faire d'abord un animatic, ne pas faire semblant de pouvoir générer.
Sans H3 configuré, ne pas passer en G5.

Quand utiliser

L'utilisateur veut réaliser un court-métrage sur un personnage/thème dont la durée est déterminée par le brief ;
30 secondes, 1 minute, 3 minutes ne sont que des exemples, pas une fourchette stricte ;
Avec des personnages réels, des données historiques, des reconstitutions AI ;
Besoin d'aller de zéro à un produit livrable ;
Besoin de contrôler les coûts, de conserver les sources, d'écrire les crédits.

Ne convient pas

Portraits de groupe, longs métrages de type interview ;
Publicités commerciales, spots produits purs ;
Animation pure, production virtuelle pure ;
Documentaires de terrain nécessitant un tournage réel.

La durée n'a pas de seuil strict ; les projets très longs nécessitent une gestion supplémentaire des actifs, mais le processus reste le même.

Questions à poser avant de commencer

Durée finale, format d'image, fréquence d'images, langue, plateforme ;
Qui est le personnage, quelle période, quels faits ne doivent pas être erronés ;
Budget maximum, autorisation de réessayer ;
Qui génère les images (image_mode=human/agent), quel modèle pour la vidéo, quel logiciel de montage ;
Voix off réelle ou TTS ; musique sur une piste séparée ou non ;
Y a-t-il des droits sur les photos/musiques historiques ; besoin d'une déclaration AI ;
Format de livraison et date limite ;
Profil : short (environ 15-60s) / standard (environ 2-5min) / custom (sur demande) ;
model_routing : hybrid / gpt_only / codex_deepseek ;
H3 est-il configuré (clé/base_url/modèle/limite) ; si non, enseigner d'abord la configuration ;
Carte d'ouverture : none / static ; durée en secondes ; incluse ou non dans la durée cible ; le titre sera déterminé en G2.5.

Sans brief, ne pas passer à la recherche.

Durée et profil

La durée est déterminée par duration_target_sec dans project.yaml, non codée en dur.

profil	durée exemple	nombre de plans (exemple)	segments (exemple)	musique (exemple)
short	15-60s	8-18	1-2	1 segment
standard	2-5min	24-60	3-5	3-5 segments
custom	défini par l'utilisateur	défini par l'utilisateur	défini par l'utilisateur	défini par l'utilisateur

Ce sont des estimations, pas des barrières ; 30 secondes et 3 minutes ne sont que deux exemples courants.

Transmission des images en G4

Une fois les prompts terminés, avertir d'abord l'utilisateur de générer les images, puis faire le travail en parallèle :

Envoyer image_batch_request.md : numéro de plan, nom de fichier, emplacement du prompt, quantité, priorité ; si la carte d'ouverture est activée, 0-1_card.png fait partie du premier lot ;
Dire clairement : "Vous pouvez maintenant commencer à générer les images" ;
Une fois l'utilisateur commencé, l'agent fait le travail qui ne dépend pas des images/vidéos : sous-titres, cue sheet, tableau des coûts, sources/crédits, squelette de montage, QA des promts du lot suivant ;
Ne pas réviser les images, ne pas générer de vidéo, ne pas faire le montage final ;
Une fois l'utilisateur a renvoyé les images, réviser d'abord les images, ne pas rediscuter de la narration/des plans déjà verrouillés ;
La carte d'ouverture est une image statique, ne pas faire de H3 ; vérifier le texte mot à mot, si le chinois est instable, ajouter du texte superposé en post-production.

Ne pas faire autre chose en silence en faisant attendre l'utilisateur ; la tâche de génération d'images doit d'abord être transmise. Voir references/13_parallel_work.md pour plus de détails.

Routage des modèles

Par défaut hybrid :

Phase	Modèle	Rôle
G0-G3	Codex + DeepSeek	Brief, recherche, narration, storyboard, prompts
G4	GPT	Génération/révision d'images ; `image_mode` décide qui génère
G5-G8	Codex + DeepSeek	Tâches, coûts, fichiers de montage, QC ; basculer temporairement sur GPT pour voir les images

DeepSeek pour le texte et les fichiers, GPT pour les pixels et le visuel ;
image_mode=human : l'utilisateur génère avec GPT ; image_mode=agent : Codex + outil d'image génère (nécessite une approbation explicite) ;
Écrire image_handoff.md avant le basculement, le fichier projet est le justificatif de transmission ;
Voir references/10_model_routing.md pour plus de détails.

8 phases et les barrières G0-G8

Phase	Livrable	Barrière
G0 Brief	`project_brief.md`	Durée, budget, droits, plateforme verrouillés
Recherche/Vérification des faits	`fact_check.csv`, `research.md`	G1 Faits verrouillés
Scénario/Narration	`script.md`, `vo.csv`, `vo_text_review.md`, `voice_audition.md`, `vo_lock.md`, `vo_review.md`	G2 Narration verrouillée (texte + timbre + version)
Storyboard/Timeline	`beats.csv`, `shots.csv`, `segments.csv`, `timeline.csv`, `animatic.mp4`, `v0_review.md`	G3 Beats attribués + tableau des plans + v0 confirmé
Première image (selon image_mode)	`首帧/`, `image_review.md`, `image_handoff.md`, `image_batch_request.md`	G4 Première image verrouillée
Génération vidéo	`h3_package/`, `clips/`, `tasks.json`, `cost.csv`	G5 Vidéo verrouillée
Montage brut/Sous-titres	`cut/`, `subtitles.srt`	G6 Image verrouillée
Musique/Effets sonores	`music/`, `cue_sheet.csv`	G7 Son verrouillé
Contrôle final/Livraison	`final.mp4`, `final_qc.md`, `credits.md`	G8 Livraison

Règle : ne pas passer à l'étape suivante tant que la précédente n'est pas verrouillée, ne pas dépenser d'argent.

Carte d'ouverture

Ne demander en G0 que "oui/non, durée en secondes, incluse dans la durée cible" ; le titre sera déterminé en G2.5.

G0 : opening_card: none|static ; opening_seconds ; opening_in_target ;
G2.5 : Titre principal/sous-titre/style de police ; opening_card.md confirmation mot à mot ;
G3 : Inscrire comme plan statique 0-1 dans shots.csv (static=yes, sans narration), une ligne CARD dans segments.csv (static=yes) ;
G4 : Premier lot de génération d'images, nom de fichier 首帧/0-1_card.png ; vérifier le texte mot à mot en même temps que l'image ;
G5 : Ne pas faire de H3 ; export_h3.py ignore static=yes, la tâche H3 ne l'inclut pas ;
G6 : Maintenir statique dans le montage ; possible d'ajouter un zoom avant lent de 1-2% ;
La durée de la carte d'ouverture est déduite de la durée cible, ou ajoutée explicitement à la durée totale, décidé en G0.

La carte d'ouverture est "une décision de durée au moment du lancement du projet", pas "une option décorative au moment de la génération d'images".

Ordre de la révision de la narration

Révision du texte : Montrer à l'utilisateur le vo.csv complet, les timecodes, les notes factuelles ; attendre la confirmation de l'utilisateur avant de faire la voix ;
Audition des timbres : Générer 2-3 candidats sur la même phrase, l'utilisateur choisit A/B/C ou enregistre lui-même ;
Scratch complet : Générer la narration complète avec le timbre choisi ;
v0 animatic : Faire ensuite l'animatic à images fixes + narration ;
Si une étape n'est pas confirmée, ne pas passer à la suivante.

La narration d'abord

C'est l'ordre central de cette compétence :

D'abord la narration, ensuite les plans, la première image, la vidéo ;
Une phrase de narration avec 2-3 plans est la norme ;
Un plan par phrase est un cas particulier (réaction brève, slogan, montage mono-plan), pas par défaut ;
La narration forme un fichier vo.csv indépendant, ne pas la découper par plan ;
Ne pas générer le TTS par plan ; le faire par phrase/segment, placer le segment entier sur une piste audio ;
Chaque phrase contient une information ; chaque 1-2 phrases au moins une information concrète (année/nom/chiffre/action/cause-effet) ;
Les images poétiques doivent avoir une ancre concrète, une chaîne, être réalisables ; "porte/graine" peut être un motif, pas une erreur automatique ; les slogans sans ancre sont des mots vides ; d'abord expliquer la cause et l'effet, ensuite la poésie ;
Après l'écriture, lancer d'abord narration_lint.py, puis relire une fois pour validation ;
Utiliser J-cut/L-cut au montage : l'image change, la narration continue ;
Laisser un silence de 0,3 à 1,0 seconde entre les phrases ; une narration de 5 secondes ne doit pas être collée exactement sur une image de 5 secondes ; il est préférable que le silence soit porté par un court plan sans narration, plutôt que d'être placé à l'intérieur d'un plan avec narration ;
Le silence ne se place qu'entre les phrases de narration ; le point de coupe doit être dans le silence, pas à l'intérieur d'une phrase avec narration ;
Après le verrouillage de la narration, ne pas modifier directement l'ancienne version ; lancer d'abord vo_diff.py, ne modifier que les fichiers impactés ;
Un segment de narration peut couvrir plusieurs plans ; un plan normal peut avoir au maximum un segment de narration ; un plan long (long_take=yes) peut contenir plusieurs segments de narration, mais chaque segment doit être entièrement contenu dans le plan ;
La fenêtre de silence entre deux narrations adjacentes doit contenir au moins un point de coupe de plan ; le début et la fin d'une phrase peuvent tomber à l'intérieur d'un plan, ils ne doivent pas nécessairement coïncider avec le point de coupe ; en cas d'intervalle, prendre le silence le plus grand ;
Après avoir ordonné shots.csv / timeline.csv, produire d'abord un animatic v0 (images fixes/noires + narration), avertir clairement l'utilisateur d'écouter les silences entre les phrases ; après confirmation, passer à la première image/à la vidéo ;
Montrer d'abord le texte, puis choisir le timbre, puis faire le v0 : sans confirmation du texte et du timbre par l'utilisateur, ne pas générer de TTS/animatic.

D'abord la narration, ensuite les images ; pas d'abord 40 plans, puis essayer de mettre une phrase dans chaque plan.

Contrat des fichiers

`shots.csv`

id,story_segment,scene_id,duration,shot_size,camera,scene,action,expression,vo_ids,anchor,first_frame,video,status,cost,notes,long_take,static

story_segment est le numéro du segment narratif, pas le segment de génération H3 ; le segment de génération est dans generation_id de segments.csv ;
scene_id est le numéro de la scène, doit correspondre à segments.csv ;
duration en secondes, supporte les décimales ;
status utilise seulement todo/image_ready/video_running/video_ok/conditional/retake/final ;
vo_ids peut être vide ; un plan normal a au plus un vo_id ; un plan long (long_take=yes) peut avoir V01|V02 ;
long_take=yes : un plan long continu, peut avoir 2 segments de narration ou plus, mais chaque segment doit être entièrement dans le plan ;
static=yes : carte d'ouverture/carte d'insertion statique, pas de H3 ; doit avoir first_frame, segments.csv utilise un segment static=yes ;
C'est la source de vérité pour l'image ; la narration est dans vo.csv, les deux sont liés par vo_ids.

`vo.csv`

vo_id,start,end,text,shot_ids,notes
V01,0.0,4.2,"Une phrase de narration complète","1-1|1-2","4.2s ; silence de 0,8s après la phrase"
V02,5.0,6.2,"Phrase suivante","1-3","1.2s ; silence de 0,8s en fin de phrase"

start/end sont en secondes absolues ;
Une phrase de narration peut couvrir 2-3 plans ;
Un plan par phrase n'est utilisé que dans des cas particuliers ;
Laisser un silence de 0,3 à 1,0 seconde entre les phrases ;
Un shot_id ne peut appartenir qu'à un seul cue ; un cue peut couvrir plusieurs shots ;
Les sous-titres sont générés à partir de vo.csv, pas liés aux plans.

`beats.csv`

beat_id,story_segment,kind,shot_id,vo_id,text,notes
B01,1,action,1-1,V01,Calcule derrière le comptoir,
B02,1,action,2-1,V02,Mettre le papier dans l'enveloppe,

Le beat est l'unité minimale de l'histoire, pas un battement musical ;
Chaque beat est exactement attribué à un seul shot_id ;
Chaque plan non static a au moins un beat ; une carte d'ouverture static=yes peut n'avoir aucun beat ; chaque segment de narration a au moins un beat ;
Une narration peut couvrir plusieurs beats, en répétant le même vo_id dans chaque ligne ;
L'ordre des beats doit correspondre à l'ordre des plans ; les beats manquants, en double ou désordonnés sont bloqués par validate.py.

`segments.csv`

generation_id,scene_id,cut_order,shot_id,start,end,duration,keyframe,static,notes
S01,1,1,1-1,0,5,5,首帧/1-1_first.png,no,Coupe unique
S02,1,1,1-2,5,9,4,首帧/1-2_first.png,no,Coupe 1 dans le segment
S02,1,2,1-3,9,15,6,首帧/1-3_first.png,no,Coupe 2 dans le segment

generation_id = une génération H3 ; un segment ≤15 secondes, ne change pas de scène ;
scene_id doit être égal au scene_id du même plan dans shots.csv ; un changement de scène nécessite un changement de segment ;
cut_order = numéro de coupe dans le segment, commence à 1 et continu ;
keyframe = image d'ancrage pour la composition de cette coupe ; la première coupe est fixée à 0,00 seconde, les suivantes au point de coupe ;
static=yes = carte statique, pas de H3 ; doit être une coupe unique ; export_h3.py l'ignorera ;
Chaque shot ne peut apparaître que dans une seule generation ;
Les start/end/duration de chaque coupe doivent être égaux aux cumuls de shots.csv ; tout le film doit être sans interruption et sans chevauchement ;
validate.py bloque les débordements, les décalages, les interruptions et les doublons.

`h3_prompts.csv`

shot_id,prompt,soundscape,notes
1-1,"Garder la première image ; la pointe du stylo se déplace lentement, la flamme vacille légèrement.","Bruit du papier et du stylo, bruit du vent au loin.",

export_h3.py regroupe selon segments.csv et assemble les prompts de chaque coupe en un prompt multi-images aligné ;
Sortie h3_package/<generation_id>/prompt.md + manifest.json ;
N'appelle pas d'API ; la génération est toujours effectuée par la tâche H3.

Versions de la narration

vo_versions/vo_v1.csv
vo_v1_scratch.wav
vo_lock.md

Avant le verrouillage, faire une lecture test/TTS pour mesurer la durée réelle ;
Après le verrouillage, ne créer que de nouvelles versions, ne pas modifier directement l'ancienne ;
Pour modifier la narration, lancer d'abord vo_diff.py, puis ne modifier que les fichiers impactés ;
Voir references/12_change_control.md pour plus de détails.

`project.json`

Configuration machine générée par init_project.py : profile/model_routing/image_mode/duration_target_sec/shot_target/fps/resolution/providers.
project.yaml est la version lisible par l'humain ; les scripts lisent project.json.

`tasks.json`

[{"generation_id":"S01","provider":"minimax_h3","model":"MiniMax-H3","resolution":"768P","duration":9,"status":"todo","prompt":"h3_package/S01/prompt.md","first_frames":["首帧_h3/1-1_first.png"],"cost_cny":0.0}]

generation_id correspond au segment de génération dans segments.csv ;
duration doit être un entier entre 4 et 15 ;
prompt / first_frames sont les chemins du package de production ;
Les tâches échouées ne sont pas facturées ; les tentatives sont listées séparément ;
Les anciennes tâches par plan peuvent utiliser id, mais h3_tasks.json utilise toujours generation_id.

Package de livraison

final.mp4
subtitles.srt
vo.wav
vo.csv
music/A-E.wav + cue_sheet.csv
credits.md
source_list.csv
fact_check.csv
final_qc.md

Règles strictes

Les images sont par défaut générées par l'utilisateur via GPT, l'AI n'appelle pas d'API d'images ; uniquement quand image_mode=agent et avec l'approbation explicite de l'utilisateur, les outils d'image sont autorisés ;
La vidéo est par défaut en version unique, une version de remplacement n'est faite qu'en cas d'échec ;
Les vidéos générées ne peuvent contenir que des sons ambiants/voix, pas de musique/BGM ;
Les sources en 768P peuvent être en 1344×768 (7:4), le rendu final est en 1920×1080 ;
La première image doit être en 16:9, sinon le rapport d'aspect de l'image vers la vidéo dérivera ;
Les photos historiques doivent avoir une source, les images AI doivent être marquées "reconstitution" ;
Sous-titres : 16-20 caractères/ligne, maximum 2 lignes, marges gauche/droite ≥100px ;
Chaque segment musical doit avoir une poignée de 1,5 à 2 secondes, un creux n'est pas un silence ;
Les coûts sont basés sur les logs des tâches, pas sur la mémoire ;
Avant la livraison, utiliser ffprobe pour vérifier la résolution, la fréquence d'images et l'audio ;
D'abord la narration, ensuite les plans ; par défaut, une phrase de narration couvre 2-3 plans, un plan par phrase est un cas particulier ;
La narration ne doit pas remplir l'image ; une narration de 5 secondes avec une image de 5 secondes sera pressée, laisser un silence de 0,3 à 1,0 seconde entre les phrases ;
La narration peut être poétique, mais la poésie doit avoir une ancre concrète/une action ; seules les sections d'explication exigent une information concrète par phrase ; ne pas mélanger les deux standards ;
Après le verrouillage de la narration, il est interdit de réécrire tout le projet pour une seule phrase modifiée ; lancer d'abord vo_diff.py, puis ne modifier que les fichiers impactés ;
Une fois les prompts G4 terminés, avertir d'abord l'utilisateur de générer les images ; une fois que l'utilisateur a commencé, faire le travail en parallèle qui ne dépend pas des images/vidéos ;
Un segment de narration peut couvrir plusieurs plans ; un plan normal peut avoir au maximum un segment de narration ; un plan long (long_take=yes) peut contenir plusieurs segments de narration, mais ils doivent tous être dans le plan ;
La fenêtre de silence doit contenir un point de coupe de plan ; ne pas exiger que le début et la fin d'une phrase soient collés au point de coupe ; en cas d'intervalle de silence, prendre le plus grand ;
Après la sortie de l'animatic v0, avertir d'abord l'utilisateur de vérifier les silences entre les phrases ; avant confirmation, ne pas sortir la première image, ne pas générer de vidéo ;
Le timbre doit être choisi par l'utilisateur après avoir écouté 2-3 candidats ; ne pas utiliser un TTS par défaut ;
La narration est par défaut "claire mais pas littérale" : d'abord expliquer le personnage/l'événement/la causalité, puis utiliser des images concrètes et des phrases courtes pour créer un espace ; 1-2 phrases supplémentaires sont autorisées, mais chaque phrase doit apporter une nouvelle information ou une nouvelle image, ne pas utiliser d'adjectifs pour remplir le temps ;
Chaque beat dans beats.csv doit être attribué exactement à un plan ; chaque plan, chaque segment de narration doit avoir un beat qui le couvre ; les beats manquants, en double ou désordonnés sont bloqués par validate.py ;
Dans segments.csv, un segment ≤15 secondes ; l'ordre des coupes dans le segment est continu, chaque coupe a une image clé, chaque shot n'apparaît qu'une seule fois ; les débuts et fins de chaque coupe doivent être égaux aux temps cumulés dans shots.csv ; l'alignement multi-images H3 utilise export_h3.py pour produire le package de production ;
Carte d'ouverture : G0 fixe la durée, G2.5 fixe le texte, G3 écrit 0-1 static=yes, G4 génère l'image, G5 ne fait pas de H3.

Fournisseur

config/providers.yaml est la documentation ; la configuration machine est providers.json (généré par init_project.py, sera vérifié par timeline.py).

Par défaut : images=user_gpt, vidéo=minimax_h3, narration=capcut_tts, musique=local_midi_fluidsynth, montage=capcut, QC=ffmpeg.

Le fournisseur d'images est toujours human ; cette règle ne change pas avec la configuration.

Commandes

python scripts/init_project.py --root my-film --profile short --duration 30 --shots 10 --segments 2
python scripts/timeline.py --shots shots.csv --vo vo.csv --vo-out vo_report.csv --project project.json --min-gap 0.4
python scripts/timeline.py --shots shots.csv --vo vo.csv --max-density 0.85 --allow-single
python scripts/narration_lint.py --text vo.csv --style lyrical --max-chars 28
python scripts/validate.py --shots shots.csv --vo vo.csv --beats beats.csv --segments segments.csv --project project.json
python scripts/validate.py --shots shots.csv --vo vo.csv --beats beats.csv --segments segments.csv --project project.json --strict-files
python scripts/validate_tasks.py --tasks h3_tasks.json --segments segments.csv
python scripts/selftest.py
python scripts/export_h3.py --shots shots.csv --segments segments.csv --prompts h3_prompts.csv --out h3_package
python scripts/timeline.py --shots shots.csv --vo vo.csv --animatic animatic.mp4
python scripts/vo_gap_report.py --vo vo.csv --audio vo_scratch.wav --out vo_gap.md
python scripts/vo_diff.py --old vo_versions/vo_v1.csv --new vo.csv --out vo_diff.md
python scripts/vo2srt.py --vo vo.csv --out subtitles.srt --max-chars 18
python scripts/contact_sheet.py --clips clips --out review --frames 6
python scripts/cost_report.py --tasks tasks.json --out cost.csv --default-model MiniMax-H3

Scripts : init_project.py, validate.py, selftest.py, export_h3.py, timeline.py, narration_lint.py, vo2srt.py, vo_gap_report.py, vo_diff.py, contact_sheet.py, cost_report.py. --animatic par défaut utilise un cadre noir si la première image manque, --animatic-missing error peut être utilisé pour signaler une erreur.

validate.py gère les contrats de structure (schéma / beats / coupes segment / couverture) ; G3 ne vérifie pas les fichiers d'images clés par défaut, G5 utilise --strict-files pour vérifier. timeline.py --vo gère le temps (silence / densité / plans longs). Les deux sont exécutés, ils ne se remplacent pas mutuellement.

Gestion des échecs

Échec vidéo : vérifier l'état de la tâche ; l'échec n'est pas facturé ; changer pour H3-Max ou modifier la première image, ne pas relancer aveuglément ;
Visage qui change/mains supplémentaires : regénérer ou utiliser un profil/une vue de dos ;
Action non réalisée : regénérer, ne pas essayer de la réparer au montage ;
Débordement des sous-titres : modifier le style/les sauts de ligne, ne pas rétrécir jusqu'à devenir illisible ;
Musique abrupte : ajouter un pickup, une rampe d'expression, une poignée, ne pas couper brutalement ;
Mauvais rapport d'export : revenir dans le projet et le régler à 1920×1080, ne pas étirer.

Références

SOP.md : Processus et checklist pour les humains
references/ : Détails des phases (inclut 00_setup.md, 09_vo_spans.md, 10_model_routing.md, 11_narration.md, 12_change_control.md, 13_parallel_work.md, 14_v0_animatic.md, 15_beats_segments.md)
providers/ : Outils remplaçables
templates/ : Fiche projet, tableau des plans, prompts, fiche de révision, cue sheet, crédits, contrôle final

yinguozhang/ai-documentary-production

Qu'est-ce que ai-documentary-production ?

Demander à votre IA préférée

Documentation