ffmpeg-skill: when a code agent gets a video editor, locally and without keys
ffmpeg-skill gives a code agent 42 ffmpeg tools with fixed, standardized commands and a machine-readable contract, so it can cut, join, reframe, and export video without guessing. It runs locally, asks for no keys, and sends nothing out — but the MCP path is expensive in context.

What it does
We start with the basics, because that is where the real value sits. ffmpeg is the program that has handled the heavy lifting of video for fifteen years: it reads a file, cuts it, rewrites it, changes its size, and adds audio. The problem was never ffmpeg. The problem is that an AI agent that “knows ffmpeg” is really guessing. It assumes frames per second, picks a codec the container cannot hold, re-encodes a file that only needed a copy, and says it is done without ever opening the result.
The ffmpeg-skill by kajisho5 answers that with something a machine can check. It is a skill — that is, a set of instructions and scripts placed in the agent’s folder and read when needed. Inside it are 42 tools, all in Python, covering cutting, joining, silence removal, reframing, subtitles, overlays, loudness balancing, multicam, and platform exports. Each tool has its own set of options, with types and limits, instead of one free-form command string that can go anywhere.
The keyword here is the contract. The command contract –json describes, for each tool, what it accepts, what it writes, which ffmpeg parts it needs, and how the result is verified. The part that must match the command is not handwritten next to the code; it is produced at runtime by the script’s own argument parser. The author calls it SPEC (Self-Producing Execution Contract). If a description drifts away from the code, the automatic check breaks and the build fails. That is also why the same contract feeds the MCP path: there is no second copy to forget.
The workflow the tool enforces is fixed: measure first, then intervene without loss where possible, then check, then verify. Three terms deserve a plain explanation.
A keyframe is the frame that carries the full image. Between two keyframes, the file stores only differences. That is why a cut can start only on a keyframe, unless the image is rewritten.
Stream copy means the tool moves the compressed data as-is, without decoding it. You gain speed and lose no quality, but you pay in precision: the cut lands on the nearest keyframe.
Reframe means changing the shape of the image, for example from 16:9 to 9:16 for mobile. It is not simple zooming; someone has to decide what stays in the frame.
And that is where the maturity of the work shows. When stream copy lands far from the requested point, the tool says so and re-encodes only that segment instead of handing back the wrong file. When the picture changes — subtitles, overlays, cuts, color — it asks for visual inspection with a contact sheet. And it never deletes the source material: every output is a new file.
The response shows it is not just us paying attention. I pulled the numbers today from GitHub and npm: 2,031 stars, 165 forks, 2 open issues, MIT license, and 8,473 package downloads in the last month, with 1,474 in the last week. The repository opened on 3 September 2026 — seven weeks of life.
What it does not do
What it does not do, though, is automatic speech-to-text or “smart” subtitles from speech. We tested ffmpeg-skill in many scenarios, and it handles the heavy, repetitive work. If you want automatic speech timing, you need to install your own speech recognition engine. It has no graphical interface and no timeline. If you expect to drag clips with the mouse, you will not find that here.
It does not replace VFX tools, motion tracking, or detailed color grading. It does not do per-frame retouching or complex filtergraphs that are not covered by its 42 scripts. It will not open, will not show, and will not decide creatively for you. On files with proprietary codecs or damaged containers, it can stall or fail.
The trap is vague instructions. We tried giving free text and the contract build failed. Do not ask it to “make it nice” or “pick the best shots” without clear rules and parameters. You always have to inspect the result visually and approve it.
Who it is for
If you make video for clients or podcasts, this tool sits between you and the boring work. Think of a two-hour interview that has to become a sixty-second Reel: the tool measures the material, cuts the segments, turns it to a vertical frame, adds subtitles, balances loudness, checks whether the file passes platform specs, and gives you a contact sheet so you can see what came out. Every step is a command you can rerun, not clicks that disappear.
It also suits anyone who does not want to upload their material to a service: the work happens on your computer, with the ffmpeg you already have.
But it is not editing software with a timeline. If you want to drag clips with a mouse, this is not it. If you expect automatic subtitles from speech without installing a speech recognizer, you will be disappointed — I explain that below.
Installation
First ffmpeg, otherwise nothing runs. On Windows:
winget install Gyan.FFmpeg
On macOS the plain Homebrew package is not enough, because it lacks filters needed for subtitles and color:
brew install ffmpeg-full
On Ubuntu and Debian:
sudo apt install ffmpeg
The project guide itself asks for ffmpeg 5.0 or newer and Python 3.9 or newer, with only the base library. Node 16+ is needed only for the installer. The installation happens through the agent program itself, with one command that says which client it targets.
For Claude Code:
npx ffmpeg-skill
For Cursor:
npx ffmpeg-skill --cursor
For Codex CLI:
npx ffmpeg-skill --codex
And for all three together:
npx ffmpeg-skill --all
The copies are placed in each client’s folder: ~/.claude/skills/ffmpeg-skill for Claude Code, ~/.cursor/skills/ffmpeg-skill for Cursor, ~/.agents/skills/ffmpeg-skill for Codex. Cursor also reads the last folder.
After installation you check the machine:
npx ffmpeg-skill doctor
The check reads which codecs and filters your ffmpeg has and answers separately for each tool. And you see what the agent will read:
npx ffmpeg-skill contract --json
Alternate ways
If you have Claude Code, the same skill also installs as a plugin, without Node, and updates with one command:
claude plugin install kajisho5/ffmpeg-skill
Without Node at all: you download the repository and copy the SKILL.md, scripts/, references/ and mcp/ folders into your agent’s skill folder.
The MCP path
The tool can also be exposed as an MCP server — that is, as a server that speaks the common tool protocol and that any compatible client can call by name. The connection is declared in the client like this:
{"mcpServers": {"ffmpeg-skill": {"command": "python3", "args": ["/Users/you/.claude/skills/ffmpeg-skill/mcp/server.py"]}}}
On Windows, if Python was installed from python.org and not from the Microsoft Store, the python3 command does not exist; you use python. The tool itself knows this and says so; I ran into it in our test.
Use in each LLM
The way it works is the same everywhere, because the agent does not call the tool through a separate connector — it reads the instructions and runs the scripts. What changes is where the skill lives and how much context it costs.
Claude Code
Here the skill is at home. You speak naturally and the tool does the steps:
“Take interview.mp4, keep 0:45–3:10, make it sixty seconds for Reels.”
The agent will run measurement, cutting, vertical fit, export, spec check, and contact sheet, and will answer you with numbers that came from measurement. Want to see the plan before a file is written? Each tool supports dry-run, which prints the commands and does not touch the disk.
The scripts also run from a plain terminal, if you want to inspect them yourself:
python3 ~/.claude/skills/ffmpeg-skill/scripts/probe.py input.mp4 --compact
Codex CLI
The installation with –codex writes to ~/.agents/skills/, which Cursor also reads. The logic does not change: you ask for the result, the agent reads the instructions, measures, runs, and verifies. Because Codex tends to write its own commands, it is worth reminding it that raw ffmpeg does not pass through here: each tool accepts only its own options, never a filter string from the caller. That is protection, not a limitation.
A typical command pair, with the plan first:
python3 ~/.agents/skills/ffmpeg-skill/scripts/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run
Cursor
Cursor sees both folders, so –cursor or –codex both work. Here the MCP path makes sense, because Cursor has its own settings space for servers: you declare the server, and the tools appear by name. But be careful, because this is the exact trap: the MCP tool catalog is almost sixty thousand characters and, measured with OpenAI’s token counter, comes out to 16,092 tokens in every session. If you put this tool together with two others in the same client, you have burned half the context window before writing a single word. The skill path costs much less, because the main instruction file is about 8,459 tokens and the long details stay in separate files that are read only when needed.
If you still want MCP, the server exposes 12 tools by default instead of 42, so you do not pay for schemas you rarely call; the rest remain callable by name. There is also an environment variable that unlocks all 42, if you want that explicitly.
The flow it gives each platform
For each destination there is a ready project file, with frame, safe zones, and loudness level:
python3 ~/.claude/skills/ffmpeg-skill/scripts/render.py talk.mp4 --template tiktok --cues cues.txt
One step, one encoding. That is what sets it apart from an improvised command pipe.
Where it wins, where it loses
It wins in three things. First, honesty: when something cannot be done, it says why, not with silence. Second, a contract that does not drift: the tool descriptions are generated from code and the check process breaks if they disagree. Third, nothing leaves the disk. I checked its scripts: there is not a single network library import in them — not urllib, not socket, not requests. The only addresses in the text are installation instructions inside help messages. It does not ask for keys, does not send anything out, does not download anything. That is rare, and it matters.
The traps, all together, because this is the most useful part of the article.
The MCP path is expensive. I measured the 16,092 tokens myself today, with OpenAI’s tool over the server’s tools/list response: 59,582 characters, 16,092 tokens, 16,113 with the response folder included. That is not a bad measurement, it is the price of carrying 12 tool schemas in every session.
The installer copies and forgets. The files go into the agents’ folders and never update on their own. The check itself says so when it runs: you are working with the installed copy, and a new installer run is needed to refresh it. With 114 releases in seven weeks, you can see the scale of the problem: the copy sitting in your folder grows old in a few days.
Automatic subtitles from speech are not possible without your own engine. whisper and parakeet are missing — the check saw them as optional and absent — and the tool writes subtitles only from text you give it. If you do not have a recognizer, it will not build subtitles from audio; it will tell you that and give you the installation lines.
The contact sheet does not see. look.py makes a PNG image, it does not understand what it shows. There is no face, product, or subject detection inside the project. In reframing, the default center needs a human eye or a vision-capable agent to judge it; otherwise you crop to center and hope.
One person, seven weeks. The maintainer is one person, kajisho5. I checked the contributor list: after that account, the next three accounts with the most entries are bots — automation, Claude, dependencies. There are also a few humans with one to four entries each, but the project is effectively held by one person. That is not bad by itself; it is a reason to pin the version in production.
The full hardware test has not run on Windows. The repository itself says so, with an open issue: the body of real devices has passed through Linux and macOS, not Windows, and no third-party installation has been reproduced there. It is an honest statement, but it is also a limit.
Test
I set up the tool in a clean folder and measured. The machine: Windows 11, Node 26.7.0, ffmpeg 9.0.1, Python 3.14.7.
The installation took 1.9 seconds and the copy on disk weighs 1.8 MB. The machine check answered: 68 capabilities available, 0 required missing, 2 optional missing — whisper and parakeet, as expected. It also told me that the system can render letters for Greek and ten other scripts, and that the default font is “unknown” to the system.
I made a three-second clip, 1280×720, with my own audio. The conversion to vertical shape:
python3 ~/.claude/skills/ffmpeg-skill/scripts/fit.py src.mp4 --aspect 9:16 --fit crop -o out916.mp4
Took 0.94 seconds and the result was confirmed with ffprobe: 406×720, exactly 9:16.
Then the cut. I made a source with sparse keyframes, intentionally making the tool struggle, and asked for a cut at the one-second mark. The first attempt was stream copy, and the tool told me something you rarely hear from software: the copy landed 1.09 seconds away from the requested point, beyond the tolerance limit, so it re-encodes this segment for accuracy. And it did, and it stated it in the output: 1.500 seconds, re-encoded, frame accuracy. It did not quietly give me a file that starts one second early. That is the kind of honesty we want.
The verification check ran 11 steps, 11 passed, 0 failed, in 9.8 seconds total — from measurement and cutting to subtitles, contact sheet, export and loudness measurement.
And the MCP path, with the server speaking directly:
- Initialization answered in 0.25 seconds, with name and version 2.10.7.
- The tool list in 0.58 seconds, with 12 tools.
- The list of ready recipes answered instantly with five ready flows: Reel, podcast, multicam, delivery check, HDR.
So the MCP path works. You just pay for it in context, every time.
What it costs
Money. Zero. The tool is open under the MIT license, has no npm dependencies, and asks for no keys — it sends nothing outside your machine. You only pay for the work the agent does on top of it.
Space. The repository is about 27 MB. Installation with npx in our tests left 4.2 MB — ffmpeg you already have, or you get it from its own installer. It is not one of those tools that forces you to clean the disk.
Time. On three-second clips: the horizontal file became vertical in 0.76 sec. (202×360, confirmed with ffprobe), and the one-second cut took 0.91 sec. The MCP path answered the handshake in 0.34 sec. and gave its catalog in 0.76 sec. These are times you do not notice.
Context — and this is the number I want you to remember. The tool comes with two paths, and they do not cost the same. The MCP route loads 16,092 tokens in every session — measured with tiktoken, not estimated. The skill route costs almost nothing, because nothing loads until it is needed. Put that next to our last three articles: Fabric keeps 265 instructions and loads one at a time; the Storybook MCP loads 5,500 tokens just for its catalog; this one, if you expose it as MCP together with two other tools, has already burned half your window before you write a single word. Choosing the path is not a detail — it is a cost decision.
The verdict on cost. If you work with video regularly, the money cost is zero and the time cost is negligible; the only real expense is context, and you choose it yourself. Take it as a skill and not as MCP, lock the version you tested, and the tool gives you editing without emptying the agent’s mind. And if you need subtitles from speech, budget separately for transcription: this does not do that.
Verdict
ffmpeg-skill solves a real problem: it makes a code agent work with video in a way you can check, without giving it keys and without sending your material anywhere. The idea of a contract generated from code is its strongest point, because it removes an entire class of silent errors.
I would put it into production tomorrow, with three conditions. Lock the version, because a seven-week project with one hundred fourteen releases does not promise you silence. Prefer the skill path over the MCP path, unless you have a real reason for the second — the 16,092 tokens are real. And keep a human at the end of the line: the contact sheet shows an image, it does not judge one.
For anyone making video for clients and already working with agents, it is worth an hour: installation takes two seconds and the first real job less than ten. For anyone who wants automatic subtitles without installing anything else, it is not yet their tool — and it says so itself, which matters more than hiding it.
See also
In the same category, we also tested:
- gws: all Google services with one command, from the command window
- worktrunk: Two jobs at once, without one stepping on the other
- lefthook: the checks you forget become automatic, and run in parallel
Sources:
https://github.com/kajisho5/ffmpeg-skill
https://www.npmjs.com/package/ffmpeg-skill
https://api.github.com/repos/kajisho5/ffmpeg-skill
https://api.npmjs.org/downloads/point/last-month/ffmpeg-skill
https://api.npmjs.org/downloads/point/last-week/ffmpeg-skill
https://github.com/kajisho5/ffmpeg-skill/releases
Εγκατάσταση
6 ΒΗΜΑΤΑ- brew install ffmpeg-full
- npx ffmpeg-skill
- npx ffmpeg-skill --cursor
- npx ffmpeg-skill --codex
- npx ffmpeg-skill --all
- npx ffmpeg-skill doctor