Workflow de production vidéo

Ceci est le workflow de production unique pour les nouvelles vidéos dans ce dépôt. video-director est propriétaire du résultat final et du statut. Utilisez .claude/skills/viral-tech-video-creator/SKILL.md pour les techniques de recherche et d'écriture et .claude/skills/video-shotcraft/SKILL.md pour les références de plans, de mouvement et de son. Lorsque ces ressources sont en désaccord avec ce fichier, suivez ce fichier. Lisez CLAUDE.md et les références sélectionnées avant de travailler. Répondez en vietnamien ; écrivez le code en anglais.

Le workflow est entièrement automatique : les agents produisent, révisent et approuvent eux-mêmes les points de contrôle, et aucune étape n'attend l'approbation manuelle de l'utilisateur. Ne terminez jamais un tour ou un rapport d'agent par « gửi bạn nghe thử / duyệt giúp / OK chưa » ; choisissez la meilleure option, enregistrez la décision dans docs/<vid>/ et continuez. Demandez à l'utilisateur uniquement lorsqu'une entrée critique est manquante et ne peut être déduite de manière sûre, ou lorsque l'utilisateur a explicitement demandé un point de décision. Les écoutes humaines (audio, MP4 final) sont des enregistrements facultatifs, jamais des questions ou des blocages. Les réviseurs indépendants utilisent un contexte propre. Ne conservez textuellement que les lignes de l'utilisateur que celui-ci a marquées comme obligatoires ; tout le reste peut être dramatisé ou réécrit pour servir l'histoire (voir la leçon du gate-A dans les points d'échec courants). La publication nécessite une demande utilisateur séparée.

Mode léger. Pour une vidéo story courte, ou lorsque l'utilisateur a fourni le script/la voix, le directeur peut fusionner des étapes sans supprimer aucun point de contrôle : un research-agent, pas de fichier de recherche lorsque le compte de l'utilisateur est la source, les trois branches de la phase 3 en un message parallèle, et task-planner avec un scene-agent pour 3-4 plans. Les points de contrôle A, D, E, B, C, les révisions des branches contenu et audio, la discipline de correction et la propriété des fichiers restent toujours.

Schéma du pipeline

Après le point de contrôle A, le travail bifurque en trois branches parallèles (contenu, audio, design), chacune avec sa propre boucle producteur → réviseur en contexte propre. Lorsque les trois réussissent, video-director les rejoint et le point de contrôle E examine le plan combiné avant la construction.

flowchart TD
  P0["0 Réception<br/>intake-agent ×2-3"] --> P1["1 Recherche<br/>research-agent ×N"]
  P1 --> P2["2 Script<br/>script-agent"]
  P2 --> A{"Gate A ≥ 9<br/>script-reviewer"}
  A -- "réviser (≤3 rounds)" --> P2
  A -- réussi --> FORK(("fork"))

  subgraph BR["3 · Trois branches parallèles"]
    direction LR
    subgraph B1["3a Contenu"]
      CA["content-agent<br/>content-pack.md"] --> CR{"content-reviewer ≥ 9"}
      CR -- réviser --> CA
    end
    subgraph B2["3b Audio"]
      VA["voice-agent + audio-agent<br/>sN.mp3, BGM/SFX, plan de mix"] --> AR{"audio-reviewer ≥ 9"}
      AR -- réviser --> VA
    end
    subgraph B3["3c Design"]
      DA["design-agent<br/>proto, style frames, couverture, board"] --> DR{"Gate D ≥ 9<br/>design-reviewer"}
      DR -- réviser --> DA
    end
  end

  FORK --> CA
  FORK --> VA
  FORK --> DA
  CR -- réussi --> J
  AR -- réussi --> J
  DR -- réussi --> J
  J["4 Jointure<br/>video-director: voice.json, timeline.ts,<br/>réconcilier timing / texte / mood"] --> E{"Gate E ≥ 9<br/>integration-reviewer"}
  E -- "ticket → branche propriétaire" --> BR
  E -- réussi --> P6["6 Tâches<br/>task-planner"]
  J -.->|échafaudage précoce| P7
  P6 --> B{"Gate B ≥ 8<br/>task-reviewer"}
  B -- réussi --> P7["7 Construction<br/>scene-agent ×N"]
  P7 --> P8["8 QA<br/>qa-agent ×N"]
  P8 --> P9["9 Rendu<br/>render-agent"]
  P9 --> C{"Gate C ≥ 8 · BARRIÈRE FINALE<br/>re-test complet sur le MP4<br/>final-check.md tout ✓ + video-reviewer ×3"}
  C -- "correction → propriétaire, re-rendu, re-test complet" --> P7
  C -- réussi --> P10["10 Livraison<br/>video-director"]

