# ffmpeg-skill : un monteur vidéo local pour agents de code

> ffmpeg-skill donne à Claude Code, Cursor ou Codex 42 outils FFmpeg pour couper, sous-titrer, recadrer et normaliser une vidéo, en local et sans clé API.

- Type : actu de l'IA
- Famille : Agents IA · Montage vidéo pour agents
- Habitat : Terminal · Python · MCP
- Niveau : intermédiaire
- Langage : Python
- Licence : MIT
- Étoiles GitHub : 8252 (relevé le 19 novembre 2026)
- Source : https://github.com/kajisho5/ffmpeg-skill
- Publié le : 19 novembre 2026
- Page : https://geekus.fr/projets/ffmpeg-skill/

ffmpeg-skill est un projet open source (licence MIT) qui donne à un agent de code, comme Claude Code, Cursor ou [Codex](https://geekus.fr/projets/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.

```bash
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.

```bash
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.

Sources :

- [kajisho5](https://github.com/kajisho5/ffmpeg-skill) (README)
- [GitHub](https://github.com/kajisho5/ffmpeg-skill/releases) (notes de version)

Mots-clés : ffmpeg, mcp, claude code, vidéo, agent skill, python

---

Fiche publiée par Geekus : https://geekus.fr/projets/ffmpeg-skill/
