ffmpeg-skill weekly downloads statistics

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="brand/app-icon-dark.png"> <img src="brand/app-icon.png" width="128" alt="ffmpeg-skill app icon"> </picture> </p> <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="brand/logo/ffmpeg-skill-wordmark-white.svg"> <img src="brand/logo/ffmpeg-skill-wordmark-black.svg" height="48" alt="ffmpeg-skill"> </picture> </p> <p align="center"><b>Give your coding agent a video editor.</b><br> Claude Code, Cursor, Codex or any MCP client edits your footage with local FFmpeg, then checks its own output.<br> No cloud · No API keys · Python standard library</p> <p align="center"> <a href="#quick-start"><b>Quick start</b></a> · <a href="docs/demos.md">Demos</a> · <a href="#tools">Tools</a> · <a href="#mcp">MCP</a> · <a href="https://www.npmjs.com/package/ffmpeg-skill">npm</a> </p> <p align="center"> <a href="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/ci.yml"><img src="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/ci.yml/badge.svg" alt="tests"></a> <a href="https://www.npmjs.com/package/ffmpeg-skill"><img src="https://img.shields.io/npm/v/ffmpeg-skill" alt="npm"></a> <a href="#ffmpeg-compatibility"><img src="https://img.shields.io/badge/ffmpeg-5.1%20%7C%206.1%20%7C%207.1%20%7C%208%20%7C%209%20tested-orange" alt="FFmpeg 5.1, 6.1, 7.1, 8 and 9 tested in CI"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"></a> </p>

npx ffmpeg-skill

<table> <tr> <td width="50%"><img src="docs/demos/captions_pop_karaoke.gif" alt="animated captions with a karaoke highlight"><br>_{<code>caption.py --animate pop --karaoke</code>}</td> <td width="50%"><img src="docs/demos/reframe_crop.gif" alt="16:9 reframed to 9:16"><br>_{<code>fit.py --aspect 9:16 --fit crop</code>}</td> </tr> <tr> <td width="50%"><img src="docs/demos/silence_removal.gif" alt="silence removed, timeline shorter"><br>_{<code>silence.py --threshold -35</code>}</td> <td width="50%"><img src="docs/demos/loudness.gif" alt="waveform before and after loudness normalisation"><br>_{<code>loudness.py -I -14 --tp -1</code>}</td> </tr> </table>

Left half is the input, right half is what the command produced. All 53 before/after demos, with the exact command under each one → — all of it generated from synthetic footage by python3 demos/build.py, so you can rebuild every frame of it yourself.

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	this repo (ffmpeg-skill), standalone
Decide cut points, approve a deliverable, plan a whole edit	video-production-agent / AI-video-production-OS
Build a typed editing graph across a workspace, without writing raw ffmpeg	video-editing-skill / audio-production-skill