Communitygithub.com

notque/vexjoy-agent

Pipeline de montage vidéo : découpage, assemblage de clips via FFmpeg et Remotion.

Qu'est-ce que vexjoy-agent ?

Cette compétence implémente un pipeline de montage vidéo en 6 couches, où l'IA gère les tâches de jugement (quoi garder, quoi couper, sélection des moments forts) et FFmpeg/Remotion exécutent les opérations mécaniques de manière déterministe. Elle est conçue pour des agents comme Claude Code, Cursor ou Codex, et permet un flux de travail structuré allant de la capture des rushes à la livraison finale. Chaque phase possède des contraintes et des points de contrôle (gates) stricts, garantissant la reproductibilité et évitant les erreurs. La compétence s'appuie sur des références détaillées pour les commandes FFmpeg, les compositions Remotion, la génération d'assets et la gestion des erreurs, offrant ainsi une approche complète et robuste pour l'automatisation du montage vidéo.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/notque/vexjoy-agent/tree/HEAD/skills/content/video-editing

Demander à votre IA préférée

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

Documentation

Compétence de montage vidéo

Présentation

Cette compétence implémente un pipeline en 6 couches où l'IA gère les tâches de jugement (quoi garder, quoi couper, sélection des moments forts) et FFmpeg/Remotion exécutent les opérations mécaniques de manière déterministe.

CoucheNomMécanismeOutil principal
1CAPTUREInventaire des rushes sourceBash + Glob
2STRUCTURE IATranscription vers EDLJugement LLM
3DÉCOUPAGE FFMPEGEDL vers fichiers segmentsFFmpeg (déterministe)
4COMPOSITION REMOTIONSegments vers composition TSXRemotion + TypeScript
5GÉNÉRATION IACombler les lacunes avec des assets générésElevenLabs / fal.ai (conditionnel)
6POLISSAGE FINALCouche de goût humainHumain + NLE

Références approfondies

SignalFichierContenu
Commandes shell pour chaque phase, vérifications de passagereferences/phase-commands.mdBlocs de commandes complets pour les phases 1 à 6
Recettes FFmpeg : découpage, concat, proxy, détectionreferences/ffmpeg-commands.mdExtraction de timestamps, découpage par lots, normalisation audio, détection de scènes/silence
Structure de composition Remotionreferences/remotion-scaffold.mdModèle de composition TSX, commande de rendu, motifs de réutilisation
Pipeline image vers vidéoreferences/image-to-video.mdWorkflow de validation, préparation, encodage, vérification
Graphes de filtres FFmpeg pour visualisationreferences/ffmpeg-filters.mdScale/pad, showwaves, showspectrum, superposition, graphes de filtres complets

Instructions

Pré-vérification (à exécuter avant la Phase 1)

Exigences strictes (BLOQUANT si absent) : ffmpeg (toutes les phases), node (Remotion / npx). Exigences souples (AVERTISSEMENT si absent) : remotion (requis uniquement pour la Phase 4).

which ffmpeg >/dev/null 2>&1 || { echo "ERREUR : ffmpeg introuvable. Installez : brew install ffmpeg (macOS) | apt install ffmpeg (Linux)"; exit 1; }
which node >/dev/null 2>&1 || { echo "ERREUR : node introuvable. Installez : https://nodejs.org ou via nvm"; exit 1; }
npx remotion --version >/dev/null 2>&1 || echo "AVERTISSEMENT : CLI remotion introuvable. Phase 4 indisponible. Installez : npm install @remotion/cli"

Phase 1 : CAPTURE

Objectif : Inventorier tous les rushes source et confirmer que les fichiers existent sur le disque avant tout traitement.

Contrainte : Les fichiers source sont en lecture seule. Toutes les commandes FFmpeg écrivent uniquement dans de nouveaux fichiers. Ne jamais écraser les rushes source.

Étapes : localiser les fichiers source (find), inspecter chacun avec ffprobe, générer des proxys pour les fichiers > 10 min (voir references/ffmpeg-commands.md -> Génération de proxy), créer les répertoires de travail (segments/, assembled/). Bloc de commandes complet : references/phase-commands.md -> Phase 1.

Passage : Les fichiers source sont confirmés sur le disque. La liste des fichiers est écrite dans source-inventory.txt. Ne procéder que lorsque le passage est réussi.


Phase 2 : STRUCTURE IA

Objectif : Analyser le contenu et produire une EDL écrite (cuts.txt) qui pilote tout le découpage en aval.

Contrainte : cuts.txt est le contrat. Le fichier EDL est la seule source de vérité pour les phases suivantes. Ne pas modifier manuellement les commandes FFmpeg — les générer à partir de l'EDL.

Contrainte : Avant d'écrire l'EDL manuellement, exécuter la détection de scènes/silence FFmpeg. Le résultat de la détection informe le jugement, ne le remplace pas.

Étapes : transcrire avec whisper/AssemblyAI, exécuter la détection de scènes/silence, appliquer le jugement (ce qui fait avancer le récit, ce qui est superflu, durée cible), écrire cuts.txt au format EDL START_TIME,END_TIME,LABEL, vérifier les chevauchements et la durée totale. Bloc de commandes complet et exemple de format EDL : references/phase-commands.md -> Phase 2.

Passage : transcript.txt existe. cuts.txt écrit sur le disque. Ne procéder que lorsque les deux fichiers existent.


Phase 3 : DÉCOUPAGE FFMPEG

Objectif : Exécuter l'EDL de manière déterministe — une découpe FFmpeg par segment dans cuts.txt.

Contrainte : Découpage par lots à partir de l'EDL en utilisant une boucle. Ne pas créer de commandes FFmpeg individuelles par découpe. Cela garantit la reproductibilité et la capacité de révision sous forme de liste.

