ffmpeg-skill
Les scripts se trouvent dans scripts/ à côté de ce fichier ; exécutez-les avec python3 <skill-dir>/scripts/<nom>.py, et les modèles de livraison dans templates/. Ce fichier suffit pour effectuer un travail : le tableau ci-dessous achemine la demande, et --help sur le script à exécuter est la liste de flags la plus complète et la moins coûteuse. Un fichier de référence coûte autant que celui-ci ; ouvrez-en un uniquement pour une question que vous avez : references/scripts.md (tous les flags des 42 scripts), references/devices.md (iPhone HDR, GoPro, DJI, enregistrements d'écran, Zoom), references/gotchas.md (la version longue des règles en une ligne à la fin). MCP : tools/list montre par défaut seulement les 12 outils principaux ; les 30 autres (selon ce tableau) restent appelables par nom via tools/call, décrits par contract --json ; définissez FFMPEG_SKILL_MCP_FULL=1 pour les 42.
Flags partagés, sur tous les scripts : --dry-run ; --json (chemin de sortie, une sonde de la sortie, les commandes exécutées) ; --json-brief (statut/sortie/vérifié plus un summary ; préférez-le pour les étapes d'écriture) ; --fast (qualité d'aperçu) ; --progress ; --timeout SECONDES (kind: timeout, défaut 1800) ; --overwrite (étape 7) ; --plan FICHIER (le dry run sous forme de plan render.py FICHIER exécutera plus tard ; refuse si une entrée a changé). Les outils de ré-encodage acceptent aussi --codec h264|hevc|av1|prores et --quality N : non défini, SDR est x264, HDR est x265 Main10 ; prores nécessite -o NOM.mov, h264 refuse le HDR (color.py --to-sdr d'abord).
Les outils d'écriture n'exécutent rien sous --dry-run ; les outils de mesure (probe, check, sync, multicam, scenes, cropdetect, report, silence, loudness, stabilize) peuvent encore exécuter ffmpeg/ffprobe, en ignorant les artefacts/fichiers secondaires (--edl, --sheet, un .ass généré) ; verify ignore le flag. Par outil : contract --json dry_run.
Workflow (dans cet ordre)
- Environnement, uniquement en cas d'échec. Ne commencez jamais un travail avec
doctor: une machine cassée échoue aveckind: missing_toolou une erreur ffmpeg nommant le filtre/encodeur. Exécutezpython3 <skill-dir>/scripts/_contract.py doctor(ounpx ffmpeg-skill doctor) après un tel échec, ou lorsqu'on vous demande ce que la machine peut faire : lisezok/usable, signalez la capacité manquante. Le schéma d'outil decontract --jsonest destiné à un agent de planification, pas à ce workflow. - Sondez ce à partir de quoi vous devez planifier. Exécutez
probe.pysur chaque entrée à partir de laquelle vous planifiez — durée, fps, résolution, codecs, canaux,variable_frame_rate_suspected— et chaque fois que l'utilisateur pose une question sur un fichier. Pas de sonde séparée avant chaque édition : le--jsonde chaque outil d'écriture contient déjà son entrée et une sonde de la sortie. Planifiez à partir de chiffres réels, jamais de suppositions. - Préférez la perte minimale. Si la demande peut être satisfaite sans ré-encodage (coupes nettes sur les images-clés, remuxage, modifications audio uniquement), ne ré-encodez pas.
cut.pyetloudness.pycopient la vidéo en flux par défaut ;--accuratesurcut.pyuniquement pour des coupes image par image. - Planifiez avec
--dry-run --json, puis exécutez. Faites confiance à--json, pas à la ligne de résumé d'un dry run, pour tout nombre dans le plan (une dimension peut y être un espace réservé). Utilisez avant les longs encodages, pour signaler des faits.--fastest la qualité d'aperçu,--progressimprime le pourcentage/ETA sur stderr. Ne pointez jamais-overs un fichier que vous n'avez pas créé dans ce travail sauf si l'utilisateur a demandé qu'il soit remplacé ; passez--overwriteuniquement dans ce cas. - Enchaînez dans un ordre logique. Une demande de livraison sans autre édition est une exécution de modèle unique (
render.py --template NOM ENTREE), pas une chaîne construite à la main. Sinon : couleur (HDR→SDR / LUT) → coupe → jointure → silence → ajustement → légende/superposition → synchronisation → audio → volume → export. Modifiez le cadre avant les légendes, afin que le texte soit dimensionné pour le cadre final. Ré-encodez le moins de fois possible : intermédiaires à CRF 18,export.pyen dernier. Trois étapes ou plus :render.pyavec un project.json. - Vérifiez le livrable. Avant de faire rapport, exécutez
check.py SORTIE --platform Xpour la destination nommée (une exécution de modèle le fait déjà). Les lignes de format (codec, format pixel, taille, pic vrai, tags couleur, VFR) peuvent être corrigées sans risque. Les lignes de jugement changent le contenu : durée (la coupe perd du matériel), format (le recadrage perd des bords), fps (perd du mouvement), volume (l'ambiance ne doit pas être amplifiée) — corrigez uniquement lorsque la demande implique la réponse, sinon énoncez le choix et son coût. Mentionnez les WARN ; ne les poursuivez pas. - Vérifiez la sortie. Confirmez que la durée, la résolution, les fps et l'audio correspondent à la demande, à partir de la sonde
--json/--json-briefde l'outil d'écriture ou deprobe.py, et rapportez ces nombres ("final.mp4 : 59,98 s, 1080x1920, 30 fps, AAC stéréo"). Une étape est terminée uniquement lorsque le script est sorti avec 0 et que la sortie est sondée comme attendue : une sortie non nulle, un fichier manquant ou vide, ou une sonde qui contredit la demande est un échec signalé avec le message d'erreur du script. - Conservez les originaux de l'utilisateur. Ne remplacez jamais la source ; écrivez de nouveaux fichiers à côté de l'entrée ou là où on vous le demande. Un chemin de sortie existant est refusé (
kind: input) ;--overwriteest la seule façon de dire "oui, remplacez-le". - Regardez l'image. Chaque fois que l'image a changé (légendes, superpositions, graphiques, recadrage/rembourrage, redimensionnement, couleur, transitions, un
join.pyredimensionnant un clip au cadre du premier clip,color.py --to-sdr), exécutezlook.py SORTIE --tiles 3x2(ou--at Tpour une seule image) et visualisez le PNG (4x3 pour une disposition sur tout le clip). Pas terminé tant queLook :ne nomme pas ce PNG — une sonde ne peut pas voir une légende sur un visage. Audio uniquement :Look : non nécessaire. Ce qu'il faut regarder se divise comme les lignes decheck.pyà l'étape 5 :- Mécanique (le travail propre de ce skill pour vérifier et rapporter) : le texte/logo spécifié est à la position spécifiée, les sous-titres apparaissent aux timestamps spécifiés, les dimensions sont paires. Le letterboxing de
fit.py --fit padest le résultat correct de ce mode, jamais un défaut à signaler. - Jugement (rapportez-le, ne le faites pas passer silencieusement ou ne le faites pas échouer) : si un sujet ou un visage est coupé, le texte se trouve sur un visage, les couleurs semblent délavées, une transition atterrit. Cela nécessite de décider ce qu'est le sujet lui-même, c'est l'appel de l'agent appelant — dites ce que vous voyez en une ligne ; ils jugent.
Sans capacité de vision, écrivez
Look : CHEMIN (pixels non inspectés ; l'agent n'a pas de vue d'image)— ne prétendez jamais qu'une image a été inspectée quand ce n'est pas le cas, sans attendre une capacité qui n'est pas là.
- Mécanique (le travail propre de ce skill pour vérifier et rapporter) : le texte/logo spécifié est à la position spécifiée, les sous-titres apparaissent aux timestamps spécifiés, les dimensions sont paires. Le letterboxing de
Avant d'exécuter quoi que ce soit : quoi demander, quoi supposer
Posez une question courte uniquement lorsque la réponse modifie matériellement la sortie et que la demande ne l'implique pas. Lorsque plusieurs choses sont ouvertes en même temps (un vague "faites-le pour les réseaux sociaux" laisse la destination, le format, la durée et les légendes ouverts), ne demandez pas une par tour : proposez un ensemble avec vos valeurs par défaut et laissez l'utilisateur modifier n'importe quelle partie ("Reels : 9:16 avec rembourrage, 60 s, -14 LUFS, pas de légendes — OK ?"). Une question, une réponse, puis l'exécution. Ne demandez jamais ce que probe.py peut vous dire.
- Destination décide du format, de la limite de durée, du volume et du codec ; "pour Reels" répond aux quatre et nomme un modèle. Pas de destination et une simple coupe/légende : conservez le format source et dites-le. Si l'utilisateur dit "exporter", "publier" ou "livrer", demandez où.
- Durée ("faites-la durer 60 s") sans méthode : accélérez pour des changements ≤1,5×, coupez sinon, dites lequel. Demandez quand le contenu est une discussion (la coupe perd des mots) et que le changement est important.
- Légendes sans source de texte :
--transcribesi un whisper local existe, sinon demandez le texte ou un fichier chronométré ; n'inventez jamais de dialogue. - Polices et marque : si l'utilisateur mentionne une marque, des couleurs ou "notre police", demandez ou créez
brand.jsonune fois, réutilisez-le. - Texte CJK / non latin : laissez l'outil choisir la police par script (
--fontle désactive) ;--lang ja|kopour le texte Han uniquement.doctor --json.fonts.scriptsdit ce qui s'affiche ici. Le tofu est un travail échoué. - Position du recadrage pour
--fit crop: centre par défaut, mais lorsque la demande ou la source nomme un sujet décentré ("gardez le produit à droite", quelqu'un visiblement décentré sur la planche), utilisez--crop-x/--crop-y(0=gauche/haut, 1=droite/bas) au lieu de deviner le centre, ou demandez quel bord garder. - Tout le reste (type de transition, style de légende) : choisissez la valeur par défaut conventionnelle, dites ce que vous avez choisi, proposez l'alternative en une ligne.
Ce que ce skill fait et ne décide pas
Ce skill coupe, joint, mesure, synchronise, exporte et vérifie des fichiers — il exécute une édition, il n'en décide pas une. Ce qui appartient à l'humain, à l'agent appelant ou à un autre skill :
- Quelle coupe est la bonne, ou si un livrable est approuvable — ce skill mesure et rapporte (PASS/WARN/FAIL de
check.py, erreur de durée decut.py) ; l'utilisateur ou l'agent de production décide si cela part. - Ce qui rend un highlight intéressant —
scenes.py --highlightsclasse par un proxy mesuré (énergie audio, durée) : des candidats, pas un verdict. - Composition de la miniature ou de la couverture — une décision de conception, pas une mesure.
- Comprendre ce qu'une vidéo raconte — il n'y a pas de vision ici au-delà des planches contact de
look.py, pour les yeux de l'agent appelant, pas pour que ce skill interprète. - Juger ce qui est beau — "appliquez cette LUT", "corrigez l'exposition de +0,3 stops" (
color.py) est mécanique ; "étalonnez cette scène pour qu'elle ait l'air cinématographique" appartient à un skill d'étalonnage (color-grading-skill) qui décide des paramètres, puis appellecolor.py. - Les mots dans une légende — le texte de réplique est gravé tel qu'écrit. Trop long pour le cadre signifie une taille plus petite,
--max-lines, ou la propre édition de l'utilisateur ; ne réécrivez, raccourcissez ou paraphrasez jamais, même lorsqu'on vous demande de "faire tenir" — dites-le, proposez--max-lines 1à une taille plus petite. - Choisir un sujet ou une région qui ne vous a pas été donné — "recadrer sur x=200, y=0" est mécanique une fois que la boîte est connue ; "recadrer pour garder l'intervenant dans le cadre" nécessite de décider ce qu'est l'intervenant, un jugement pour l'agent appelant (à partir d'une planche
look.py).
La ligne : la même entrée + les mêmes paramètres explicites produisant toujours la même sortie vérifiable appartiennent ici ; tout ce qui dépend du goût, de la compréhension ou de ce qui a l'air bon ou sonne bien appartient à celui qui porte ce jugement.
Si une demande nécessite une fonctionnalité FFmpeg qu'aucun des 42 scripts n'expose, dites-le et nommez l'option intégrée la plus proche — ne devinez jamais une invocation brute de ffmpeg/ffprobe en dehors de scripts/*.py. Cela contourne toutes les garanties que ce skill offre, donc jamais un fallback lorsqu'un flag de script ne couvre pas quelque chose.
Demande → script
Ce tableau et la liste tools de doctor --json sont la source de vérité sur ce qui existe : ne nommez qu'un script que vous avez vu dans l'un d'eux (il n'y a pas de doctor.py, de trim.py, de subtitle.py).
Les flags de timestamp (--start, --end, --at, --from, --duration, --offset, et les temps dans les fichiers de réplique et de chapitre) prennent des secondes, mm:ss(.fff), hh:mm:ss(.fff) ou SMPTE hh:mm:ss:ff avec @fps (00:01:02:[email protected]) — collez une feuille de réplique NLE telle quelle ; les flags de longueur (--min-silence, --margin, --fade) sont en secondes simples.
| L'utilisateur dit | Faites |
|---|---|
| "coupe de 1:20 à 2:05", "rogne les premières 10 s" | cut.py entree.mp4 --start 1:20 --end 2:05 |
| "garde seulement ces parties", "enlève le milieu" | cut.py entree.mp4 --segments 0-1:00,1:30-2:00 |
| "fais-le durer exactement 60 secondes" | fit.py entree.mp4 --duration 60 (vitesse) ou --method trim |
| "coupe ça et fais-le en HEVC / AV1 / ProRes" (codec de sortie nommé) | cut.py entree.mp4 --start 0:10 --end 0:40 --codec hevc (--codec/--quality sur tout outil de ré-encodage ; ProRes nécessite -o NOM.mov) |
| "enlève les pauses", "coupures sautées" | silence.py entree.mp4 [--threshold -40 --min-silence 0.8] |
| "enlève les euh et les hum", "supprime les mots de remplissage" | silence.py entree.mp4 --filler --words mots.json (timings de mots mesurés ; --transcribe les crée) |
| "ne coupe pas à l'intérieur d'une phrase, seulement les vraies pauses" | silence.py entree.mp4 --speech-aware — une respiration sous --min-silence dans une phrase est conservée, seules les pauses aux limites de phrases sont coupées ; se compose avec --filler en une seule liste |
| "un highlight de 60 s à partir de cette heure" | scenes.py long.mp4 --highlights 6 --target 60 --edl picks.txt → cut.py --segments |
| "coupe sur le rythme", "édite-le sur la musique" | scenes.py piste.mp4 --beats --json > beats.json, puis cut.py entree.mp4 --segments ... --snap beats --snap-source beats.json (--snap-source transporte la grille mesurée) |
| "accélère ici, ralenti là" (segments connus) | speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0 |
| "tiens cette image", "fige la dernière image" | freeze.py clip.mp4 --hold 2 |
| "ralenti fluide", "moitié vitesse mais fluide" | fit.py entree.mp4 --duration 2x --smooth interpolate (lent) ou --smooth blend |
| "inverse ce clip" | reverse.py entree.mp4 |
| "boucle ce clip pour remplir 30 secondes" | loop.py bg_loop.mp4 --duration 30 |
| "fais-le vertical / 9:16 / carré" | fit.py entree.mp4 --aspect 9:16 --fit pad (ou --fit crop ; --pad-fill blur pour des barres floues) |
| "redimensionne à une hauteur/largeur" | fit.py entree.mp4 --height 1080 (ou --width, ou les deux pour un cadre exact) |
| "recadre sur cette boîte exacte" (x/y/w/h connus) | crop.py entree.mp4 --x 100 --y 0 --width 1080 --height 1920 |
| "fond flou au lieu de barres noires" | fit.py entree.mp4 --aspect 9:16 --fit blur (image entière conservée, bordures une copie floutée et assombrie) |
| "tourne de 90 degrés", "miroir" | fit.py entree.mp4 --rotate 90 / fit.py entree.mp4 --flip h |
| "l'horizon est penché" (degrés connus) | straighten.py penche.mp4 --degrees -2.5 |
| "vue plate à partir de cette vidéo 360" (lacet/tangage/fov connus) | sphere.py insta360.mp4 --yaw 90 --pitch 0 --h-fov 100 --v-fov 70 |
| "ces vieilles images sont entrelacées" | deinterlace.py entree.mp4 |
| "c'est granuleux/bruyant, nettoie-le" | denoise.py entree.mp4 --strength medium |
| "floute/pixellise ce visage/plaque" (boîte connue) | redact.py entree.mp4 --x 820 --y 140 --width 240 --height 240 --mode pixelate |
| "stabilise ces images tremblantes" | stabilize.py entree.mp4 |
| "y a-t-il des barres noires là-dessus ?" | cropdetect.py entree.mp4 |
| "le clip Dolby Vision iPhone semble bizarre" | color.py clip.mov --to-sdr ou --strip-dovi (garder HDR, supprimer la couche DV) |
| "les couleurs semblent délavées / iPhone HDR" | color.py entree.mp4 --to-sdr |
| "c'est trop sombre/clair" | color.py entree.mp4 --exposure +0.5 (stops) |
| "la balance des blancs est verte/bleue/rouge/jaune" | color.py entree.mp4 --tint 0.03 (décalage vert-magenta) |
| "applique cette LUT" | color.py entree.mp4 --lut chemin/vers/une/LUT.cube |
| "un aspect cinématographique" | (l'agent appelant appelle le skill d'étalonnage couleur, puis ce skill avec les paramètres résultants ; ne devinez pas) |
| "ajoute ce logo/watermark" (fichier PNG connu, position) | overlay.py entree.mp4 --image logo.png --x 0.05 --y 0.05 --scale 0.15 |
| "ajoute du texte en bas à gauche" (texte, position de base) | overlay.py entree.mp4 --text "Nom du lieu" --x 0.05 --y 0.9 |
| "tiers inférieur animé pour le nom" (nom, titre) | overlay.py entree.mp4 --lower-third "Jane Doe" "Chief Engineer" |
| "sous-titres / légendes" avec un fichier SRT/ASS/VTT | subtitle.py entree.mp4 --subs dialogue.srt |
| "sous-titres karaoké" avec une couche de texte | `subtitle.py entree.mp4 --subs lyrics.ass --karaoke --style |