# ffmpeg-skill

> A local FFmpeg video editor for coding agents: 42 typed tools, a machine-readable contract and an MCP server

- Category: Multimodal Generation / Video Generation
- Language: Python
- Licence: MIT
- Repository: https://github.com/kajisho5/ffmpeg-skill
- Website: https://www.npmjs.com/package/ffmpeg-skill
- Canonical page: https://ai-tldr.dev/tools/ffmpeg-skill/
- Updated: 2026-10-16

## In short

ffmpeg-skill is an Agent Skill for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`, built to give a coding agent a working video editor. It sits in the Video Generation category of the Multimodal Generation tools and is open-source, written in Python and licensed MIT. To get started: install the skill.

## Overview

ffmpeg-skill is an Agent Skill for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`, built to give a coding agent a working video editor. It teaches the agent a fixed workflow (probe, edit losslessly where possible, check, verify) and ships 42 Python scripts that do the actual work with `ffmpeg` and `ffprobe`: cutting and joining, silence removal, fitting to a duration and aspect ratio, captions and karaoke, overlays and motion graphics, HDR to SDR and LUTs, audio clean-up, multi-recording sync, multicam, loudness normalisation, delivery checks, whole-edit project rendering and batch folders.

Everything runs locally: no cloud, no API keys and no Python dependencies beyond the standard library, so it works offline on footage you would rather not upload. The tools need FFmpeg 5.0 or later and Python 3.9 or later. Optional local transcription (Parakeet or a Whisper engine) is used for auto-captions and filler-word removal when one is installed, and never required.

The design is aimed at agents rather than people. Every tool takes typed arguments (nothing runs through a shell and no filter graph is accepted from the caller), supports `--dry-run`, `--json` and `--plan`, never overwrites its input, and refuses an existing output unless `--overwrite` is passed. `contract --json` describes each tool's inputs, outputs, required FFmpeg components and verification steps, with the input schema generated from the script's own argparse parser so it cannot drift from the CLI. `doctor` reports which of those FFmpeg components the local build actually has, and `mcp/server.py` exposes the same tools over MCP with no tool table of its own.

## What it does

- 42 structured FFmpeg tools covering analysis, editing, audio, picture and delivery, each with `--help`, `--dry-run`, `--json`, `--plan FILE` and a reason on stderr on failure
- Captions burned from SRT/ASS or timed text, with phrase-aware wrapping, script-aware fonts for non-Latin text, animated word-by-word karaoke and optional local transcription
- Reframing with `fit.py` (pad, crop or blurred fill to any aspect ratio, fit to an exact duration), plus silence and filler-word removal, two-pass EBU R128 loudness and voice clean-up
- Platform delivery: export presets and `check.py` PASS / WARN / FAIL reports for YouTube, Shorts, Reels, TikTok, X, LinkedIn, Facebook, broadcast and podcast, and `render.py --template` for one-command platform renders
- A machine-readable contract (`contract --json`) and a `doctor` capability check that reports each needed FFmpeg encoder and filter as available, missing or unknown
- An MCP stdio server that lists a core 12 tools by default (all 42 with `FFMPEG_SKILL_MCP_FULL=1`), every tool callable by name, plus five canned workflow prompts

## Getting started

You need `ffmpeg` and `python3` on your PATH (FFmpeg 5.0+, Python 3.9+); the installer runs through `npx`, or you can install it as a Claude Code plugin without Node.

1. Install the skill

   The default target is Claude Code (`~/.claude/skills/ffmpeg-skill`); add a flag for Cursor, Codex or all three. Re-run the same command to refresh an existing copy.

```bash
npx ffmpeg-skill              # Claude Code
npx ffmpeg-skill --cursor     # Cursor
npx ffmpeg-skill --codex      # Codex
npx ffmpeg-skill --all        # all three

# or, as a Claude Code plugin:
claude plugin install kajisho5/ffmpeg-skill
```

2. Check the machine

   `doctor` confirms ffmpeg, ffprobe and every FFmpeg component the tools need. Check the per-tool `usable` answer in `doctor --json`: a build can be `ok` overall while a single tool such as `caption.py` lacks the `subtitles` filter.

```bash
npx ffmpeg-skill doctor
npx ffmpeg-skill doctor --json
npx ffmpeg-skill contract --json | head -40
```

3. Ask your agent for an edit

   Describe the result in plain language. The agent probes the file, runs the matching tools (`cut.py`, `fit.py`, `export.py`, `check.py`) and inspects a `look.py` contact sheet before it reports back.

```text
Take interview.mp4, keep 0:45–3:10 and 5:00–6:30, and make it exactly 60 seconds for Reels.
```

4. Run the tools from any shell

   Each tool is also a plain script. `--dry-run` prints the plan without running ffmpeg, and `render.py --template` fills a shipped platform template in one command.

```bash
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
python3 $S/render.py talk.mp4 --template tiktok --cues cues.txt
```

5. Connect it over MCP

   Point an MCP client such as Claude Desktop or Cursor at the bundled stdio server. On Windows with a python.org install, use `python` instead of `python3`.

```json
{"mcpServers": {"ffmpeg-skill": {"command": "python3", "args": ["/Users/you/.claude/skills/ffmpeg-skill/mcp/server.py"]}}}
```

## When to use it

- Let a coding agent cut a long recording into a captioned 9:16 clip for Reels, TikTok or Shorts and check it against the platform's spec
- Clean up a podcast or talk: remove dead air and filler words, clean the voice and normalise to a podcast loudness target
- Process sensitive footage entirely on your own machine, with no uploads and no API keys
- Give an agent framework a typed, machine-readable video toolset over MCP instead of hand-written ffmpeg command lines

## Version history

- 2026-10-16 v2.10.3: Draws pad, text, box and background colours in BT.709 to match the output's colour tag, and labels untagged clips BT.709 in mixed joins, multicam, B-roll and video overlays.
- 2026-10-15 v2.10.0: Lets a `render.py` project carry a video layer in `overlays[]`, for picture-in-picture or chroma-keyed green-screen compositing.