mk-montage-vidéo

Que fait mk-montage-vidéo ?

Transformez les rushes fournis en un montage regardable et cohérent : les bons mots dans le bon ordre, une caméra qui cadre bien le sujet, une image homogène, un son propre et nivelé, et des titres élégants. La structure provient des images et de ce qui y est dit.

Ce que le skill peut faire

Besoin	Outils	Coût	Référence
Transcription mot à mot, détection des tics de langage/faux départs/pauses	edit:transcribe (mlx-whisper), speech:flow	gratuit, local	footage-editing.md
Stabiliser, suivre l'orateur, recadrer les plans larges 4K (poussées, rapprochés, panoramiques), HDR→SDR, dé-flicker, harmonisation des couleurs, fondus, jump cuts	edit:analyze, edit:track, EDL + medit (edit:render)	gratuit, local	footage-editing.md
Nettoyage dialogue, mixage, ducking, loudness	speech:clean (ISOLATE=1 Demucs), speech:mix, speech:measure	gratuit, local	footage-editing.md
Narration	voice:tts (ElevenLabs via Fal)	payant, approuvé	credentials.md
Titres, tiers inférieurs, cartes de fin (ProRes 4444 alpha)	mgraphics scènes JSON, graphics:render, modèles dans scripts/tools/graphics/examples/	gratuit, local	graphics README
Musique de fond sous le montage	EDL music (ducké), music:score (ElevenLabs Music via Fal), audio:analyze pour le calage rythmique	payant seulement si générée	finishing.md
Effets sonores sur titres/transitions	SoundSynth (synth: whoosh, rising, impact, tick…), sfx:gen/sfx:mix ou EDL sounds	gratuit (Stable Audio prompt: payant)	finishing.md
Effets d'image (flash, dip, punch, glow, lens, streaks…)	mvfx feuilles de repères, vfx:stills/vfx:render	gratuit, local	finishing.md
Encodages de livraison	media:twitter, media:youtube, media:faststart	gratuit, local	tasks.md
Sous-agents parallèles sur tâches indépendantes	work:next/work:accept/work:log/work:watch	gratuit	tasks.md

Chaque tâche avec ses arguments et options se trouve dans tasks.md. Les profils de test sont dans testing.md.

Contrat d'exécution

Conçu pour Claude Code sur macOS 14+ sur Apple Silicon (Swift 5.9+, Ruby 3.2+, Bundler, FFmpeg, ImageMagick, uv pour Whisper local). Exécutez doctor d'abord quand une tâche échoue sur un outil manquant ; setup compile les outils Swift. Ruby est la seule couche d'exécution d'entrée : exécutez ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/project 'tâche[args]'. Les tâches délèguent aux services Ruby (lib/media/edit.rb, speech.rb, guard.rb, …) qui pilotent les outils Swift natifs medit (scripts/tools/edit), mgraphics (scripts/tools/graphics) et mvfx (scripts/tools/vfx). Ajoutez une méthode Ruby et une tâche légère quand une capacité manque. Un projet exécute sa propre copie de lib/ et tools/ : après avoir modifié le skill, rsync les fichiers modifiés dans le projet.

Sécurité mémoire (obligatoire)

Le décodage matériel 4K/HDR conserve les trames dans VTDecoderXPCService, en dehors de l'empreinte du job. Sur une machine 16 Go sans swap, épuiser la mémoire fige l'ordinateur au lieu de le ralentir. Par conséquent :

• Exécutez un job lourd à la fois (medit analyze/render/stills, mgraphics encodes, Demucs, gros encodages ffmpeg). Ne lancez jamais plusieurs en parallèle ou en arrière-plan les uns avec les autres ; enchaînez-les séquentiellement dans une seule commande d'arrière-plan si nécessaire. JOBS reste à 1 sauf si RAM ≥ 32 Go.
• Chaque appel de rendu medit/mgraphics/mvfx passe par Media::Guard (automatique dans les services Ruby) : il échantillonne l'empreinte du job + décodeur et le pourcentage de mémoire libre du noyau toutes les 0.3 s et envoie SIGKILL avant MEDIT_MAX_FOOTPRINT_MB (3500 par défaut) ou en dessous de MEDIT_MIN_FREE_PCT (30 par défaut). Il refuse de démarrer quand la mémoire libre est déjà basse. Les trois moteurs de rendu utilisent par défaut JOBS=1 ; les fragments parallèles nécessitent un réglage explicite de JOBS.
• Validez tout nouveau chemin de décodage/rendu sur une courte plage avec des limites serrées d'abord (TO=15 MEDIT_MAX_FOOTPRINT_MB=1500 MEDIT_GUARD_LOG=/chemin/log), vérifiez que le log est plat, puis exécutez la longueur totale.
• Dans les boucles média Swift, enveloppez chaque copyNextSampleBuffer et rendu Core Image dans autoreleasepool (le code asynchrone ne draine jamais le pool par défaut : les trames fuient à ~1.5 Go/s).

