Communitygithub.com

reel

Outil de création et montage vidéo par agent : promotion, voice-over, clip MV/lyriques, photos + musique + voix, rushes, zoom avant, pages web avec surlignage commenté. La livraison passe obligatoirement par reel check → reel deliver pour obtenir un accusé de réception final.

Qu'est-ce que reel ?

reel est un outil de production vidéo piloté par agent, conçu pour les environnements comme Claude Code, Cursor ou Codex. Il s'appuie sur ffmpeg pour le rendu et intègre un système de validation strict : rédaction d'un brief, approbation vocale, vérification technique (reel check), révision humaine et livraison finale avec accusé de réception. Il gère les formats portrait (1080×1920), les transitions, les beats musicaux, les pages web avec surlignage synchronisé, et supporte le rendu GPU distant. La particularité de reel est son mécanisme de « portes de livraison » : chaque étape est verrouillée par du code, empêchant toute sortie non conforme. Le plan de tournage (plan.json) décrit les opérations caméra, les zooms, les pistes audio, les paroles et les surlignages. Les commandes CLI (reel inspect, frame, observe, compile, render, check, deliver) forment un pipeline complet de la conception à la remise du fichier final avec un reçu infalsifiable.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shuaige121/agent-reel/tree/HEAD/skill

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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.

  1. 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 via reel … --out PATH / --out=PATH (idem pour --png, --sheet, --report, --check-png) sera refusée par hooks/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 via reel deliver.
  2. É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.
  3. 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. Consultez result.gate.blockers (problèmes techniques) et pending_review (points nécessitant validation humaine) ; not_covered liste les éléments non vérifiés, ne dites pas « vérifié ».
  4. 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 écrivant final_watch, et écoutez l'audio en écrivant final_listen.
  5. 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, retourne DELIVERY_NOT_FINAL, seule l'option --sample est 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.
  6. 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=global pour une portée globale.
  7. Les rendus issus de scripts de rendu personnalisés du projet suivent également les étapes 3 à 6.
  8. 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_level compare la loudness et le vrai pic pour les compilations et policy: "trim" chanson par chanson, avec la même tolérance que pour un morceau unique.
  9. Les erreurs de paramètres produisent également du JSON (ARG_INVALID, code de sortie 2), --help affiche le texte d'aide. reel voice check pour la vérification du chinois (par défaut --lang zh) nécessite en plus pypinyin (installé dans le même venv), sinon retourne BACKEND_UNAVAILABLE ; reel words nécessite seulement whisper-cli et 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_change et les champs de clé text / title / caption / label sont 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 dans allow avec justification. La liste de mots scannée se trouve dans la section text du profil : banned et extra_banned (sous-chaîne insensible à la casse, échoue si trouvé, les mots interdits propres au projet sont ajoutés dans extra_banned), banned_words (mots entiers en majuscules sensibles à la casse TODO / TBD / FIXME, échoue si trouvé), review (placeholder, lorem ipsum, mots entiers, déclenche needs_review, nécessite une note de révision text_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

  1. 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).
  2. 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
    
  3. Écrire plan.json (EditPlan v1) : camera: [] = vraiment statique ; zoom_to référence une observation pour zoomer sur la cible ; track suit les observations sur plusieurs points temporels ; transition_out = transition. Les plans vidéo ne doivent pas franchir les points de coupe donnés par inspect.
  4. 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.
  5. 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, les checks incluent la fréquence d'échantillonnage. Le passage de tous les checks signifie 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-run pour 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.

  1. É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.
  2. reel words voice.mp3 --out words.json (whisper local pour les timings mot par mot).
  3. Dans le plan, utiliser des plans de type kind: "web", camera: [{"op": "follow"}], highlight: [{"text": "texte original de la page…", "sync": "voice"}], audio.words pointe vers words.json.
  4. 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), puis reel render --where 5090 / --where auto envoie 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-80 qu'après accord ; utilisation GPU ≥50 % retourne GPU_BUSY, ne pas forcer. Le flock distant garantit qu'un seul reel GPU task s'exécute à la fois.
  • reel remote probe pour vérifier l'état ; reel remote setup-vision pour créer un venv distant indépendant (torch + OWLv2).

Skills associés