reel — outil de création / montage vidéo pour agent
Outil multicouche basé sur ffmpeg : l'agent examine les rushes, définit les objectifs, rédige un plan ; le code gère le cadrage, le rendu et la validation. Le format est configurable (par défaut portrait 1080×1920).
Les détails des commandes et du format se trouvent dans le README du moteur et docs/engine.zh.md ; lisez-les avant de commencer.
Portes de livraison (obligatoires)
Une règle sans exécution n'est rien. Chaque étape ci-dessous est verrouillée par du code : impossible de produire un « rendu final » sans les suivre.
- Rédiger d'abord un brief (
$P/brief.json) et l'enregistrer :reel register brief.json. Précisez la langue de livraison, si c'est un rendu final ou un échantillon, le répertoire de livraison, et ce qui ne doit pas être modifié ; si vous ne pouvez pas, demandez à l'utilisateur. Une fois enregistré, l'écriture directe dans le répertoire de livraison via cp/mv/ffmpeg dans Bash, ou viareel … --out PATH/--out=PATH(idem pour--png,--sheet,--report,--check-png) sera refusée parhooks/guard_delivery.py. Ce garde parse uniquement le texte de la commande, au mieux : les wildcards, accolades, substitutions de commandes, scripts internes et écritures distantes peuvent passer ; ne le considérez pas comme une permission. La livraison se fait uniquement viareel deliver. - Écouter d'abord la voix : pas de voix par défaut. Fournissez d'abord un échantillon de 10–20 secondes à écouter. Après accord, écrivez la citation, le chemin de l'échantillon et son sha256 dans
brief.voice.approved; tout changement de voix nécessite une nouvelle écoute. - Vérifier après rendu :
reel check rendu_final.mp4 --plan plan.json --brief brief.json [--profile default|social-vertical|projet.json]. exit 1 = non livrable. Consultezresult.gate.blockers(problèmes techniques) etpending_review(points nécessitant validation humaine) ;not_coveredliste les éléments non vérifiés, ne dites pas « vérifié ». - Réviser : examinez un par un les points
needs_review(reel scrub/ extraction d'images), écrivez pour chaque point une note de révision avec code temporel ; visionnez l'intégralité en écrivantfinal_watch, et écoutez l'audio en écrivantfinal_listen. - Livrer :
reel deliver rendu_final.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json. Si les conditions du rendu final ne sont pas remplies, retourneDELIVERY_NOT_FINAL, seule l'option--sampleest possible, le nom de fichier portera la mention « échantillon_à_réviser ». Un même numéro de version ne peut pas être livré deux fois ; les anciennes versions ne sont ni supprimées ni écrasées. - Condition pour dire « terminé » : avoir reçu un accusé de réception avec
status: final(reel receipt <accusé>pour vérifier). Sinon, dites honnêtement « non terminé / échantillon à réviser / en attente d'écoute ».hooks/deliver_gate.py(Stop hook) bloque toute déclaration « terminé » sans accusé ; l'accusé doit correspondre à l'œuvre nommée (correspondance par nom d'œuvre et numéro de version). Par défaut, ce hook ne s'applique qu'aux projets enregistrés et aux tours ayant appelé reel ;REEL_GATE_SCOPE=globalpour une portée globale. - Les rendus issus de scripts de rendu personnalisés du projet suivent également les étapes 3 à 6.
- MV : ajoutez
--contract mv.json. La vérification des paroles lit les couches de texte des paroles déclarées dans le contrat (chaque phrase a du texte sur sa couche pendant le chant, pas de texte avant le début du chant) ; elle ne lit pas les pixels de l'image finale, donc vous ne pouvez pas dire « les paroles à l'écran ont été vérifiées » sur cette base.song_levelcompare la loudness et le vrai pic pour les compilations etpolicy: "trim"chanson par chanson, avec la même tolérance que pour un morceau unique. - Les erreurs de paramètres produisent également du JSON (
ARG_INVALID, code de sortie 2),--helpaffiche le texte d'aide.reel voice checkpour la vérification du chinois (par défaut--lang zh) nécessite en pluspypinyin(installé dans le même venv), sinon retourneBACKEND_UNAVAILABLE;reel wordsnécessite seulementwhisper-cliet le modèle.
Exemple de brief.json (pour MV, ajoutez "kind": "mv") :
{"version": "reel.brief.v1", "name": " promo_inscription", "language": "zh-CN", "deliverable": "final",
"delivery_root": "~/Deliveries/<projet>", "must_not_change": ["crédits de fin"],
"voice": {"mode": "tts", "voice_id": "zh-CN-XiaoxiaoNeural",
"approved": {"voice_id": "zh-CN-XiaoxiaoNeural", "by": "user", "quote": "Cette voix convient",
"sample": "voice_sample.mp3", "sample_sha256": "<résultat de shasum -a 256>"}},
"profile": "default"}
- Dans le brief, seuls
name,must_not_changeet les champs de clétext/title/caption/labelsont scannés pour le texte ;language,delivery_root,voice.*ne le sont pas. - Pas de voix : écrivez
"voice": {"mode": "none"}; enregistrement réel :"recorded". Version muette : utilisez un profil projet :{"extends": "default", "audio": "silent"}. - Profile :
default(seuils génériques),social-vertical(portrait pour réseaux sociaux : 1080×1920 30fps, -16 LUFS) ; les différences projet s'écrivent dans un profil projet (extends), les pauses intentionnelles sont enregistrées dansallowavec justification. La liste de mots scannée se trouve dans la sectiontextdu profil :bannedetextra_banned(sous-chaîne insensible à la casse, échoue si trouvé, les mots interdits propres au projet sont ajoutés dansextra_banned),banned_words(mots entiers en majuscules sensibles à la casseTODO/TBD/FIXME, échoue si trouvé),review(placeholder,lorem ipsum, mots entiers, déclencheneeds_review, nécessite une note de révisiontext_scan).
Début de chaque bloc d'appel Bash
Chaque appel Bash de l'agent est un nouveau shell, les fonctions ne persistent pas, donc reel est un script dans PATH (bin/reel), pas une fonction. Il choisit l'interpréteur dans l'ordre : REEL_PYTHON → ~/.local/share/reel/venv/bin/python → python3. En cas de problème d'environnement, exécutez d'abord reel doctor (liste les dépendances obligatoires et optionnelles et les solutions de réparation, sortie 1 si une dépendance obligatoire manque) :
command -v reel >/dev/null || export PATH="$HOME/.claude/plugins/reel/bin:$PATH"
P="$HOME/work/<projet>"; mkdir -p "$P/preview" && cd "$P" # les artefacts dans le répertoire du projet, pas dans /tmp
Flux de travail standard
- Préparer les rushes dans le répertoire du projet
$P(rushes, observations.json, plan.json, prévisualisations, rendus finaux ; un répertoire = un plan,.reel-history/pour les révisions). - Examiner les rushes, définir les objectifs :
reel inspect rushes/a.jpg rushes/b.mp4 reel frame rushes/a.jpg --out "$P/preview/a_grid.png" # lire l'image avec grille 0–1, lire le cadre cible reel observe --obs observations.json --src rushes --asset a.jpg --bbox x0,y0,x1,y1 --label "cible" reel locate --obs observations.json --src rushes --asset b.mp4 --t 2 --query "tasse rouge" --check-png "$P/preview/chk.png" # OWLv2, nécessite torch - Écrire plan.json (EditPlan v1) :
camera: []= vraiment statique ;zoom_toréférence une observation pour zoomer sur la cible ;tracksuit les observations sur plusieurs points temporels ;transition_out= transition. Les plans vidéo ne doivent pas franchir les points de coupe donnés parinspect. - Valider + prévisualiser :
reel validate plan.json;reel compile plan.json;reel preview plan.json s2 --out "$P/preview/s2.mp4" --sheet "$P/preview/s2.png", vérifier le storyboard pour confirmer le mouvement de caméra. - Rendre :
reel render plan.json --out "$P/rendu_final.mp4" --sheet "$P/preview/final.png" --where mac. L'audio final est fixé en AAC 48 kHz, leschecksincluent la fréquence d'échantillonnage. Le passage de tous lescheckssignifie seulement que le rendu n'a pas échoué ; suivez ensuite les portes de livraison 3–6.
Timeline et beats
- Voir :
reel timeline plan.json --format text;reel timeline plan.json --png tl.png [--beats beats.json];reel scrub plan.json --cuts --render rendu_final.mp4 --out répertoire. - Modifier :
reel edit plan.json --op '{"op":"trim","id":"s3","duration":2.4}'(écrit après validation à chaque étape) ;reel undo plan.json --to r2;reel history plan.json. - Beats :
reel beats musique.mp3 --out beats.json→reel snap plan.json --beats beats.json --mode downbeat(--dry-runpour un rapport préalable).
Page web : commenter, suivre et surligner
Quand les rushes sont une page web, pas d'OCR : la position du texte est lue directement depuis le DOM, la caméra et le surlignage sont dessinés image par image par le navigateur.
- Écrire le voice-over à partir du texte original de la page (les phrases à surligner doivent être identiques à la page), TTS génère
voice.mp3. reel words voice.mp3 --out words.json(whisper local pour les timings mot par mot).- Dans le plan, utiliser des plans de type
kind: "web",camera: [{"op": "follow"}],highlight: [{"text": "texte original de la page…", "sync": "voice"}],audio.wordspointe verswords.json. TEXT_NOT_FOUND= la page ne contient pas ce texte ;TEXT_NOT_IN_VOICE= le voice-over ne correspond pas.
GPU distant (optionnel)
- Définir
REEL_REMOTE=user@gpu-host(plusieurs séparés par des espaces possibles), puisreel render --where 5090/--where autoenvoie le rendu sur une machine NVIDIA distante (NVENC + libass), les artefacts sont rapatriés et vérifiés à nouveau localement. Si non défini, seul le local est utilisé. - VRAM par défaut ≤80 %, au-delà retourne
NEED_USER_APPROVAL, prévenir l'utilisateur, n'ajouter--allow-over-80qu'après accord ; utilisation GPU ≥50 % retourneGPU_BUSY, ne pas forcer. Le flock distant garantit qu'un seul reel GPU task s'exécute à la fois. reel remote probepour vérifier l'état ;reel remote setup-visionpour créer un venv distant indépendant (torch + OWLv2).