Équilibre mesuré : analyse ≈ 1.0 Go (job + décodeur) par source 4K HLG ; un rendu avec un fondu ouvre deux sources.

1. Prise en charge

Demandez seulement ce qui manque : chemins des rushes, ce qu'est le montage (extrait de talk, résumé…), texte des titres/crédits, durée cible, souhaits de narration. Initialisez avec les médias (liens symboliques, jamais copiés ni modifiés) :

ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" init --project /abs/project --media /abs/clip1.MOV --media /abs/clip2.MOV --prompt-file /abs/brief.md
ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/project setup

Sondez chaque source (ffprobe : taille, fps, durée, transfert HDR). Extrayez l'audio (audio/raw/*.wav, 48 kHz) et transcrivez localement : edit:transcribe[analysis/transcripts,source/...] (mlx-whisper large-v3-turbo, temps des mots ; gratuit). Lisez chaque transcription et écrivez ce que chaque clip dit, avec les horodatages, dans docs/BRIEF.md. Recherchez sur le Web les faits événementiels utilisés dans les titres et enregistrez les sources.

2. Analyser (séquentiellement)

REGION=0,0,1,0.62 DETECT_REGION=0.15,0.3,0.85,0.8 mv 'edit:analyze[source/A.MOV,analysis/A.json]'   # un à la fois
mv 'edit:track[analysis/A.json,analysis/A.track.json]'      # SEED=x,y quand l'orateur n'est pas trouvé tôt ; SPACE=frame pour stabiliser : 0
mv 'edit:stats[analysis/A.json,from,to]'

• REGION limite la stabilisation (corrélation de phase) aux décors statiques (scène, écrans), excluant le public.
• DETECT_REGION recadre la scène pour la détection de personnes Vision à ~2× la résolution — essentiel pour un orateur éloigné (la détection est passée de 2 % à 40–90 % des échantillons).
• Les pistes sont verrouillées au monde (stabilisation supprimée), choisies par continuité, et suppriment les grandes boîtes de premier plan (têtes) via max_aspect.
• Les rushes de téléphone (iPhone etc.) sont déjà stabilisés en caméra : effectuez le rendu avec stabilize : 0 et SPACE=frame pour les pistes. Notre stabilisateur peut confondre le contenu de diapositive en mouvement avec un mouvement de caméra et ajouter des sauts horizontaux soudains. Vérifiez : comptez les trames avec |Δshift| > 8 px dans l'analyse ; la gigue résiduelle sur iPhone 4K mesurée ≈ 0.9 px RMS, ne vaut pas la correction.

Flux de parole (tics de langage, faux départs, répétitions, pauses anormales)

VERBATIM=1 mv 'edit:transcribe[analysis/transcripts_verbatim,source/A.MOV]'   # amorce Whisper pour écrire euh/hum
mv 'speech:flow[analysis/transcripts_verbatim/A.json,audio/clean/A.wav,analysis/flow/A.json]'   # lisez analysis/flow/A.txt

Le détecteur mesure les pauses acoustiquement (énergie + voisement, pas les temps des mots de Whisper), les classe (phrase/virgule/expression) et signale les tics de langage, les hum non transcrits, les répétitions et les faux départs possibles, chacun avec une cut proposée. Décidez par le sens, puis appliquez les coupures avec Media::Cuts dans le générateur (étape 4). Cherchez les auto-corrections et les phrases abandonnées (« afin d'être— », une dernière phrase inachevée avant des applaudissements) en lisant le .txt ; le détecteur ne propose que des candidats.

• Les statistiques de couleur de trame entière sont dominées par les écrans de projection ; faites correspondre l'exposition sur la zone de l'orateur (tuiles autour de la piste) et jugez la balance des blancs sur des images fixes.

3. Planifier et approuver

Écrivez docs/PLAN.md : table des sélections (source, entrée/sortie aux limites de phrase, contenu, jointure : fondu/jump cut), titres, texte de narration, langage caméra, traitement image et audio. Résumez dans le chat ; enregistrez l'approbation avec NOTE='...' plan:approve (également requis avant les appels payants, par ex. narration ElevenLabs via voice:tts ; voir credentials.md — dans les sessions de plugin, les tâches payantes s'exécutent via le serveur MCP mk-video-editing).

4. Construire l'EDL avec un script générateur

