ffmpeg-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.

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

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

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

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

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

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// 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

Every verified update to ffmpeg-skill that AI/TLDR tracked, newest first — each links to our coverage and the official changeset.

1. 2026-10-16v2.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.

   changeset ↗
2. 2026-10-15v2.10.0

   Lets a `render.py` project carry a video layer in `overlays[]`, for picture-in-picture or chroma-keyed green-screen compositing.

   changeset ↗

// How ffmpeg-skill compares

ffmpeg-skill alongside other open-source video generation tools AI/TLDR tracks, ranked by GitHub stars.