ffmpeg-skill
Install

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 setup
No cloud No API keys Python standard library

Take interview.mp4, keep 0:45–1:20 and 5:00–5:35, and make it exactly 60 seconds for Reels.

  1. probe.py interview.mp4measured
  2. cut.py --segments 0:45-1:20,5:00-5:35
  3. fit.py --duration 60 --method speed --aspect 9:16 --fit crop
  4. export.py --preset reels
  5. check.py --platform reelsPASS
  6. look.pycontact sheet

final.mp4: 59.98 s, 1080×1920, 30 fps, AAC stereoVERIFIED

The request from the README's quick start, and the tools the agent runs for it.

The workflow it teachesevery job, in this order

  1. Probemeasure the real file
  2. Editlosslessly where possible
  3. Checkagainst the destination
  4. 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.
Every before/after demo, with the exact command

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.

  1. 1Ask your agent: "show me the review page". Or run it yourself: npx ffmpeg-skill review project.json --result run.json
  2. 2Open the index.html it writes. Press C2 for the second clip or T2 for the second caption, and type what should change.
  3. 3Press "Copy the instruction" and paste it to your agent. It edits the project and renders again.
The review page: sources and work steps on the left, the source frames and the vertical result in the middle with a timeline below, and on the right the selected caption with the instruction that will be copied to the agent

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.

  1. 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.

  2. 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.

  3. A contract the agent can read

    contract --json states, for every tool, what it takes, what it writes, which FFmpeg components it needs and how the result is verified.

  4. Verification after execution

    The result is probed, checked against the destination’s spec and, when the picture changed, looked at as a contact sheet.

  5. 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 FFMPEG_SKILL_MCP_FULL=1.

    tools/list · tools/call
  • 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 --json
  • SPEC

    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?
No. Each operation is a script whose flags are its own argument parser, and that parser is what the contract and the MCP schema are built from. A caller-supplied filter graph, -vf string or other ffmpeg option is not an argument any script accepts.
Why 42 tools? Isn’t that overkill?
One tool per job, because each job promises something different and the tool measures that promise after the run. An agent does not read 42 schemas: over MCP it sees a core 12 and calls the other 30 by name when a job needs one.
What does “verified” check, and what can it not tell me?
It covers what can be measured from the file: that it opens, its length, codecs, size and frame rate, and the tool’s own promise, such as loudness after normalising. A value that cannot be read fails as not_measured instead of passing. Whether it looks or sounds right is listed as unverified, so you look at the contact sheet.
How does ffmpeg-skill compare with Remotion?
They complement each other. ffmpeg-skill edits footage you already have; Remotion renders a video from React components. remotion-ffmpeg-skill joins the two: it measures with this repo, draws in Remotion, then checks and delivers with this repo again.
Does it encode on the GPU?
On Apple Silicon, with VideoToolbox, when you ask for it with --hw or FFMPEG_SKILL_HW=1. Other GPU encoders are reported by doctor when your FFmpeg has them, but no tool encodes with them.
All questions in the README
Velisa Velisa

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 →