kajisho5/ffmpeg-skill

What it does

ffmpeg-skill is a local video and audio editing engine that a coding agent drives through structured CLI tools. It targets Claude Code, Cursor, Codex and any MCP client. Instead of letting an agent write raw FFmpeg command lines, the project exposes 42 Python scripts with typed argparse flags; each run is probed before it starts and the written file is measured afterwards. A job usually follows probe → edit → verify, with probe.py, cut.py, fit.py, export.py, check.py and look.py (contact sheet) working together.

The same tool definitions are published as a machine-readable contract and served over MCP. The contract's input_schema is generated from each script's live argparse parser, so the CLI, the contract and the MCP tools/list cannot drift independently; a test exercises that invariant. Over MCP only the core 12 tools are listed by default to save context, and all 42 remain callable through tools/call.

Quick start

FFmpeg 6.1+ and Python 3.10+ are prerequisites; Node 16+ is only needed for the npx installer. On Ubuntu/Debian:

sudo apt install ffmpeg
npx ffmpeg-skill            # Claude Code; use --cursor, --codex or --all for others
npx ffmpeg-skill doctor     # check ffmpeg, ffprobe and required components

The installer copies the skill into the agent's skills directory. You can then ask in natural language, for example to keep two ranges of a clip and fit the result to a 9:16 Reels duration. The agent is expected to run probe.py, cut.py, fit.py, export.py, check.py and look.py, then report the measured result. Tools also run directly from a shell:

S=~/.claude/skills/ffmpeg-skill/scripts
python3 $S/probe.py input.mp4 --compact
python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run
python3 $S/export.py input.mp4 --preset reels --json

Platform templates are rendered with render.py, e.g. python3 $S/render.py talk.mp4 --template tiktok --cues cues.txt; shipped templates cover TikTok, Reels, Shorts, YouTube, X, LinkedIn, Facebook, podcast and audiogram. Running npx ffmpeg-skill again refreshes an installed copy, because copies are not updated automatically. Other installation routes, including the Claude Code plugin and manual copying, are listed in the install section.

Constraints and limits

• FFmpeg builds vary. doctor reports required filters and encoders such as libx264, aac, drawtext, subtitles (libass) and loudnorm; its overall ok can be false while most tools still run, so check the per-tool usable field in doctor --json. Some Homebrew bottles lack libass, libfreetype or libzimg.
• Speech-to-text captions need a separately installed local engine, for example pip install faster-whisper; the first run may download a model. Without one, other tools still work and --transcribe refuses with an install hint.
• Verification is about measurable file properties. verified cannot judge whether the result looks or sounds right; placement, legibility, framing, grade look and mix balance are listed as unverified.
• Known limitations: no automatic face or subject tracking for reframing, no removal of moving burned-in logos or subtitles, no GPU encoding except Apple VideoToolbox on Apple Silicon (nvenc, QSV, VAAPI and AMF are detected but not used by tools), and arbitrary FFmpeg arguments or caller-supplied filter graphs are not accepted.
• The project measured its one-hour benchmark on Linux, and the full real-device media corpus has not yet been run on Windows. The README notes that a full corpus run and an install by someone other than the maintainer still need Windows coverage (issue #143).
• Licensed MIT.

HotRepo's take

In the Python weekly chart recorded on 2026-11-03, the repository reached 6th place with 1,352 stars added and 4,443 stars in total, against 350 forks. That is a single weekly snapshot, so it supports the observation that the project drew substantial weekly attention, not a claim about longer-term adoption. What stands out technically is the contract-driven design: the CLI parsers are the single source of truth for both the JSON contract and the MCP schemas, and per-tool post-run measurement is treated as part of each tool's promise rather than an afterthought. That structure is what makes the 42-tool surface usable by an agent, and it is also the main thing to evaluate when considering it.