Écrivez edit/build_edl.rb (voir footage-editing.md pour le schéma complet de l'EDL et un exemple concret). Définissez un vocabulaire de plans (LARGE zoom≈1.2–1.4, MOYEN-LARGE fit≈0.4, MOYEN fit≈0.56, RAPPROCHÉ fit≈0.72 plafonné par max_zoom 3.6) et écrivez les beats de caméra en secondes source tirés de la transcription : poussées lentes sur 6–12 s, rapprochés coupés sur les lignes d'emphase, passage au large sur les changements de sujet/diapositive, recadrage sur chaque jump cut. Par plan : zone safe (garder le premier plan distrayant à l'écart), deflicker, correspondance grade ; un look partagé. Les incrustations sont des titres ProRes 4444 alpha (voir Titres ci-dessous).

Supprimez les mots et les pauses à l'intérieur d'une sélection avec lib/media/cuts.rb : Media::Cuts.pause_cuts (raccourcir automatiquement les pauses anormales), Media::Cuts.segments (diviser la sélection en segments de jump cut, aligner les limites au point le plus silencieux entre les mots, ouvrir chaque segment sur un cadrage contrasté, maintenir chaque zoom ≥ 4.5 s), Media::Cuts.text (journaliser ce que chaque coupe supprime dans edit/cuts.txt). Commencez et terminez chaque sélection dans le silence et loin de la manipulation de la caméra (vérifiez la vélocité de décalage près des bords). Exemple concret dans footage-editing.md.

5. Audio

speech:clean[audio/raw/A.wav,audio/clean/A.wav] (PRESET=room : coupure du grondement, FFT denoise, coupure du boueux, présence, dé-essing, expandeur doux, niveleur ; ISOLATE=1 pour Demucs vocal local). Ajoutez la narration avec voice:tts quand demandée (MODEL=v4 pour Eleven v4). Ajoutez une musique de fond seulement quand le brief le demande : un morceau fourni ou music:score, placé comme music dans l'EDL (finishing.md). Exécutez ensuite speech:mix[edit/edl.json,audio/mix.wav]. Il mixe l'audio du clip avec des fondu-enchaînés sur les dissolves (audio_xfade : 0.15 garde le dernier mot avant un dissolve de 0.6 s), audio_duck sous la narration, les sounds et la music avec ducking sidechain, puis applique un loudnorm deux passes à −16 LUFS / −1.5 dBTP.

6. Révision, rendu, livraison

• DEBUG=1 edit:stills[edit/edl.json,edit/review/vN,t1,t2,...] — chaque image fixe plus la trame source complète avec le recadrage (rouge), le sujet (vert) et la zone sûre (jaune). Vérifiez le cadrage, l'espace au-dessus de la tête, les intrusions de premier plan, la continuité exposition/WB à travers les coupes.
• edit:sheet planches contact ; edit:preview[edl,out.mp4,from,to] prévisualisations demi-résolution des plages modifiées.
• edit:render[edit/edl.json,output/final.mp4] (JOBS=1). Ne jamais écraser un master livré.
• QA avant le rendu vidéo : speech:mix, puis edit:transcribe le mix et lisez les mots autour de chaque at du clip (peu coûteux ; attrape les mots coupés et les flashs de mots isolés). Après le rendu, retranscrivez le final ; journalisez les versions et les problèmes dans docs/REVIEW.md.

Livrez la vidéo, les docs plan/brief/review et un court résumé des choix et problèmes connus. Exécutez les profils RSpec de testing.md après avoir modifié la toolkit et swift test dans tools/graphics après les changements du moteur de rendu.

Titres

Partez des modèles dans scripts/tools/graphics/examples/ : opening_title.json, lower_third.json et end_card.json (1920×1080, AvenirNext, une couleur d'accent). Copiez-les dans edit/titles/, changez le texte et le timing, ou générez-les à partir de edit/make_titles.rb quand il y en a plusieurs. Vérifiez les noms, rôles et faits événementiels sur le Web.

1. Effectuez le rendu d'images fixes avec ONLY= sur une trame du plan (PLATE=) et vérifiez la lisibilité, la marge de sécurité et les accents.
2. Effectuez le rendu CODEC=prores4444 SUPERSAMPLE=2 graphics:render[edit/titles/x.json,edit/titles/x.mov,frames,1920,1080,fps] au fps du montage.
3. Placez-le comme entrée EDL overlays, en assombrissant ou en floutant le fond sous une carte d'ouverture avec la caméra dim/blur.

Le format de scène (nœuds, pistes, easing, glow, polices) se trouve dans le graphics README. Après des changements du moteur de rendu, exécutez swift test dans scripts/tools/graphics et comparez les rendus de titres anciens et nouveaux octet par octet.

Finishing (optionnel)

Une musique de fond, des effets sonores et des effets d'image sont des passes optionnelles, décrites dans finishing.md :

• la musique de fond va dans speech:mix avant le rendu ;
• les SFX (sfx.yml) et VFX (cues.yml) s'exécutent sur le master rendu et écrivent toujours un nouveau fichier.

Utilisez-les quand le brief demande une ambiance promo ou résumé. Les montages de talks simples en ont rarement besoin.

Travail parallèle

Pour les montages longs, divisez les tâches indépendantes (titres, lignes de narration, images de révision par section, transcriptions QA) dans config/production.json avec leurs depends. Confiez-les à des sous-agents via work:next, demandez-leur de rapporter avec work:log, et acceptez chacun après révision (work:accept). Les sous-agents peuvent écrire des scènes, scripts et docs en parallèle. Les jobs média lourds (medit, mgraphics/mvfx encodes, Demucs) s'exécutent toujours un à la fois (sécurité mémoire ci-dessus).