custom-animated-video : orchestrateur
SKILL_DIR = le dossier contenant ce fichier. Vous êtes l'orchestrateur : vous gardez l'intention de l'utilisateur, déléguez chaque étape à un sous-agent spécialisé et exécutez vous-même la porte de révision. N'incrustez jamais un style dans le cœur ; chaque valeur de style provient du style_bible.json de l'utilisateur.
| drapeau | signification |
|---|---|
--script | script.txt / script.md (les mots réellement prononcés) |
--audio | voiceover.wav / .mp3 |
--style | style_bible.json (n'importe quelle forme ; normalisé automatiquement) |
--bgm | fichier musical optionnel (sinon bibliothèque d'actifs, sinon drone modal procédural) |
--aspect | 16:9 (1920×1080, défaut) ou 9:16 (1080×1920) |
--subtitles | true / false |
--out | fichier .mp4 de sortie (son dossier est WORK sauf --workdir) |
Pipeline (tous pilotés par scripts/build_video.py) : normalize_style → analyze_audio → storyboard.json → scene_drawers.js → sfx_synth → mix_audio → render_frames (par plan → clip, images supprimées) → concat + mux → QA images → auto-clean → porte de révision.
Agents et routage
| étape | sous-agent | modèle · effort | travail |
|---|---|---|---|
| 1 ingestion | cav-ingest | haiku · bas | vérification d'exécution, --stage analyze, écrit WORK/director_brief.json |
| 2 direction | cav-director | sonnet · moyen | storyboard.json (7 règles de directeur) ; mises à jour de plans uniquement |
| 3 dessin | cav-artist (cav-artist-fast en mode rapide/budget) | opus · élevé (sonnet · élevé) | scene_drawers.js (6 règles d'art) + vérification par aperçu ; correctifs ciblés |
| 4 construction | cav-builder | haiku · bas | complet / --only / --apply-review / --ship, télémétrie audio |
| 5 QA | cav-qa-critic | sonnet · moyen | inspecte WORK/qa/, retourne `STATUS: PASS |
Utilisez le mode rapide uniquement si l'utilisateur l'a demandé (rapide/budget/pas cher/brouillon). Ne rétrogradez jamais silencieusement l'artiste.
Règles d'orchestration
- Sous-agents à usage unique, sans état. Les caches de prompt expirent après ~5 min et la porte de révision utilisateur peut prendre beaucoup plus de temps, donc ne gardez jamais un sous-agent actif entre deux portes et n'utilisez jamais
SendMessagevers un sous-agent terminé. Créez un nouveau sous-agent par tâche avec des chemins absolus explicites et un brief structuré concis (ci-dessous). Exécutez le travail indépendant en un seul message. - Format du brief (chaque délégation) :
SKILL_DIR,WORK, les valeurs exactes--script/--audio/--style/--aspect/--subtitles/--bgm/--out, la tâche, les fichiers d'entrée à lire, les fichiers à écrire et la forme de la réponse dont vous avez besoin. - Gardez votre propre contexte léger : lisez les résumés des sous-agents, pas les fichiers bruts. Ne lisez jamais
Readsuraudio_timeline.json(énormes tableaux par image). UtilisezWORK/director_brief.json. - Si un type de sous-agent
cav-*n'est pas encore disponible dans cette session (les agents enregistrés en cours de session peuvent ne pas être listés avant un redémarrage), conservez le routage du modèle : appelezAgent(subagent_type="general-purpose", model=<m>)avecmodel=haikupourcav-ingest/cav-builder,sonnetpourcav-director/cav-artist-fast/cav-qa-critic,opuspourcav-artist, et dites-lui de d'abord lire$SKILL_DIR/agents/<agent-name>.mdet de le suivre comme ses instructions, puis de donner le brief habituel. - Assurez-vous que l'utilisateur a fourni le script, la voix off et le style bible ; demandez (AskUserQuestion) uniquement ce qui manque.
Phase 0 · Enregistrement des sous-agents et exécution
AGENTS_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents" && mkdir -p "$AGENTS_DIR" && for f in "$SKILL_DIR"/agents/cav-*.md; do cmp -s "$f" "$AGENTS_DIR/$(basename "$f")" || cp "$f" "$AGENTS_DIR/"; done
(Portable sur macOS et Linux. build_video.py les maintient également synchronisés à chaque exécution ; la ligne ci-dessus le garantit dès le premier tour.) L'exécution privée ($SKILL_DIR/.runtime/ : venv, modèle Whisper, navigateur, ffmpeg si nécessaire) est amorcée par cav-ingest via build_video.py --check (1–3 min une fois, connexion internet nécessaire ; ne touche jamais aux autres environnements). Déterminez WORK (dirname(--out)) et mkdir -p.
Phase 1 · Ingestion → cav-ingest
Déléguez. Attendez-vous à STATUS: ok|needs_user et WORK/director_brief.json.
alignment_coverage < 0.6→ le script ne correspond pas à la prise : arrêtez et demandez à l'utilisateur (corriger le script / confirmer / fournir une nouvelle prise). Les différences d'orthographe uniquement sont acceptables.- Une entrée de mood/palette obligatoire manquante → demandez si vous devez l'ajouter à la bible ou accepter les valeurs par défaut.
- Sinon continuez ; signalez les avertissements dans votre prochain message destiné à l'utilisateur.
Phase 2 · Direction → cav-director
Entrées : WORK/director_brief.json, WORK/storyboard.draft.json, references/storyboard_schema.json. Sortie WORK/storyboard.json. Vérifiez la cohérence de la réponse (tuilage, coupures aux points de pause, plans de 1,5 à 6 s, variété de caméra, sfx présents). Pas satisfait → un nouvel appel cav-director avec des corrections spécifiques.
Phase 3 · Dessin → cav-artist (ou cav-artist-fast)
Entrées : WORK/storyboard.json, WORK/style.normalized.json, la bible de l'utilisateur, plus les arguments CLI d'origine pour les rendus d'aperçu. Sortie WORK/scene_drawers.js, vérifiée avec un aperçu --frames (zéro erreur [scene / layer / frame]). Le travail de l'artiste est uniquement artistique ; les modifications du storyboard nécessaires lui sont remontées pour cav-director.
Phase 4 · Construction → cav-builder
Construction complète vers --out (il passe --no-review ; la porte vous appartient). Attendez-vous à BUILD: ok, ducking à ±1 dB de la cible, ≈ −14 LUFS, et les images WORK/qa/. En cas d'failed, routez l'erreur nommée [scene / layer / frame] vers cav-artist (ou une erreur de synchronisation vers cav-director), puis reconstruisez avec --only.
Phase 5 · QA → cav-qa-critic
Exécutez toujours avant que l'utilisateur ne voit quoi que ce soit. En cas de STATUS: FAIL :
- Tickets avec
target_file: scene_drawers.js→ nouveaucav-artist(mode correction, liste de tickets dans le brief). Tickets avecstoryboard.json→ nouveaucav-director(mise à jour ciblée), puiscav-artistsi les clés de scène ont changé. cav-builderavec--only <ids de plans affectés>.- Nouveau
cav-qa-criticsur les nouvelles images. Maximum 2 boucles de correction automatique ; puis dites à l'utilisateur ce qui échoue encore et laissez-le décider (continuer vers la porte de révision ou diriger une correction).
Phase 6 · PORTE DE RÉVISION (vous, dans la session principale ; ne sautez jamais, ne décidez jamais pour l'utilisateur)
python3 "$SKILL_DIR/scripts/review.py" --questions --storyboard WORK/storyboard.json --video project/final_video.mp4
Demandez avec AskUserQuestion, au maximum trois appels rapides (donnez le chemin de la vidéo et ce que la QA a confirmé) :
- tour1 · « On envoie ou on modifie ? »
- Si Modifier, tour2 en UN appel : Quelles parties ? (Visuels / Caméra & montage / Sous-titres / Son, multiple) et Quels moments ? (Vidéo entière ou plans spécifiques, multiple).
- UN appel avec la question tour3 pour chaque partie sélectionnée (multiple ; « Autre » = texte libre) : Visuels → Personnage · Arrière-plan · Couleurs & éclairage · Mouvement ; Caméra → Plus serré · Plus large · Plus calme · Timing des coupes/transitions ; Sous-titres → Désactiver · Plus grands · Plus petits · Déplacer en haut ; Son → Musique moins/plus forte · Effets moins/plus forts.
Écrivez les réponses dans WORK/review.json :
{"decision": "change", "parts": ["visuals", "sound"], "shots": ["s2 3.5-5.6s"],
"visuals": ["Character", "Motion"], "sound": ["Music quieter"],
"notes": {"visuals": "le visage semble trop long", "sound": "utiliser ~/music/sitar.mp3"}}
Ensuite :
- Modifications paramétriques (cadrage plus serré/plus large/plus calme, sous-titres désactivés/taille/position, musique/effets ±3 dB) →
cav-builderavec--apply-review WORK/review.json. Il reconstruit uniquement les cibles affectées (son → audio + remux ; caméra → ces plans ; sous-titres → tous les plans). - Tickets artistiques/de coupe (visuels, timing des coupes, notes en texte libre) →
--apply-reviewécrit égalementWORK/review_plan.jsonet imprime la commande--onlyexacte. Déléguez uniquement les plans affectés à un nouveaucav-director(timing des coupes/rythme caméra) et/oucav-artist(visuels), en donnantreview_plan.jsonet les notes →cav-builder --only <plans>→cav-qa-criticsur les plans modifiés → retour au tour 1. Bouclez jusqu'à « On envoie ».storyboard.prev.jsoncontient le storyboard avant modification si l'utilisateur veut annuler.
Phase 7 · Expédition → cav-builder
Sur « On envoie », déléguez --ship (--keep-deps si l'utilisateur va faire une autre vidéo bientôt ; --purge-recipe seulement si demandé). Il conserve
uniquement la vidéo finale (plus les entrées de l'utilisateur et la recette de quelques Ko storyboard.json / scene_drawers.js) et supprime chaque
fichier généré et $SKILL_DIR/.runtime/. Dites à l'utilisateur : le chemin de la vidéo, sa ligne de spécification (résolution/fps/durée) et l'espace disque
libéré. Les outils système (python3, ffmpeg, Chrome) ne sont jamais touchés.
Garanties que les sous-agents doivent préserver (détails complets dans leurs fichiers)
Directeur : les plans se tuilent ; coupes aux points de pause ; 1,5–6 s ; préréglages variés ; beat sur chaque pause ; un mood/plan ; transitions sur
les pauses ; speaker sur les plans de synchronisation labiale ; sfx_events précis à l'image (pas selon walk_cycle.frames_per_step, alternance ±1,5 dB
; swell culmine à t_sec + duration_sec sur la coupe ; ambience −24…−28 dB ; bgm.gain_db −18…−21).
Art : couleur uniquement par palette, pas de hex, pas de #000, ombres shadowOf, une lumière clé F.mood.key_dir_deg, cinq couches de parallaxe +
_lights, marges ≥ 400 px, architecture ancrée, celShade + drawTaperedStroke(…, 1.6) + un applyRimLight basé sur un tableau,
pieds IK posés, chaînes de tissu, bouches de synchronisation labiale, CAV.withBoil sur les deux (tc) pour les personnages/FX uniquement, RNG déterministe.
Audio : d'abord les assets sfx puis procéduraux ; sidechaincompress ducking ±1 dB de audio_palette.duck_db (15), +3 dB swell de pause,
loudnorm en deux passes −14 LUFS / −1.5 dBTP ; les pistes sont supprimées après le mix.
Construction : clips par plan (x264 crf 16) avec images supprimées immédiatement ; les hachages de build_state.json rendent les ré-exécutions incrémentielles ;
--only s2,s3,audio restreint une ré-exécution ; les plans dont les coupes ont bougé, et un suiveur de fondu enchaîné de tout plan re-rendu, sont toujours re-rendus.
Drapeaux : --preview --workers N --force --frames a,b,c --apply-review --ship --keep-deps --purge-recipe --stage analyze --check --auto.
API artistique : references/art_reference.md · schémas : references/storyboard_schema.json, references/style_schema.json.
Dépannage
alignment_coveragefaible → le script et la prise diffèrent ; corrigezscript.txt.scene_drawers.js does not define scene(s)→ les clésscenedu storyboard doivent correspondre aux clésregisterScenes.- Ducking loin de la cible → respiration/musique qui dépasse ; passez
--duck-dbou augmentezbgm.gain_db. - Images noires/blanches → une couche a levé une erreur ; lisez l'erreur
[scene / layer / frame]. Rendu lent →--workers N,--preview. - Exécution cassée/obsolète → supprimez
$SKILL_DIR/.runtime/et exécutez--check. Hors ligne → définissezCAV_RUNTIME; l'aligneur revient à une segmentation basée uniquement sur l'énergie sans modèle Whisper. - Nouveaux sous-agents non listés dans la session en cours → ils sont enregistrés sur le disque ; démarrez une nouvelle session Claude Code ou utilisez le
recours
general-purposeci-dessus (avec lemodelcorrespondant).