Agent skill · local FFmpeg · 42 tools
Give your coding agent a video editor.
Claude Code, Cursor, Codex or any MCP client edits your footage with local FFmpeg, then checks its own output.
$ npx ffmpeg-skill setupTake interview.mp4, keep 0:45–1:20 and 5:00–5:35, and make it exactly 60 seconds for Reels.
probe.py interview.mp4measuredcut.py --segments 0:45-1:20,5:00-5:35fit.py --duration 60 --method speed --aspect 9:16 --fit cropexport.py --preset reelscheck.py --platform reelsPASSlook.pycontact sheet
final.mp4: 59.98 s, 1080×1920, 30 fps, AAC stereoVERIFIED
The workflow it teachesevery job, in this order
- Probemeasure the real file
- Editlosslessly where possible
- Checkagainst the destination
- Verifylook at the result
Demos
Left is the input. Right is what the command produced.
The two videos run the tools on AI-generated footage; the previews below run them on AI-generated and phone footage. The previews are rebuilt by demos/build.py and the two videos by demos/pages_videos.py from its output, so you can make every frame yourself.
fit.py --aspect 9:16 --fit crop --crop-x 0.27Real speech, made vertical: the crop follows the speaker, not the centre. AI-generated footage.silence.py --filler --transcribeTurn the sound on: "er" and "um" play, then they are gone. AI-generated footage.

caption.py --animate pop --karaokeAnimated captions with a karaoke highlight
fit.py --aspect 9:16 --fit crop16:9 reframed to 9:16
silence.py --threshold -35Silence removed, timeline shorter
loudness.py -I -14 --tp -1Waveform before and after normalisation
color.py --to-sdr --tonemap hableHDR10 to SDR
overlay.py --chromakey 0x50b64fGreen screen onto a generated background
Twelve clips, edited by asking
Nine of the clips are AI-generated with Google Veo: the people and places in them do not exist. Three are shot on a phone and say so. Every edit is one of the skill's tools, built by demos/showcase.py; the request and the exact commands are in the showcase notes.
join.py · graphics.py · export.pyAll of them in 50 seconds.background.py · overlay.py --video · audio.py --replaceOne camera on the speaker, the slides as a second source: laid out side by side.overlay.py · caption.py --karaoke · export.py --preset reelsThe same talk as a captioned vertical short. Turn the sound on.color.py --correct · denoise.pyExposure, white balance, noise and grade, with the shadows and the neon kept.cut.py · fit.py --aspect 9:16 · join.pyThe shot, reframed to vertical: the player, then the hoop.silence.py --threshold -30A long pause, then the same take without it: 7.9 s to 5.9 s. Turn the sound on.overlay.py --video --chromakeyGreen screen keyed, resized and placed in a new room.straighten.py --degreesA crooked horizon, levelled. The tilt was added for the demo: the generated clip was level.stabilize.pyHandheld at night, stabilised. Shot on a phone.color.py --correct --exposure · denoise.pyA dark night shot, lifted, with the noise the lift shows cleaned. Shot on a phone.fit.py --duration --method speed --fps 24Shot at 60 fps, played at 24: every frame is a real one, 2.5 times slower. Shot on a phone.
Then look at it, and say what to change
After an edit you can ask for a review page: one local HTML file with the sources, every step and its checks, the result in a phone frame with the platform's safe area, and a timeline. Press the number of a clip or a caption, write what should change, and copy the instruction back to your agent. Nothing is uploaded.
- 1Ask your agent: "show me the review page". Or run it yourself:
npx ffmpeg-skill review project.json --result run.json - 2Open the index.html it writes. Press C2 for the second clip or T2 for the second caption, and type what should change.
- 3Press "Copy the instruction" and paste it to your agent. It edits the project and renders again.
The page shown is the talk above (AI-generated with Google Veo), rendered as a vertical short. It speaks English, Japanese, Korean and Chinese.
How it works
It stops guessing.
An agent that “knows FFmpeg” still guesses: it assumes a frame rate, picks a codec the container cannot hold, re-encodes a file that only needed a stream copy, and reports “done” without opening the result.
Real files first
Every job starts with
probe.py. The agent decides from the measured duration, fps, resolution, colour and audio layout, not from the file name.Structured tools, not shell strings
Each operation is a script with typed arguments. Nothing runs through a shell, and no filter graph is accepted from the caller.
A contract the agent can read
contract --jsonstates, for every tool, what it takes, what it writes, which FFmpeg components it needs and how the result is verified.Verification after execution
The result is probed, checked against the destination’s spec and, when the picture changed, looked at as a contact sheet.
Local first
No cloud, no API keys, no Python dependencies. Optional speech-to-text runs on an engine you install, and the audio is never uploaded.
Tools
42
tools that do the actual work with ffmpeg / ffprobe.
- Cut & join
- Silence removal
- Fit to duration & aspect
- Captions & karaoke
- Overlays & motion graphics
- HDR → SDR & LUTs
- Audio clean-up & dynamics
- Sync & drift correction
- Multicam
- Loudness
- Delivery checks
- Project rendering
- Batch folders
Built for agents
MCP
Every tool is an MCP tool. A core 12 is listed by default to keep the client’s context small, all 42 with
tools/list · tools/callFFMPEG_SKILL_MCP_FULL=1.Contract
One machine-readable contract describes the whole set: what each tool takes and writes, what it needs from FFmpeg, and how it is checked.
contract --jsonSPEC
Each tool’s input schema is derived from the script’s own argument parser, never written by hand beside it. CI fails if the docs drift.
Self-Producing Execution Contract
Install
One command.
It installs the skill for every agent found on this machine, installs FFmpeg through your package manager when it is missing, then checks the machine. The other lines pick one agent.
$ npx ffmpeg-skill setupeverything in one go$ npx ffmpeg-skillClaude Code$ npx ffmpeg-skill --cursorCursor$ npx ffmpeg-skill --codexCodex$ npx ffmpeg-skill --allall three$ npx ffmpeg-skill doctorcheck the machine
Needs FFmpeg 6.1+ and Python 3.10+ on your PATH. Works offline. How to install FFmpeg itself on macOS, Linux and Windows is in the README.
FAQ
Questions people ask first
Can I pass raw ffmpeg arguments, or a filter_complex?
Why 42 tools? Isn’t that overkill?
What does “verified” check, and what can it not tell me?
How does ffmpeg-skill compare with Remotion?
Does it encode on the GPU?
On its own, it is a local FFmpeg engine. In Velisa, it is the hands: it cuts, measures and exports, and reports back in JSON. It never decides what to cut.
Velisa →Paper
What Is Verification-Driven Coding?
A Discipline for Not Trusting Generation
Kajiyama, S. (2026). Zenodo · doi:10.5281/zenodo.23720216
Read the paper →