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.
| Couche | Nom | Mécanisme | Outil principal |
|---|---|---|---|
| 1 | CAPTURE | Inventaire des rushes source | Bash + Glob |
| 2 | STRUCTURE IA | Transcription vers EDL | Jugement LLM |
| 3 | DÉCOUPAGE FFMPEG | EDL vers fichiers segments | FFmpeg (déterministe) |
| 4 | COMPOSITION REMOTION | Segments vers composition TSX | Remotion + TypeScript |
| 5 | GÉNÉRATION IA | Combler les lacunes avec des assets générés | ElevenLabs / fal.ai (conditionnel) |
| 6 | POLISSAGE FINAL | Couche de goût humain | Humain + NLE |
Références approfondies
| Signal | Fichier | Contenu |
|---|---|---|
| Commandes shell pour chaque phase, vérifications de passage | references/phase-commands.md | Blocs de commandes complets pour les phases 1 à 6 |
| Recettes FFmpeg : découpage, concat, proxy, détection | references/ffmpeg-commands.md | Extraction de timestamps, découpage par lots, normalisation audio, détection de scènes/silence |
| Structure de composition Remotion | references/remotion-scaffold.md | Modèle de composition TSX, commande de rendu, motifs de réutilisation |
| Pipeline image vers vidéo | references/image-to-video.md | Workflow de validation, préparation, encodage, vérification |
| Graphes de filtres FFmpeg pour visualisation | references/ffmpeg-filters.md | Scale/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
| Erreur | Cause | Solution |
|---|---|---|
| "No such file or directory" sur la source | Le chemin dans cuts.txt ne correspond pas au nom du fichier | Exécuter cat source-inventory.txt. Mettre les chemins avec espaces entre guillemets. |
| FFmpeg "Invalid option" ou erreurs de codec | Codec indisponible ou erreur de syntaxe de drapeau | `ffmpeg -codecs |
| Remotion "Could not find composition" | Identifiant de composition non correspondant | Vérifier src/index.ts pour l'ID enregistré. Correspondre exactement dans la commande de rendu. |
| Concaténation des segments dans le mauvais ordre | Le glob shell trie alphabétiquement, pas selon l'EDL | Générer concat-list.txt à partir de l'ordre de cuts.txt, pas du glob. |
| ElevenLabs 401 | ELEVENLABS_API_KEY non définie | export ELEVENLABS_API_KEY=votre_clé avant la Phase 5. |
| Aucun fichier .vtt extrait | La vidéo n'a pas de sous-titres dans la langue demandée | yt-dlp --list-subs '<URL>' et choisir une langue disponible. |