What is ffmpeg-skill?
ffmpeg-skill, by S. Kajiyama (kajisho5), gives a coding agent a local video editor. It is an Agent Skill (a SKILL.md workflow) plus 42 Python scripts that wrap ffmpeg and ffprobe: cutting and joining, silence removal, fitting to a duration and aspect ratio, captions with karaoke highlighting, overlays, HDR to SDR, loudness normalisation, multicam, platform export presets and delivery checks. Every tool is also an MCP tool, and a machine-readable contract describes each one.
The skill makes the agent follow a fixed order: probe the real file, edit losslessly where possible, then check the result and inspect a contact sheet. Nothing runs through a shell and callers cannot pass raw filter graphs. Speech-to-text captions need a local engine such as faster-whisper, installed separately.
The repo is MIT-licensed with about 4,200 GitHub stars, created in September 2026. It installs with npx ffmpeg-skill; the npm package is at 3.1.1 (31 October 2026), after more than 100 GitHub releases in two months.
Is ffmpeg-skill worth it?
ffmpeg-skill fixes the specific way agents fail at video. A model that knows FFmpeg still guesses: it assumes a frame rate, picks a codec the container cannot hold, re-encodes when a stream copy would do, and reports success without opening the file. This skill replaces free-form shell commands with 42 scripts that take typed arguments, and makes the agent probe the input first and verify the output after, down to a contact sheet it looks at when the picture changed. The README's example is a request to cut two segments of an interview to exactly 60 seconds for Reels, which the agent turns into six tool calls ending in a check that the file is 1080 by 1920 at 30 fps.
The engineering is careful. Each tool's MCP schema is generated from the same argparse parser as its command line, and CI fails if they drift, so the agent's view of a tool cannot fall out of step with the tool. Nothing passes through a shell and no caller-supplied filter graph is accepted, which closes the obvious injection route. CI tests against FFmpeg 6.1, 7.1, 8 and 9 across Linux, macOS and Windows. It needs only the Python standard library, and audio for transcription stays on the machine.
The weight is scope and pace. Forty-two tools is a lot of surface for an agent to choose from; the MCP server lists only a core 12 by default to save context, and the author's own routing evals report the agent finding the right flag from a symptom in 7 of 8 prompts, which is good but not perfect. The project went from first commit in September 2026 to version 3.1.1 by the end of October, with two majors that removed support for older FFmpeg and Python, and it is essentially one person's work. It also sits inside a larger ecosystem of the author's video skills, though it runs fine alone.
Against hyperframes, which renders new video from HTML, ffmpeg-skill edits footage you already have; the two are complements rather than rivals. For a developer who regularly asks an agent to trim, caption and export recordings, it removes most of the ways that goes wrong.
Where it earns its place
A developer advocate turning hour-long livestreams into short clips
Cut highlights to 60 seconds, reframe to 9:16 and caption them
Ask Claude Code in plain language; the skill runs probe, cut, fit, caption, export with the reels or TikTok preset and check. Free and local; the main cost is agent tokens.
A podcast producer at a three-person studio
Remove silences and normalise loudness for each platform
silence.py trims dead air and loudness.py targets -14 LUFS, with check.py confirming the export meets the platform spec. Audio never leaves the machine.
A platform engineer building an internal video pipeline on agents
Call reliable editing primitives from an agent framework
Read npx ffmpeg-skill contract --json for every tool's inputs, outputs and verification, and call tools over MCP or the CLI with --json output. Set FFMPEG_SKILL_MCP_FULL=1 to expose all 42.
Before you commit
- Setup
- Install FFmpeg 6.1+ (apt, Homebrew or gyan.dev builds), then npx ffmpeg-skill (--cursor, --codex or --all for other agents) and npx ffmpeg-skill doctor to check which tools this FFmpeg build supports.
- Integrations
- Claude Code, Cursor, Codex and any agent that reads SKILL.md; an MCP server for other clients; optional local speech engines (faster-whisper, whisper.cpp, Parakeet) for transcribed captions; Apple VideoToolbox encoding opt-in.
- Data and privacy
- Everything runs locally with no API keys; speech engines download model weights on first run but audio is never uploaded. MIT licence.
- Cost at scale
- No paid edition. Costs are local CPU or GPU time for encodes and the agent's own token usage; the author reports VideoToolbox at 2 to 7 times faster than x264 on an M4 Max.
- Limits
- Requires FFmpeg 6.1 or later and Python 3.10 or later; some tools fail on FFmpeg builds missing filters such as subtitles or libvidstab; no face tracking for reframing; installed copies do not update automatically.
What’s good
- Typed tools with no shell and no raw filter graphs
- Probe-first, verify-after workflow with contact-sheet checks
- MCP schemas generated from the CLI parser, checked in CI
- Fully local; Python standard library only
What’s not
- 42 tools is a wide surface for an agent to route through
- Over 100 releases and two majors in two months
- Effectively a single-maintainer project
- Speech captions need a separately installed whisper engine
Best for
Developers and small video teams who already use Claude Code, Cursor or Codex and want the agent to edit recordings without hand-written FFmpeg commands.
ffmpeg-skill alternatives
ffmpeg-skill: common questions
- Is ffmpeg-skill worth it?
- The safest way we have seen to let a coding agent loose on footage, wrapped in more tools and more releases than most people will ever need. We rate it 3.9 out of 5.
- How much does ffmpeg-skill cost?
- Free and open source (MIT). Needs FFmpeg 6.1+ and Python 3.10+; no API keys or cloud service.
- What are the downsides of ffmpeg-skill?
- 42 tools is a wide surface for an agent to route through; over 100 releases and two majors in two months; effectively a single-maintainer project; speech captions need a separately installed whisper engine.
- Who is ffmpeg-skill best for?
- Developers and small video teams who already use Claude Code, Cursor or Codex and want the agent to edit recordings without hand-written FFmpeg commands.
- How much does ffmpeg-skill cost for a team or in production?
- No paid edition. Costs are local CPU or GPU time for encodes and the agent's own token usage; the author reports VideoToolbox at 2 to 7 times faster than x264 on an M4 Max.
- Is ffmpeg-skill safe for company data?
- Everything runs locally with no API keys; speech engines download model weights on first run but audio is never uploaded. MIT licence.
- What are the best ffmpeg-skill alternatives?
- The closest alternatives we have reviewed are HyperFrames, VideoAgent and Anthropic Skills.
Answers checked Oct 31, 2026.