ffmpeg-skill: a local video editor for your coding agent
Say "keep these two parts, 60 seconds for Reels" and the agent cuts, reframes and opens the result to check it
- Who
- A personal project by kajisho5 (Kajiyama S.), for people who want to hand video editing to a coding agent.
- When
- Public since 3 September 2026; latest is v2.21.0 on 30 October 2026, the third release in two days.
- Where
- Claude Code, Cursor, Codex and any MCP client, on macOS, Linux and Windows. Everything runs on your machine: no cloud, no API keys.
What was hard
Turning one recording into a Reel meant looking up how to cut, reframe, level the audio and pick export settings, one by one. Ask an agent to write the FFmpeg commands and it would guess the frame rate, re-encode a file that only needed a copy, and say it was done without opening the result.
What it does about it
ffmpeg-skill gives the agent a fixed workflow and 42 tools. Typed Python scripts run ffmpeg instead of shell strings, and every result is measured again and returned as JSON with its length and size. When the picture changed, the agent has to look at a contact sheet before it may report the job done.
How it runs inside
- 1
You → Claude Code
"interview.mp4, 60 s for Reels"You say which parts to keep and where it is going. - 2
Claude Code → SKILL.md
probe → edit → check → lookThe agent reads SKILL.md's workflow and request-to-script table to pick the tools.SKILL.md - 3
Claude Code → probe · cut · fit · check.py
probe.py interview.mp4Duration, fps, resolution and audio are measured first; the plan comes from those numbers.scripts/probe.py - 4
Claude Code → probe · cut · fit · check.py
cut.py --segments 0:45-3:10,5:00-6:30What needs no change is stream-copied, not re-encoded.scripts/cut.py - 5
probe · cut · fit · check.py → ffmpeg / ffprobe
an argument list, no shellThe tool calls ffmpeg directly; a hung run is killed by --timeout and its partial file removed.scripts/_common/runner.py - 6
Claude Code → probe · cut · fit · check.py
fit.py --duration 60 --aspect 9:16Length and frame are fitted, then export.py --preset reels writes the file.scripts/fit.py - 7
probe · cut · fit · check.py → final.mp4 + contact sheet
check.py --platform reels, look.pyPASS/WARN/FAIL against the spec, and a contact sheet PNG the agent looks at itself.scripts/check.py
What goes in, what comes out
Is it for you
Good for
- People who often turn interviews or talks into Reels, Shorts or TikToks
- Editing footage you would rather not upload anywhere
- Handing captions, silence removal and loudness to an agent
- Using the same tools from Cursor, Codex or an MCP client as well as Claude Code
Not for
- It does not decide what to cut or which scene is interesting; it runs the edit and leaves judgement to the agent or you (per the README).
- It does not find faces or subjects. A vertical crop is centred unless the agent picks a position from the contact sheet.
- Captions from speech (--transcribe) need a local speech engine such as faster-whisper, installed separately.
- Homebrew's plain ffmpeg on macOS lacks the subtitles and drawtext filters; it needs ffmpeg-full.
Reviewed by Devalley’s editor before publishing. How the column is made