Sommaire11 parties
ffmpeg-skill est un projet open source (licence MIT) qui donne à un agent de code, comme Claude Code, Cursor ou Codex, 42 outils de montage vidéo fondés sur FFmpeg. Tout tourne sur ta machine, sans cloud et sans clé API. L’agent ne se contente pas de lancer une commande : il mesure ensuite le fichier produit pour vérifier son travail.
En bref
- 42 outils FFmpeg : coupe, silences, sous-titres, recadrage, loudness, exports
- Compatible Claude Code, Cursor, Codex et tout client MCP
- Local : pas de cloud, pas de clé API, pas de dépendance Python
- Le fichier produit est mesuré, puis inspecté en image par l’agent
- Licence MIT, installation avec npx
Ce qu’est ffmpeg-skill et ce qu’il règle
ffmpeg-skill est une « Agent Skill » : un paquet que des agents comme Claude Code, Cursor ou Codex lisent grâce à un fichier SKILL.md. Il impose à l’agent un déroulé fixe (mesurer le fichier, monter sans perte quand c’est possible, contrôler, vérifier) et lui fournit 42 outils qui appellent ffmpeg et ffprobe.
Le README part d’un constat : un agent qui « connaît FFmpeg » devine encore. Il suppose une fréquence d’images, choisit un codec que le conteneur ne peut pas contenir, ré-encode un fichier qui demandait une simple copie de flux, puis annonce « terminé » sans ouvrir le résultat. Le projet cherche à retirer ces approximations.
Comment fonctionne ffmpeg-skill
Chaque opération est un script Python avec des arguments typés. Rien ne passe par un shell et aucun graphe de filtres n’est accepté de l’appelant. L’ensemble est décrit par un contrat lisible par une machine : contract --json indique, pour chaque outil, ce qu’il prend, ce qu’il écrit, quels composants FFmpeg il exige et comment son résultat se vérifie.
Chaque travail commence par probe.py, qui mesure durée, fréquence d’images, résolution, couleur et pistes audio : l’agent décide d’après le fichier réel, pas d’après son nom. Les outils copient les flux qu’ils n’ont pas besoin de toucher et ne ré-encodent que si c’est nécessaire. Après exécution, le résultat est sondé, comparé aux exigences de la destination et, si l’image a changé, regardé sous forme de planche-contact avec look.py.
Le README précise que ce « regard » est celui de l’agent s’il est multimodal : look.py produit seulement un PNG et ne détecte ni visages ni sujets. Sans yeux sur la planche, c’est à l’appelant de fournir lui-même le point de recadrage, le défaut étant un recadrage centré.
Ce que savent faire les outils
Le README liste les familles d’outils, avec des démonstrations avant/après générées par le dépôt. Chaque outil accepte aussi --dry-run, qui affiche les commandes FFmpeg prévues sans rien écrire, et --json, qui renvoie un résultat structuré.
Les commandes montrées sous les démos donnent une idée concrète de ce que l’agent lance : caption.py --animate pop --karaoke pour des sous-titres animés avec surlignage karaoké, fit.py --aspect 9:16 --fit crop pour passer du 16:9 au vertical, silence.py --threshold -35 pour supprimer les silences et loudness.py -I -14 --tp -1 pour normaliser le volume.
- Coupe, assemblage et suppression des silences
- Sous-titres et karaoké, incrustations et motion graphics
- Ajustement à une durée et à un format, HDR vers SDR et LUT
- Nettoyage audio, synchronisation avec correction de dérive, multicaméra
- Normalisation du volume, contrôles de livraison, rendu de projet, traitement par lots
Exporter pour TikTok, Reels ou YouTube
Une commande par destination suffit : render.py remplit un modèle livré avec le projet. Pour TikTok, le modèle applique un recadrage 9:16, des sous-titres mot à mot placés au-dessus de la barre de description et à l’écart de la colonne de likes, un niveau de -14 LUFS, le préréglage d’export tiktok, puis un check.py --platform tiktok sur le fichier écrit.
Des modèles existent pour tiktok, reels, shorts, youtube-shorts, youtube, x, linkedin, facebook, podcast et audiogram. --template all produit les sept destinations vidéo à partir du même montage et écrit un tableau récapitulatif.
python3 $S/render.py talk.mp4 --template tiktok --cues cues.txt
Installer ffmpeg-skill
Il faut ffmpeg et python3 dans le PATH. La commande npx ffmpeg-skill installe la skill pour Claude Code ; les options --cursor, --codex ou --all visent Cursor, Codex ou les trois. La commande doctor vérifie la machine et les composants FFmpeg dont les outils ont besoin.
Les sous-titres générés depuis la parole (caption.py --transcribe) demandent un moteur de transcription local, installé à part ; pip install faster-whisper est présenté comme le plus simple. Sans moteur, le reste fonctionne et --transcribe refuse en indiquant les lignes d’installation. Le moteur tourne sur ta machine, mais certains téléchargent leurs poids de modèle au premier lancement.
sudo apt install ffmpeg
npx ffmpeg-skill
npx ffmpeg-skill doctor
npx ffmpeg-skill contract --json | head -40
Utiliser ffmpeg-skill avec un client MCP
Chaque outil est aussi disponible comme outil MCP, via un serveur en JSON-RPC sur l’entrée standard. Par défaut, tools/list n’annonce que 12 outils de base pour garder léger le contexte du client ; FFMPEG_SKILL_MCP_FULL=1 affiche les 42, et tous restent appelables par leur nom.
La version 3.13.0 ajoute FFMPEG_SKILL_MCP_TOOLS, qui permet d’annoncer une sélection d’outils séparés par des virgules. Les noms et schémas d’entrée sont dérivés des scripts, ce qui évite qu’ils divergent.
Où en est le projet
Selon les chiffres relevés sur GitHub le 19 novembre 2026, le dépôt, créé le 3 septembre 2026, compte 8096 étoiles, 761 copies, 11 contributeurs et 52 tickets et demandes de fusion ouverts. Il est écrit à 99 % en Python et sous licence MIT.
La dernière version, v3.13.2, date du 18 novembre 2026. Elle documente un montage Reels sous-titré à partir d’une vidéo parlée, ajoute à doctor un contrôle du démarrage du moteur Whisper et protège les séquences d’images. La v3.13.1 a corrigé la conversion des sources HDR ou BT.2020 en RGB ; ce correctif est mesuré sur FFmpeg 6.1.1 seulement. Les versions 6.1, 7.1, 8 et 9 de FFmpeg sont testées en intégration continue, d’après le README.
Quelques repères
- MCP : Protocole ouvert qui permet à un assistant IA d’appeler des outils externes de façon standardisée. Un même outil peut ainsi servir plusieurs assistants.
- Normalisation du volume (loudness) : Ajustement du niveau sonore d’un fichier vers une valeur cible, pour que des vidéos différentes soient écoutées à un volume comparable.
Questions fréquentes
ffmpeg-skill est-il gratuit et open source ?
Oui, ffmpeg-skill est publié sous licence MIT. Il n’exige ni compte, ni clé API, ni cloud.
Comment installer ffmpeg-skill pour Claude Code, Cursor ou Codex ?
Avec ffmpeg et python3 dans le PATH, lance npx ffmpeg-skill pour Claude Code. Ajoute --cursor, --codex ou --all pour viser Cursor, Codex ou les trois, puis npx ffmpeg-skill doctor pour vérifier la machine.
ffmpeg-skill envoie-t-il mes vidéos en ligne ?
Non, le montage se fait avec FFmpeg en local, hors ligne. Les moteurs de transcription optionnels tournent aussi sur ta machine, mais certains téléchargent leur modèle au premier lancement.
Combien d’outils propose ffmpeg-skill ?
ffmpeg-skill compte 42 outils. Via MCP, 12 sont annoncés par défaut et FFMPEG_SKILL_MCP_FULL=1 les liste tous.
À retenir
ffmpeg-skill apporte à un agent de code 42 outils FFmpeg locaux, décrits par un contrat lisible par machine et suivis d’une vérification du fichier produit. Il demande ffmpeg et python3, s’installe avec npx et reste sous licence MIT.