Contrainte : Toujours générer concat-list.txt à partir de l'ordre de cuts.txt, pas à partir d'un glob shell. Le glob shell (segments/*.mp4) trie alphabétiquement, pas dans l'ordre de l'EDL.

Étapes : découpage par lots depuis l'EDL avec une boucle while (libx264/aac, -avoid_negative_ts make_zero), vérifier les segments, générer concat-list.txt dans l'ordre de l'EDL, concaténer avec -f concat -safe 0 -c copy. Bloc de commandes complet : references/phase-commands.md -> Phase 3. Voir aussi references/ffmpeg-commands.md -> Découpage par lots.

Passage : Tous les fichiers segments existent. assembled/rough-cut.mp4 écrit sur le disque. Ne procéder que lorsque le passage est réussi.


Phase 4 : COMPOSITION REMOTION

Objectif : Envelopper les segments dans une composition Remotion TSX pour des superpositions, titres ou transitions programmatiques.

Quand l'utiliser : Uniquement lorsque rough-cut.mp4 nécessite des éléments programmatiques (titres animés, tiers inférieurs, pistes de sous-titres, superpositions de marque). Si rough-cut.mp4 est suffisant, passer directement à la Phase 6.

Contrainte : La couche 4 nécessite TypeScript/React. Confier le travail TSX à typescript-frontend-engineer ; revenir à python-general-engineer pour la Phase 5 et suivantes.

Étapes : initialiser Remotion (npm create video@latest la première fois ; sinon npm install @remotion/cli @remotion/player remotion), structurer la composition (voir references/remotion-scaffold.md), rendre avec npx remotion render. Bloc de commandes complet : references/phase-commands.md -> Phase 4.

Passage : assembled/remotion-output.mp4 existe. Ne procéder que lorsque le passage est réussi.


Phase 5 : GÉNÉRATION IA

Objectif : Combler les lacunes réelles dans les rushes avec des assets générés — uniquement lorsque nécessaire.

Contrainte : Vérifier si les rushes existants couvrent la lacune avant de générer quoi que ce soit. Ne générer que ce qui n'existe pas.

Arbre de décision : contourner la lacune → mettre à jour cuts.txt et relancer la Phase 3 ; voix off → ElevenLabs (autorisation requise) ; musique → fal.ai (déléguer à fal-ai-media) ; b-roll → fal.ai (déléguer à fal-ai-media). Aide Python ElevenLabs, modèle d'autorisation et flux de sauvegarde sur disque : references/phase-commands.md -> Phase 5.

Passage : Tous les assets générés requis sont sauvegardés dans le répertoire assets/ avant de continuer.


Phase 6 : POLISSAGE FINAL

Objectif : Livrer la sortie assemblée et confier le travail de finition gustative à un humain.

Contrainte : La couche 6 est le territoire humain. La compétence assemble ; l'humain termine. Les éléments suivants nécessitent un jugement humain et ne doivent pas être tentés de manière programmatique :

  • Étalonnage et harmonisation des couleurs entre les clips
  • Timing musical et ducking de volume
  • Style, police et positionnement des sous-titres
  • Timing et style des transitions
  • Niveaux finaux du mixage audio

Modèle de transmission (handoff-notes.txt avec liste des sources, EDL, chemin du rough-cut, liste de ce qui reste à faire pour l'humain) : references/phase-commands.md -> Phase 6.

Passage : assembled/rough-cut.mp4 (ou assembled/remotion-output.mp4) existe. handoff-notes.txt écrit sur le disque.


Extraction de transcription vidéo

Extraire la transcription d'une vidéo sous forme de paragraphes lisibles. Privilégier les sous-titres de l'uploader ; utiliser les sous-titres automatiques en dernier recours.

# Chemin 1 : sous-titres de l'uploader (précis)
yt-dlp --skip-download --write-subs --sub-langs en --sub-format vtt -o '<work-dir>/%(id)s' '<URL>'
# Chemin 2 : sous-titres automatiques (fallback si le chemin 1 n'écrit aucun fichier)
yt-dlp --skip-download --write-auto-subs --sub-langs en --sub-format vtt -o '<work-dir>/%(id)s' '<URL>'
# Nettoyage VTT en paragraphes
python3 skills/research/video-transcript/scripts/vtt_to_paragraph.py <work-dir>/<id>.en.vtt

Options : --timestamps pour les marqueurs [mm:ss], --keep-brackets pour les balises de repère, -o FICHIER pour la sortie fichier. Autres langues : modifier --sub-langs. Lister les disponibles : yt-dlp --list-subs '<URL>'.

Gestion des erreurs

ErreurCauseSolution
"No such file or directory" sur la sourceLe chemin dans cuts.txt ne correspond pas au nom du fichierExécuter cat source-inventory.txt. Mettre les chemins avec espaces entre guillemets.
FFmpeg "Invalid option" ou erreurs de codecCodec indisponible ou erreur de syntaxe de drapeau`ffmpeg -codecs
Remotion "Could not find composition"Identifiant de composition non correspondantVérifier src/index.ts pour l'ID enregistré. Correspondre exactement dans la commande de rendu.
Concaténation des segments dans le mauvais ordreLe glob shell trie alphabétiquement, pas selon l'EDLGénérer concat-list.txt à partir de l'ordre de cuts.txt, pas du glob.
ElevenLabs 401ELEVENLABS_API_KEY non définieexport ELEVENLABS_API_KEY=votre_clé avant la Phase 5.
Aucun fichier .vtt extraitLa vidéo n'a pas de sous-titres dans la langue demandéeyt-dlp --list-subs '<URL>' et choisir une langue disponible.

Skills associés