Communitygithub.com

top110341/ffmpeg

Éditez des vidéos et de l'audio avec FFmpeg local à partir de demandes en langage naturel : coupe, rogne, joint, redimensionne/recadre (9:16, 1:1), change la vitesse, ajoute des sous-titres et légendes (SRT/ASS, animés, karaoké), des logos et superpositions de texte, des tiers inférieurs et titres, supprime les silences, synchronise multicam et micro externe, normalise le volume, convertit HDR/Dolby Vision en SDR, applique des LUT, ajoute une musique de fond avec ducking, exporte pour les plateformes (YouTube, Reels, TikTok, X), vérifie la conformité, détecte les scènes et crée des compilations de highlights, génère des planches contact pour inspecter les résultats, et produit des fichiers de projet d'édition complète.

Qu'est-ce que ffmpeg ?

Ce skill permet à un agent IA (comme Claude Code, Cursor ou Codex) d'éditer des fichiers vidéo et audio en local via FFmpeg, sans dépendances cloud ni clés API, en utilisant uniquement la bibliothèque standard de Python 3.9. Il comprend 42 scripts spécialisés dans `scripts/`, chacun dédié à une tâche spécifique : coupe, rognage, redimensionnement, changement de vitesse, synchronisation multi-caméra, suppression de silence, normalisation du volume (LUFS), conversion de couleurs HDR vers SDR, application de LUT, ajout de légendes et sous-titres (avec transcription via Whisper), superposition de logos et de texte, détection de scènes, et export optimisé pour les plateformes sociales (YouTube, Instagram Reels, TikTok, X). Le skill fonctionne via une table de routage 'Request → script' qui indique quel script exécuter en fonction de la demande de l'utilisateur. Il propose un workflow structuré en 8 étapes : sondage, préférence pour la perte minimale, planification avec `--dry-run`, chaînage logique des opérations, vérification du livrable, validation de la sortie, préservation des fichiers originaux, et inspection visuelle via des planches contact. Les scripts partagent des flags communs (dry-run, json, progress, timeout) et acceptent des formats de timestamp flexibles. Le skill agit comme un exécutant mécanique : il découpe, mesure et exporte, mais ne décide pas du contenu créatif (quel plan garder, ce qui fait un bon highlight, le choix des mots dans les légendes).

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/top110341/ffmpeg/tree/HEAD/.claude/skills/ffmpeg-skill

Demander à votre IA préférée

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

Documentation

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)

  1. Environnement, uniquement en cas d'échec. Ne commencez jamais un travail avec doctor : une machine cassée échoue avec kind: missing_tool ou une erreur ffmpeg nommant le filtre/encodeur. Exécutez python3 <skill-dir>/scripts/_contract.py doctor (ou npx ffmpeg-skill doctor) après un tel échec, ou lorsqu'on vous demande ce que la machine peut faire : lisez ok/usable, signalez la capacité manquante. Le schéma d'outil de contract --json est destiné à un agent de planification, pas à ce workflow.
  2. Sondez ce à partir de quoi vous devez planifier. Exécutez probe.py sur 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 --json de 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.
  3. 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.py et loudness.py copient la vidéo en flux par défaut ; --accurate sur cut.py uniquement pour des coupes image par image.
  4. 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. --fast est la qualité d'aperçu, --progress imprime le pourcentage/ETA sur stderr. Ne pointez jamais -o vers un fichier que vous n'avez pas créé dans ce travail sauf si l'utilisateur a demandé qu'il soit remplacé ; passez --overwrite uniquement dans ce cas.
  5. 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.py en dernier. Trois étapes ou plus : render.py avec un project.json.
  6. Vérifiez le livrable. Avant de faire rapport, exécutez check.py SORTIE --platform X pour 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.
  7. 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-brief de l'outil d'écriture ou de probe.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.
  8. 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) ; --overwrite est la seule façon de dire "oui, remplacez-le".
  9. Regardez l'image. Chaque fois que l'image a changé (légendes, superpositions, graphiques, recadrage/rembourrage, redimensionnement, couleur, transitions, un join.py redimensionnant un clip au cadre du premier clip, color.py --to-sdr), exécutez look.py SORTIE --tiles 3x2 (ou --at T pour une seule image) et visualisez le PNG (4x3 pour une disposition sur tout le clip). Pas terminé tant que Look : 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 de check.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 pad est 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à.

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 : --transcribe si 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.json une fois, réutilisez-le.
  • Texte CJK / non latin : laissez l'outil choisir la police par script (--font le désactive) ; --lang ja|ko pour le texte Han uniquement. doctor --json .fonts.scripts dit 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 de cut.py) ; l'utilisateur ou l'agent de production décide si cela part.
  • Ce qui rend un highlight intéressant — scenes.py --highlights classe 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 appelle color.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 ditFaites
"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/VTTsubtitle.py entree.mp4 --subs dialogue.srt
"sous-titres karaoké" avec une couche de texte`subtitle.py entree.mp4 --subs lyrics.ass --karaoke --style

Skills associés