Texte de repli : 0 Réception → 1 Recherche → 2 Script ⇒ A → fork[ 3a content-agent ⇒ content-reviewer | 3b voix+audio ⇒ audio-reviewer | 3c design-agent ⇒ D ] → 4 Jointure → E → 6 Tâches ⇒ B → 7 Construction → 8 QA → 9 Rendu ⇒ C → 10 Livraison.

Convention et nommage

Une vidéo a un ID de sujet unique en kebab-case minuscule <vid>, un slug de voix <voice>, docs/<vid>/, src/<vid>/, public/audio/<vid>/ et out/qa/<vid>-*.png.
La seule vidéo finale est out/<vid>-<voice>-reel.mp4, par exemple out/cam-on-phien-ban-minh-anh-khoi-reel.mp4. Le slug de voix décrit la voix réellement entendue. Lorsque la voix change, exécutez python3 -I scripts/pipeline.py voice <vid> <new-voice> avant le rendu ; le fichier précédent reste disponible.
Commencez par python3 -m unittest scripts.test_voice_catalog pour vous assurer que les aperçus du catalogue se résolvent. Choisissez un candidat dans vietnamese-voice-samples/previews/ (le dossier est le catalogue ; les noms de fichiers sont des noms de voix raccourcis) selon la description du catalogue et la demande de l'utilisateur, et enregistrez le fournisseur et son ID de voix dans brief.md. Un aperçu ne confère en soi aucun droit commercial ou de clonage.
Après la vérification de doublon de sujet de la phase 0, initialisez une fois : python3 -I scripts/pipeline.py init <vid> --comp <CompId> --voice <voice> --profile story|product|knowledge|news. --voice est requis pour une nouvelle production : transmettez la meilleure estimation actuelle, puis exécutez pipeline.py voice <vid> <slug> dès que la voie est décidée (le slug doit nommer la voix réellement entendue) ; --out est uniquement pour les noms de sortie hérités. Démarrez ou réutilisez le Pipeline Monitor sur le port 4180 avant de dispatcher les agents de production. Ne modifiez pas status.json manuellement.
Autour de chaque étape de travail, appelez pipeline.py set <vid> <stage> in_progress puis done, blocked ou failed. Les étapes sont research, brief, script, content, voice, design, build, audio, qa, render (content existe depuis le workflow v3, que init crée ; une vidéo v2 en cours qui n'a que le point de contrôle A examiné passe en v3 avec pipeline.py upgrade <vid>). La commande render met à jour sa propre étape. Les points de contrôle de révision s'exécutent dans l'ordre A → [content · audio · D] → E → B → C ; les deux révisions de branches sont enregistrées comme des points de contrôle (review <vid> content|audio …, gate <vid> content|audio, override au plafond de 3) et le point E refuse tant que content, audio et D ne sont pas tous acceptés. Les points de contrôle A, content, audio, D et E réussissent à 9/10, B et C à 8 (pipeline.py applique le score).
Activité des agents (alimente le moniteur). Chaque fois que video-director dispatche un agent, exécutez pipeline.py agent <vid> <agent-name> running --stage <stage> --note "<task>" ; lorsque sa notification d'achèvement arrive, exécutez pipeline.py agent <vid> <agent-name> done (ou failed). Les copies parallèles utilisent un nom numéroté (scene-agent-1, research-agent-2). Sans ces enregistrements, le moniteur ne peut que deviner à partir des états d'étape, et les réviseurs ne s'allument jamais. Un point de contrôle ne réussit que si le score atteint le seuil ET qu'aucun ticket Cao/Trung n'est ouvert (voir Discipline de correction) ; pipeline.py ne peut pas voir les tickets, donc le réviseur définit --verdict revise tant qu'un ticket est ouvert.

Phase	Étape(s) à définir	Point de contrôle / Checkpoint
0 Réception	— (init)	—
1 Recherche	`research`	—
2 Script	`brief`, `script`	A
3a Branche contenu	`content`	review `content` (`content-reviewer`)
3b Branche audio	`voice`, `audio`	review `audio` (`audio-reviewer`, verdict machine)
3c Branche design	`design`	D
4 Jointure	— (intégration directeur)	—
5 Intégration	(l'étape propriétaire se rouvre sur corrections)	E
6 Tâches	`build` → in_progress	B
7 Construction	`build`, `audio` (intégration mix)	—
8 QA	`qa`	—
9 Rendu	`render` (automatique)	C (écoute humaine = enregistrement facultatif)

Rouvrir une étape (in_progress/blocked/failed) invalide les révisions de : research/brief/script → A (et les deux révisions de branches), content → review content + E et après, voice → review audio + E et après, design → D et après, build/audio/qa/render → C. Une nouvelle entrée de révision invalide également tout ce qui la suit (une révision de branche rouvre E, B, C). Réexécutez chaque point de contrôle invalidé dans l'ordre.

Différentes vidéos peuvent s'exécuter simultanément lorsqu'elles utilisent des ID, des dossiers audio, des préfixes QA et des sorties distincts. Les agents travaillant sur une vidéo possèdent des fichiers de scène disjoints ; seul video-director modifie kit, timeline, Reel, Root et le JSON de voix. Le pipeline sérialise les écritures vers un seul statut et un seul nom de sortie.

Liste des agents et transferts

video-director est le propriétaire du pipeline et le gestionnaire d'informations : il initialise le statut, conserve les décisions courantes de brief/script/source comme seule source de vérité, choisit le profil, assigne les fichiers, intègre le travail, exécute les commandes de point de contrôle et livre le résultat. Donnez à chaque spécialiste le brief accepté, les entrées exactes, le chemin de sortie attendu et la vérification d'acceptation. Lors du transfert, video-director vérifie l'artefact retourné par rapport à ces entrées, enregistre les décisions ou les questions non résolues dans docs/<vid>/, met à jour le statut et ne donne au spécialiste suivant que la version acceptée. Un réviseur doit avoir un contexte propre et ne doit pas être l'agent qui a produit l'artefact qu'il note. video-director ne note pas son propre travail.

video-director est le fil de conversation principal (vous), pas un sous-agent. Il gère chaque agent ci-dessous : dispatche, transmet les entrées acceptées, achemine les corrections, intègre les fichiers partagés, enregistre les statuts/points de contrôle et parle à l'utilisateur. Chaque phase est exécutée par son propre agent nommé ; les agents réviseurs sont séparés, en contexte propre et nouveaux à chaque tour.

Phase	Agent producteur	Agent réviseur (gate)	Possède et restitue
0 Réception	`intake-agent` (lecture seule)	—	Rapport de doublon de sujet, résultats de pré-vérification ; le directeur écrit l'en-tête du `brief.md` ; demande à l'utilisateur uniquement lorsqu'une entrée critique est manquante
1 Recherche	`research-agent` (× N par groupe de source)	—	`research.md` ou `research-<group>.md` : sources, langage du public, faits/ inférences/inconnus, cinq candidats d'accroche
2 Script	`script-agent`	`script-reviewer` (A)	`brief.md`, `script.md`, `voice.proposed.json` / `script-review.md`
3a Contenu	`content-agent`	`content-reviewer` (branche)	`content-pack.md` : texte à l'écran par plan, morceaux de sous-titrage, mots d'accent, texte de couverture/re-hook/CTA, tableau revendication→source, étiquettes `minh hoạ` / `content-pack-review.md`
3b Audio	`voice-agent` + `audio-agent`	`audio-reviewer` (branche, verdict machine)	`sN.mp3` + durées + ASR (`voice-report.md`) ; BGM/SFX + grille de beat + plan de mix + `assets-manifest.md` / `audio-review.md`
3c Design	`design-agent`	`design-reviewer` (D)	`design-spec.md` + prototype + 3 style frames + couverture + storyboard + bande de mouvement d'accroche / `design-review.md`
4 Jointure	`video-director`	—	`voice.json`, brouillon `timeline.ts`, `docs/<vid>/join-notes.md` (réconciliation timing/texte/mood)
5 Intégration	(les corrections vont au producteur de la branche propriétaire)	`integration-reviewer` (E)	`integration-review.md`, évalué avant la construction complète
6 Tâches	`task-planner`	`task-reviewer` (B)	`task-review.md` : outils, propriété plan→fichier, dépendances, vérifications
7 Construction	`scene-agent-1..N` (parallèle, un fichier chacun)	—	`src/<vid>/scenes*.tsx` + images fixes ; le directeur intègre `timeline`/`kit`/`Reel`/`Root`/audio
8 QA	`qa-agent`	—	`qa-report.md` : tsc, déterministe, vérifications de frame/transition/sous-titre, score de fidélité design par plan, corrections routées vers les propriétaires
9 Rendu	`render-agent`	`video-reviewer` (C, barrière finale)	MP4 vérifié + `final-check.md` (régression complète sur le MP4) + `render-evidence.md` (planche contact, frames denses, loudness, ASR) / `video-review.md`
10 Livraison	`video-director`	— (écoute humaine = enregistrement facultatif)	Le directeur exécute `check` et écrit le rapport de livraison

Seul video-director écrit les fichiers partagés kit, timeline, Reel, Root et voice.json ; les spécialistes proposent des modifications à ces fichiers dans leur transfert. Les agents de scène lisent les durées de la carte SHOTS de la vidéo et ancrent le mouvement sur la plage vocale mesurée. N'assignez jamais deux agents au même fichier inscriptible. Si l'utilisateur arrête le travail, arrêtez également les agents en arrière-plan. Le point de contrôle C est une révision IA des planches contact, frames denses, données ffprobe/loudness et ASR ; une écoute humaine après C (pipeline.py listen) est un enregistrement facultatif, pas un blocage de livraison.

Règle de vitesse : dispatcher en parallèle par défaut

video-director doit dispatcher autant de sous-agents en parallèle que le travail le permet, afin que la vidéo soit terminée aussi rapidement et aussi bien que possible. Exécuter des étapes les unes après les autres alors qu'elles pourraient être exécutées ensemble est un défaut.

Envoyez tous les appels d'agent indépendants dans UN SEUL message (un bloc d'outil), jamais un par tour.
Parallélisez dès que les entrées sont acceptées et que les fichiers inscriptibles ne se chevauchent pas : research-agent × N (un par groupe de source) ; les trois branches de la phase 3 (content-agent, voice-agent + audio-agent, design-agent) ensemble ; scene-agent × N (un fichier et une liste d'ID de plan chacun) ; qa-agent divisé par cluster de plan ; corrections de workflow/skill/doc parallèlement au travail vidéo ; corrections indépendantes routées vers différents propriétaires dans le même tour.
Les étapes indépendantes s'exécutent en parallèle (carte des étapes) :
- Phase 0 : vérifications intake-agent (sujet en double, pré-vérification des outils, test du catalogue vocal) en un message ; Phase 1 : tous les groupes de source research-agent.
- Phase 3 : les trois producteurs de branches dans UN SEUL message juste après la réussite de A. Chaque branche boucle ensuite producteur → son propre réviseur indépendamment : une branche qui réussit attend à la jointure pendant que les autres continuent de corriger ; une branche n'attend jamais la révision d'une autre branche.
- Phases 5–6 : task-planner ébauche le plan et les scene-agents construisent l'échafaudage précoce pendant que E examine ; la révision B attend la réussite de E (le plan change si E change quoi que ce soit).
- Phase 7 : scene-agent × N sur des fichiers disjoints ; Phase 8 : qa-agent par cluster de plan et rendus d'images fixes ; Phase 9 : planche contact, frames denses, preuves loudness et ASR calculées simultanément.
- Tours de correction : les tickets pour différents propriétaires partent en un seul message. Les révisions peuvent s'exécuter simultanément, mais le directeur enregistre les scores et exécute gate strictement dans l'ordre A → D → E → B → C (pipeline.py l'applique), et le résultat d'un réviseur ultérieur est nul si un point de contrôle antérieur se rouvre.
Restez séquentiel uniquement là où existe une dépendance réelle : points de contrôle A → D → E → B → C (un réviseur a besoin que son artefact soit terminé), un tour de correction qui dépend de la révision précédente, et tout fichier avec un seul propriétaire (kit, timeline, Reel, Root, voice.json).
Par défaut video-director envoie toutes les branches de la phase 3 et tous les research-agents dans un seul message (un bloc d'outil). Les exceptions sont documentées dans CLAUDE.md ou signalées par le moniteur.

Discipline de correction

Tout problème (échec de révision, problème de qualité, artefact de rendu) doit être enregistré et résolu avant notification. « Enregistré » signifie qu'il existe un ticket formel — un fichier docs/<vid>/fix-log.yaml avec des entrées Cao (bloquant, doit être réparé avant la notification), Trung (important, doit être réparé avant la notification dans cette phase) ou Thấp (cosmétique, peut être réparé plus tard). Seuls Cao et Trung bloquent la notification. Le réviseur ne passe pas le point de contrôle tant qu'un ticket Cao ou Trung est ouvert.

Le video-director ouvre un ticket à la première détection. Format : Cao: <description> ↔ owner: <agent-name>. Chaque ticket doit appartenir à un seul agent pour le rétablissement, même s'il y a une synchronisation.
Agent de correction : l'agent propriétaire reçoit le ticket et les fichiers sources ; il propose une correction dans docs/<vid>/fixes/<ticket-id>/. Il exécute les tests et met à jour le ticket.
Le directeur réexécute les révisions invalidées. Un ticket résolu est marqué trạng thái: resolved ; si la révision suivante échoue, le ticket se rouvre.
Le réviseur vérifie que les tickets Cao et Trung sont fermés avant de noter ≥ 9 ou ≥ 8. pipeline.py ne peut pas lire les tickets ; le réviseur définit --verdict revise manuellement.
Pas de changement de portée : un ticket de correction ne modifie pas le brief ni le script sans retour à A. Toute modification de contenu après avoir passé A nécessite une réouverture formelle de A ; le directeur pèse le coût.

Points d'échec courants

Leçon du gate-A : une ligne chronologique parfaite n'a d'importance que dans la timeline. Lorsque les sources ne sont pas d'accord, nous avons déjà choisi la version la plus convaincante pour l'histoire. Dans la révision A, le réviseur peut objecter à un détail qui semble faux ; le choix du script-agent est défendu dans script.md (explication). La correction remplace le fait litigieux par une information solide. Le résultat après correction peut être plus long mais plus vrai. Conserver mot à mot signifie copier exactement la déclaration de l'utilisateur uniquement lorsqu'elle a été marquée comme obligatoire ; sinon, traitez-la comme une source et réécrivez si la compréhension l'exige.

Échec des révisions de branches : Le producteur d'une branche ouvre un ticket et corrige ; le réviseur en contexte propre vérifie la correction et note à nouveau. Les trois branches sont indépendantes ; une branche en correction n'arrête pas les autres.

Le réviseur audio vérifie que chaque piste de voix est dans le codec/sample rate spécifié et que la durée mesurée correspond à la partition (pas d'écoute humaine).

Sur-interprétation d'une invite utilisateur courte. Lisez l'historique de la conversation, les fichiers du projet, la structure du dépôt et toute documentation avant d'agir. Dans le doute, traitez comme un brief de haut niveau et demandez une confirmation rapide.

Désynchronisation du moniteur : La règle d'agent (pipeline.py agent …) est obligatoire à chaque dispatch et notification. Sans elle, le moniteur ne peut pas afficher l'activité en cours.

Correction parallèle avec changement de portée. Deux tickets de correction ne doivent pas modifier la même assertion de script ou la même décision de design. Si c'est inévitable, le directeur fusionne les tickets en un seul tour ou ouvre un ticket parent dans fix-log.yaml.

Dépendances et installation

Python 3.10+ et pip install -r requirements.txt
Node.js 20+ et npm install
FFmpeg, ffprobe sur le PATH
Compte ElevenLabs (clé dans .env) pour la génération vocale
Compte Remotion (licence, tokens dans .env) pour le rendu
Le Pipeline Monitor nécessite python3 scripts/monitor.py sur le port 4180
python3 -m pytest scripts/ pour les tests d'intégrité

Utilisation

# 1. Vérifier le catalogue vocal
python3 -m unittest scripts.test_voice_catalog

# 2. Initialiser une nouvelle vidéo
python3 -I scripts/pipeline.py init <vid> --comp <CompId> --voice <voice> --profile story|product|knowledge|news

# 3. Lancer le moniteur (dans un terminal séparé)
python3 scripts/monitor.py

# 4. Le video-director dispatche les agents de manière itérative via des messages.
#    Utilisez les commandes du pipeline pour définir les statuts, les points de contrôle,
#    et les activités des agents tout au long du processus.

# 5. Livrer la vidéo finale
python3 scripts/check.py out/<vid>-<voice>-reel.mp4

Consultez scripts/pipeline.py --help pour la documentation complète des commandes.

nanxnguyen/remotion-ai-agentic-studio

Qu'est-ce que remotion-ai-agentic-studio ?

Demander à votre IA préférée

Documentation