Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
★ 6,096⑂ 540👁 11⑃ 402● 149▤ 204
+419
日增长
+1,240
周增长
6,096
stars
540
forks
11
watchers
402
prs
149
issues
204
releases
README
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.
No cloud · No API keys · Python standard library
Website ·
Quick start ·
Demos ·
Tools ·
MCP ·
npm
bash
npx ffmpeg-skill
caption.py --animate pop --karaoke
fit.py --aspect 9:16 --fit crop
silence.py --threshold -35
loudness.py -I -14 --tp -1
Left half is the input, right half is what the command produced. Every before/after demo, with the exact command under each one → — all of it built by python3 demos/build.py, so you can rebuild every frame of it yourself. The footage is synthetic (FFmpeg's own test sources) except in three demos, reframe_talk, filler_en and pauses_en, which use two AI-generated clips of people who do not exist (demos/footage/).
ffmpeg-skill is an Agent Skill for Claude Code, Cursor, Codex and any agent that reads SKILL.md. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships 42 tools that do the actual work with ffmpeg / ffprobe: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also callable as an MCP tool (tools/list advertises a core 12 by default to keep client context small, with FFMPEG_SKILL_MCP_FULL=1 listing all 42; every tool is reachable by name through tools/call either way), and the whole set is described by a machine-readable contract.
If ffmpeg and python3 are on your PATH, it works: offline, on footage you would rather not upload.
SPEC (Self-Producing Execution Contract): each tool's input_schema — the part of its
contract and MCP tool definition that has to track the CLI flag-for-flag — is never
hand-authored beside the code. It is derived, at run time, from the same argparse parser that
already defines the CLI, and CI fails the build if any of it drifts.
→ full explanation
---
Standalone, and in an ecosystem
Standalone, this is a local FFmpeg engine: probe → edit → verify, npx ffmpeg-skill and nothing else. No API key, no account, no other repo required. Everything above and below this section describes that standalone tool, and none of it changes if you never read the rest of this one.
In kajisho5's wider video-production ecosystem, this repo is the hands: it cuts, measures and exports files, and reports back in structured JSON. It does not decide what to cut, whether a deliverable is approvable, what makes a highlight interesting, or what a caption should say (the user's cue text is burned as written, never rewritten to fit) — those are a brain's job, sitting in front of this engine, not inside it.
| You want to... | Use |
|---|---|
| Cut / join / measure / export a file right now | thisTop issues
#470Follow-ups found while fixing the audit's high findings (#469)6 comments · 2026-11-12#143Real-hands verification: Windows, Cursor and Codex installs on machines that are not the maintainer's, plus three editor reviews3 comments · 2026-09-11#551A picture tool given an audio-only output extension fails inside ffmpeg instead of being refused2 comments · 2026-11-15#552render: a multi-clip `frame.fit: crop` project keeps bars on clips of another aspect (join pads before fit crops)1 comments · 2026-11-15#545caption.py --fonts-dir: font_used can still differ from libass's pick for bitmap-only faces and fontconfig aliases1 comments · 2026-11-15#539Streams lost or mis-contained: siblings found while fixing #515, #517 and #5201 comments · 2026-11-15#479join (3.6.3) on FFmpeg 8.0.1: H.264+AAC MP4 join returns a clip 3 frames short1 comments · 2026-11-12#449Word-timed cuts: measured speech onset, separate lead/tail margins, word-index segments1 comments · 2026-11-11
Discussions
Latest release
v3.10.0 v3.10.0 2026-11-15_Automated release: version and notes generated from pull requests merged since 3.9.3._ Changed - A render.py project of several clips takes its picture size from the fit object, as a one-clip project does, in the render and in --export-timeline (526). fit.py gets the fit object's aspect, mode, width and height and the frame's only where the object has none, and the exported sequence (FCPXML, EDL, OTIO) is sized, and timed, from the same merge. Before, a multi-clip render fitted the object inside the joined picture and the export sized the sequence from frame alone, so the two dis
相关报道 (2)
News & coverage (4)
xpanera on X: "5. ffmpeg-skill, by kajisho5: 42 local FFmpeg tools and an MCP server for agents. MIT, v2.24.0 (Oct 31). Needs FFmpeg, no API key. Prompt (not run): trim the ...2026-10-31noteI checked my local version of ffmpeg-skill after noticing it had grown to 42 tools2026-10-31noteCan I use it on my Intel Mac? Things I checked before installing AI video tools2026-10-27ivooxGitHub Trending Today #48: reverify, keslr connect, anti-slop, boardui, ffmpeg-skill, chippytea2026-06-08