Ffmpeg Skill

What is Ffmpeg Skill about?

Ffmpeg Skill provides a collection of 42 FFmpeg‑based tools wrapped as a local MCP server. Each tool has a strict CLI schema that is automatically turned into a JSON contract, so AI agents can call them with typed arguments, get structured results, and verify the output. The whole workflow—probe, edit losslessly when possible, check, and verify—is baked into the skill, removing the need for cloud APIs or manual FFmpeg command construction.

How to use Ffmpeg Skill?

1. Install the skill – run npx ffmpeg-skill (add --cursor, --codex or --all to install for specific agents).
2. Check the environment – npx ffmpeg-skill doctor confirms that FFmpeg, required filters, and optional speech engines are available.
3. Read the contract – npx ffmpeg-skill contract --json returns the machine‑readable description of every tool; MCP clients use this to build calls.
4. Run a tool – either via the CLI, e.g. python3 ~/.claude/skills/ffmpeg-skill/scripts/cut.py input.mp4 --segments 0:45-3:10, or through MCP with tools/call providing the JSON arguments.
5. Verify – each tool automatically runs probe, check and look as needed and returns a structured JSON report containing status, output metadata, command list, and verification flags.

Key Features

• Full offline operation – no internet, no API keys, only FFmpeg and Python (standard library).
• 42 dedicated tools covering cutting, joining, silence removal, aspect‑ratio fitting, captioning (including karaoke), overlays, HDR↔SDR conversion, loudness normalisation, multichannel audio work, multicam sync, export presets for every major social platform, and more.
• Self‑producing Execution Contract (SPEC) – input schemas are generated directly from each script’s argparse definition, guaranteeing zero drift between CLI and contract.
• MCP‑derived interface – tools/list and tools/call are built on‑the‑fly from the contract; new flags appear automatically.
• Lossless‑first editing – stream‑copy cuts and joins whenever possible; re‑encoding only when required (frame‑accurate cuts, filters, format changes).
• Plan & dry‑run support – --dry-run, --plan, and --timeout let agents preview commands, cache stages, and avoid hangs.
• Verification pipeline – automatic probing, platform‑specific compliance checks (check.py), and contact‑sheet generation (look.py).
• Extensible via templates – one‑command delivery to TikTok, Reels, Shorts, YouTube, LinkedIn, Facebook, X, podcasts, and audiograms.
• Cross‑platform – works on Linux, macOS, and Windows; supports FFmpeg 6.1 – 9.

Use Cases

• Automated social‑media clipping – an agent receives a request like “keep 0:45‑3:10 and 5:00‑6:30, format for TikTok”, runs probe → cut → fit → export → check → look and returns a ready‑to‑post video.
• Podcast post‑production – silence removal, filler‑word deletion, loudness normalisation to –16 LUFS, and final export with export.py --preset podcast.
• Multicam interview stitching – sync multiple camera recordings via audio, switch automatically on loudest source, and render a final edit.
• Caption generation with local ASR – caption.py --transcribe uses a locally installed Whisper/faster‑whisper engine to create burn‑in captions without sending audio to the cloud.
• Batch processing of a media library – batch.py applies a recipe or a full render.py project to every file in a folder, using a content‑hash cache for speed.

FAQ

Can I pass raw FFmpeg arguments or a filter graph? No. Only the flags defined by each script’s argparse parser are accepted; the contract guarantees this schema.

Do I need an internet connection for speech‑to‑text? Only if you install a local ASR engine (e.g., pip install faster-whisper). The engine runs entirely on your machine; without it captioning still works but without transcription.

What FFmpeg version is required? FFmpeg 6.1 or newer. doctor will refuse to run on older builds.

How does the tool handle variable‑frame‑rate sources? probe.py detects VFR; editing tools automatically convert to a constant rate or use the --vfr-guard option to decide when to re‑encode.

What happens if an output file already exists? The tool refuses to overwrite unless --overwrite is supplied; the refusal is reported with kind: input and error.reason: output_exists.

Is GPU encoding supported? Apple VideoToolbox is used on Apple Silicon when --hw (or FFMPEG_SKILL_HW=1) is enabled. Other GPU encoders (nvenc, qsv, vaapi, amf) are detected by doctor but not used automatically.

How can I run the skill without the npm installer? Clone the repo and copy SKILL.md, scripts/, templates/, mcp/ and related folders into your agent’s skill directory; the contract and MCP server work the same way.

How do I debug a failure? The JSON report includes a diagnostics array, the exact FFmpeg command line, and a status object with error.kind and error.reason. Use --dry-run to view the command before execution.

npx ffmpeg-skill

Left half is the input, right half is what the command produced. Every before/after demo, 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.

Other repos in the ecosystem — media-analysis-skill, transcription-skill, subtitle-skill, thumbnail-skill, color-grading-skill, motion-graphics-skill, qc-skill — read this repo's contract --json, its tools' --json output and doctor, the same way any agent framework would; this repo does not call into any of them. The dependency runs one way.

Contents Standalone, and in an ecosystem · Why · Quick start · How it works · Design principles · Tools · Audio · Built for agents · FAQ · FFmpeg compatibility · Tested on real footage · Install · Requirements · Development · Docs

Why

An agent that "knows FFmpeg" still guesses: it assumes a frame rate, picks a codec the container cannot hold, re-encodes a file that only needed a stream copy, and reports "done" without opening the result. This skill takes the guessing out:

• Real files first. Every job starts with probe.py; the agent decides from the measured duration, fps, resolution, colour and audio layout, not from the file name.
• Structured tools, not shell strings. Each operation is a script with typed arguments. Nothing runs through a shell; no filter graph is accepted from the caller.
• A contract the agent can read. contract --json states, for every tool, what it takes, what it writes, which FFmpeg components it needs and how the result is verified. The MCP surface is derived from it.
• Verification after execution. The result is probed, checked against the destination's spec and, when the picture changed, looked at as a contact sheet.
• Local first. No cloud, no API keys, no Python dependencies. Optional local transcription is used when a speech engine (Parakeet or a whisper) is installed, never required — by caption.py --transcribe and, since 1.17, by silence.py --filler --transcribe; both take a transcript you already have instead, and both refuse with the install lines rather than guessing. Both take --engine and --model; FFMPEG_SKILL_ASR_ENGINE and FFMPEG_SKILL_ASR_MODEL set this machine's defaults (e.g. large-v3-turbo where that whisper.cpp model is installed; without either, auto and base). The engine runs on your machine and the audio is never uploaded; parakeet-mlx, faster-whisper and openai-whisper download their model weights the first time they run (parakeet-mlx's default from Hugging Face).

Paper

The design discipline behind this skill — per-operation verification for AI agents — is written up as a position paper. The paper scores ffmpeg-skill itself as only partially conformant with the discipline it defines.

Kajiyama, S. (2026). What Is Verification-Driven Coding? — A Discipline for Not Trusting Generation. Zenodo. https://doi.org/10.5281/zenodo.23720216

Quick start

# 0. FFmpeg itself, once (Ubuntu/Debian shown; macOS and Windows are in the Install table below)
sudo apt install ffmpeg

# 1. install the skill for Claude Code (Cursor: --cursor, Codex: --codex, all three: --all)
npx ffmpeg-skill

# 2. check the machine: ffmpeg, ffprobe and every FFmpeg component the tools need
npx ffmpeg-skill doctor

# 3. (for agent frameworks) read the machine-readable contract
npx ffmpeg-skill contract --json | head -40

Captions from speech (caption.py --transcribe) need one local speech engine, installed separately. pip install faster-whisper is the simplest; the first run downloads its model, and the audio never leaves the machine. Without an engine, everything else works, doctor lists the engine as missing optional, and --transcribe refuses with the install line for each engine it supports.

Already installed? re-run npx ffmpeg-skill to refresh ~/.claude/skills/ffmpeg-skill. Copies are not updated automatically.

doctor's overall ok and a single tool's usable are different signals: ok is false when anything some tool requires is missing, so one missing filter (a plain Homebrew ffmpeg without subtitles, or a build without libvidstab) turns it false even though most tools still run. Check doctor --json's tools field for the per-tool answer, not just ok.

Then talk to your agent:

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

The agent runs probe.py, cut.py --segments 0:45-3:10,5:00-6:30, fit.py --duration 60 --aspect 9:16 --fit crop, export.py --preset reels, check.py --platform reels and look.py, then reports "final.mp4: 59.98 s, 1080×1920, 30 fps, AAC stereo" with the contact sheet it inspected.

Deliver to a platform

One command per destination, with the app's own UI taken into account:

python3 $S/render.py talk.mp4 --template tiktok --cues cues.txt

That fills the shipped templates/tiktok.json: 9:16 crop, captions popped word by word above TikTok's description bar and clear of its like column, −14 LUFS, the tiktok export preset, and a check.py --platform tiktok on the file it wrote. The caption size comes from the delivery table, so since 1.17.1 the filled project also states "fit_size": "on": a size nobody asked for shrinks to fit the cue instead of splitting the sentence across two cues. A template that states its own fit_size, and a --brand that states a caption size, still win, and a project with "fit_size": "off" renders the captions 1.17.0 rendered. Templates ship for tiktok, reels, shorts, youtube-shorts, youtube, x, linkedin, facebook, podcast and audiogram; --template all (or a comma-separated list) renders the seven video destinations (tiktok, reels, shorts, youtube, x, linkedin, facebook) from the same edit and writes a <name>_pack.md table of what each one produced. Files land next to the input unless -o says otherwise, and --dry-run shows every planned command rather than a result. render.py --list-templates prints them with their frames, limits and safe zones. Alias spellings work everywhere a platform is named (youtube-shorts = shorts, ig = reels, twitter = x, fb = facebook).

The tools also work on their own, from any 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    # print the plan, run nothing
python3 $S/export.py input.mp4 --preset reels --json                 # structured result with a probe of the output

On Windows in Git Bash, python3 is only on PATH if Python was installed from the Microsoft Store; a python.org install exposes python (or the py launcher) instead — replace python3 with python above if you see a "command not found". bin/install.js and doctor/contract already handle this for you; only the raw script examples above need it spelled out manually.

More requests and the commands behind them: examples/README.md. To see everything run end-to-end on generated footage: npm run demo (the gallery in docs/demos.md).

How it works

Over MCP the same tools are reached through a transport that holds no tool table of its own:

Names, order and inputSchema in tools/list are translated from each tool's argparse parser at start-up, so a new flag or a new script appears in MCP with no edit to mcp/. A test copies the skill, adds, removes and edits a script, and reads tools/list again to prove it.

Design principles

These are the rules the skill file gives the agent and the code enforces.

1. Probe first. No tool decides from the file name. probe.py measures duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth, HDR format including Dolby Vision, colour tags and every audio stream before anything is cut.
2. Lossless when possible. cut.py and loudness.py stream-copy what they do not need to touch (join.py re-encodes so it can crossfade and conform mismatched clips; --copy --transition none joins clips that already match by stream copy). Re-encoding happens only when it must: frame-accurate cuts, filters, format changes, or a keyframe farther than the tolerance.
3. Plan before render. Every tool takes --dry-run (print the ffmpeg command lines, write nothing), --plan FILE (the dry run saved as a plan with fingerprinted inputs that render.py FILE executes later, refusing if an input changed), --json (structured result with a probe of the output), --fast (preview quality), --progress (percent and ETA), --timeout (a hung ffmpeg is killed and reported, never waited on forever; Ctrl-C or SIGTERM likewise stops the running ffmpeg, removes its partial output and reports kind: interrupted) and --overwrite (explicit consent before an existing output is replaced). A test runs every tool under --dry-run behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
4. Machine-readable contract. contract --json describes all 42 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, mutates_input: false. provides lists all 42 by a cross-repository Capability id (ffmpeg-skill.cut, ffmpeg-skill.loudness, ...) for kajisho5/AI-video-production-OS's CapabilityContract.provides — see docs/contract.md.
5. Contract-derived MCP. mcp/server.py builds its tools/list from the contract. Tool names, order and inputSchema cannot drift from the scripts; a test keeps the two byte-identical.
6. Capability detection. doctor reads ffmpeg -encoders / -filters / -bsfs and reports which of the components the tools need are present on this build (libx264, libass, zscale, loudnorm, xfade, …), before a job fails inside ffmpeg.
7. Unknown is not missing. When a listing cannot be read (a layout the parser does not know, ffmpeg exiting non-zero) the affected capabilities are unknown: never missing, never silently available. An installed filter is not reported absent; a failed detection is not a pass.
8. Verify the result. The output is probed, and when the picture changed (captions, overlays, crops, colour, transitions) the agent runs look.py and inspects the PNG. The report is not finished until its Look: line names that image; audio-only jobs say Look: not needed. "Inspects" means the calling agent's own vision, not a feature of this skill: look.py only renders a PNG; nothing in this repository detects faces, products, subjects, or "the interesting part" of a frame or a scene. When a crop or reframe needs to keep a specific part of the frame (fit.py --fit crop --crop-x/-y, see Tools), it is the multimodal agent looking at that PNG and choosing the anchor — a non-visual caller (a script, a CLI user without eyes on the sheet) has to supply that decision itself, and the default is a plain centre crop. Likewise scenes.py --highlights ranks candidate scenes by a measured proxy (--rank-by audio or --rank-by duration), never by content; it is the agent that turns a look at the sheet into a judgement.
9. One label per report. A finished job is Done:, a failure or a refusal is Failed:, and a partial result is Done: with the shortfall named in Notes: — never a third label such as Done (partially):.
10. Keep originals. No tool overwrites its input. Outputs are new files named <input>_<operation>.<ext> unless told otherwise, and a test hashes every input after the run.

Tools

42 public tools, all Python 3.10+ standard library, all with --help, --dry-run, --json, --plan FILE (a dry run written as a plan render.py executes later), non-zero exit and a reason on stderr on failure. --json-brief (1.11.0) prints the same result document trimmed to what a caller acts on — status, output, verified, a compact summary of the output probe, the tool's own keys and the command count instead of the command lines — for roughly a third of the bytes; --json itself is unchanged. Every re-encoding tool except export.py, render.py and batch.py (a preset or the project decides there) takes --codec h264|hevc|av1|prores and --quality N (1.8) and, with export.py, --hw/--no-hw (Apple VideoToolbox on Apple Silicon, opt-in; see doctor below), and every time flag takes seconds, mm:ss, hh:mm:ss.fff or SMPTE hh:mm:ss:ff with an optional @fps suffix (1.9).

Analysis and inspection

Editing

Audio

Picture

Delivery

Orchestration

Not tools, but part of the surface: mcp/server.py (the MCP transport) and scripts/_contract.py (contract --json, doctor). Per-flag reference for every tool: references/scripts.md.

Audio is a first-class input

WAV, FLAC, MP3, M4A/AAC, OGG and Opus go through probe, cut, join, silence, loudness, audio, sync and check --platform podcast with the same commands as video. The output extension picks the codec: -o out.wav writes PCM, -o out.flac FLAC, -o out.mp3 MP3, -o out.m4a AAC.

• Extraction. An audio extension on a video input drops the picture: audio.py talk.mp4 -o talk.wav, or --voice -o talk.m4a to clean it on the way. --audio-stream N picks a track; probe lists them under audio_streams.
• Join. join.py intro.wav episode.m4a outro.wav -o full.flac resamples every clip to one rate and channel layout and crossfades them (--transition none for a butt join). Audio and video inputs cannot be mixed in one join.
• Sample-accurate trims. cut.py talk.wav --start 1.2345 --end 2.3456 --accurate trims at the sample; the JSON reports precision (packet for a stream copy, sample for PCM / FLAC, codec_frame when a lossy encoder frames the audio again, frame for video) and the measured duration_error_ms. A .wav never receives compressed packets.
• Typed dynamics. audio.py --compress --comp-threshold -20 --comp-ratio 4, --limit --limit-ceiling -1, --gate --gate-threshold -45. Each flag is one documented option of FFmpeg's acompressor, alimiter or agate, range-checked before ffmpeg runs; no filter string is accepted from the caller.
• Loudness. loudness.py talk.wav -I -16 --tp -1.5 -o talk.m4a for podcast levels; check.py talk.m4a --platform podcast measures LUFS and true peak and reports the chapter markers and channel count.

Picture tools (fit, caption, overlay, graphics, color, export, scenes, look) refuse an audio file with "input has no video stream" instead of inventing a picture.

Built for agents

What is SPEC?

SPEC (Self-Producing Execution Contract) is the name this project's author, kajisho5, gave the pattern the tool layer is built on: each tool's input_schema — the part of its contract that has to track the CLI exactly, flag for flag — is never hand-authored side by side with the code. It is derived, at run time, from the one thing that has to be correct for the CLI to work at all: the script's own argparse parser.

Concretely, scripts/_contract.py's _capture_parser() imports every tool script and intercepts its parse_args() call to get the live, fully-built parser object — flags, types, choices, defaults, required/positional, mutually exclusive groups, all of it. input_schema is built straight from that object. (The rest of a ToolSpec — role, capabilities, inputs, outputs, output_schema — comes from a hand-authored table, TOOL_META, since those facts aren't things a parser can express; only input_schema is parser-derived.)

• The contract's input_schema for every tool is generated from the live parser directly.
• SKILL.md is two-tier (1.11.0): the file the agent loads every session keeps the workflow, the request→script table and one line per gotcha; the long-form detail lives in references/gotchas.md and the other references/ files, read only when a job needs it.
• The MCP server (mcp/server.py) carries no schema of its own; tools/list is translated straight from the contract, input_schema included.
• The docs (docs/contract.md's field reference, this README's tool table) describe the same shape. tests/test_contract.py runs on every CI run and fails the build if any of them drift out of sync with what the code actually does — it catches drift, it doesn't fix it for you.

So adding a flag to a script's argparse block updates input_schema and the MCP tool definition with no second edit, and a docs page or TOOL_META entry that falls behind fails CI rather than drifting silently. There is no separate input_schema file to forget to update.

Machine-readable contract

npx ffmpeg-skill contract --json            # or: python3 scripts/_contract.py --json
npx ffmpeg-skill contract --json --static   # without environment detection

The contract is generated from the code that runs, not maintained beside it. For each of the 42 tools (ffmpeg-skill/<name>) it states:

Next to the tool list the document carries a top-level deprecated list (since 1.10): what the next major removes, since when, the replacement and the surface it lives on. It is empty in 3.0.0: Python 3.9 and FFmpeg 5.x, the two 2.x entries, moved to removed with what 2.0 removed, and docs/contract.md "What 2.0 changed" and "What 3.0 changed" are written from that.

contract_version (1.0) is separate from the skill version, so a consumer can pin the shape and read the version for provenance. The document also states the invocation mapping (structured arguments → argv), the JSON shapes for success and failure ({"status": "failed", "error": {"kind": "input | ffmpeg | output | missing_tool | timeout | verification | interrupted", "message": …}}; a refusal adds error.reason, a stable code such as output_exists or plan_inputs_changed, and error.details, the facts behind it; warnings, fallbacks and skipped steps a run decided on its own are in diagnostics), and that no tool runs a shell or executes anything other than the named script, ffmpeg and ffprobe. Field-by-field reference: docs/contract.md.

MCP

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

On Windows, python3 is only on PATH if Python was installed from the Microsoft Store; a python.org install exposes python (or the py launcher) instead — if your MCP client reports the server failed to start, change "command" above to "python" (or the full path from where python).

mcp/server.py is a stdio JSON-RPC transport with no tool table of its own. tools/list is derived from the contract at start-up, in contract order, with inputSchema translated from each tool's input_schema. By default it lists only the core 12 (render, look, caption, export, check, fit, cut, audio, loudness, graphics, silence, probe) so a client doesn't pay context for 30 schemas it rarely calls directly; set FFMPEG_SKILL_MCP_FULL=1 to list all 42. Every tool, listed or not, is callable through tools/call, which maps structured arguments to argv and runs the named script; a raw argv form is accepted for compatibility and marked non-canonical. python3 mcp/server.py --list prints the tools; --call probe '{"inputs": ["a.mp4"]}' runs one from the shell.

No inputSchema lists json or progress: they are transport flags the server sets itself, not tool arguments (2.0; 1.x listed them unless FFMPEG_SKILL_MCP_LEAN=1). A client that still sends them is not refused.

The server also advertises a prompts capability: five canned workflow recipes an agent can ask for by name instead of composing the individual tool calls itself — reel, podcast, multicam, delivery_check, hdr. prompts/list returns each one's name, description and arguments; prompts/get {name, arguments} fills the matching template and returns one text message naming the actual command lines to run and what to check afterward. These are recipes, not new tool calls — every command line a prompt names is one tools/call (or the CLI) can already run.

Capability detection

npx ffmpeg-skill doctor          # human-readable
npx ffmpeg-skill doctor --json   # available / missing / missing_optional / unknown / detection / errors / tools / gpu_encoders / ffmpeg_security

doctor reads ffmpeg -encoders, -filters and -bsfs and resolves every capability the contract declares against this machine's build. Three states per capability: available, missing, unknown. Exit 0 when everything required is available, 1 when something required is missing, 2 when nothing is proven missing but a required capability is unknown. With detection on (the default), contract --json carries the same lists under capabilities. doctor also reports fonts: the default drawtext family, and fonts.scripts — one available/missing/unknown per writing system (ja, zh, ko, ar, he, hi, bn, ta, th, lo, ru, el, latin) with the file it would use — so "can this machine render Korean captions" is answered before the job, not after. doctor --json's tools field folds that down to one answer per tool — {"caption": {"usable": "no", "missing": ["filter:subtitles"], "fix": "..."}, ...} — so "is doctor overall ok" and "can I run caption.py on this machine" are answered separately: a plain Homebrew ffmpeg is ok for tools that don't need subtitles/drawtext/zscale, while caption's own usable is "no".

doctor --json's gpu_encoders reports which GPU-backed encoders (nvenc, videotoolbox, qsv, vaapi, amf) this ffmpeg build was compiled with — read from -encoders alone, so it proves the capability shipped, not that the GPU/driver on this machine will actually accept a job (that needs a real encode, which doctor's introspection never runs). It never affects ok or any tool's usable. The one GPU path a tool uses is Apple VideoToolbox, opt-in: --hw on every re-encoding tool (h264/hevc/prores on the GPU, AV1 stays on SVT-AV1), FFMPEG_SKILL_HW=1 to make it this machine's default for everything except export.py's delivery presets (those take --hw explicitly, or render.py --hw for a whole project). It runs only on Apple Silicon and never by default, except on a build with no libx264/libx265 (an LGPL ffmpeg that has only h264_videotoolbox/hevc_videotoolbox): there it is the only encoder, so every re-encoding tool and export.py's presets use it without --hw, the result says hw.source: "auto", and doctor lists the missing x264/x265 under covered_by instead of calling the tools unusable (--no-hw still asks for the CPU). It falls back to the CPU encoder — reported in the result's hw.fallback/hw.notes — only when VideoToolbox itself refuses a job (any other ffmpeg failure is reported as it happened, not retried); every result names the encoder that actually ran (batch.py, which encodes nothing itself: each results row), and a GPU encode adds a notes line that its quality is not CRF-equivalent. Measured on an M4 Max, 2–7× faster than x264/x265 medium; at matched SSIM (tests/bench_vt.py) 1.1–2.9× the bytes on SDR and 1.9–3.5× on HDR, which is why it is a flag and not the default (docs/design-decisions.md). doctor --json's hw says whether this machine can run it (platform_ok) and whether it is the default here (default_on).

doctor also compares the FFmpeg version with a small, dated table of high-severity FFmpeg CVEs (doctor --json's ffmpeg_security; source ffmpeg.org/security.html, checked 2026-10-22). ffmpeg-skill does not ship FFmpeg, so a decoder bug in the build you have stays yours until you upgrade it. When the version is older than the first upstream release on its branch that carries a fix (today: CVE-2026-8461, the MagicYUV decoder heap write, fixed in 8.0.3, 8.1.2 and 9.0), doctor prints one warning: line on stderr with the update command and lists it under ffmpeg_security.warnings. It is advice, never a failure: ok, each tool's usable and the exit code do not change. A distribution package (Ubuntu 8.0.1-3ubuntu2, Debian +deb13u1) may carry the fix as a backport under the old version number, so the line says the build is older than the fix, not that it is vulnerable. A version it cannot read (a git snapshot such as N-12345-g…) gets no warning, and nothing is fetched: the table ships with the skill.

Gotchas and best practices

The short list for humans. The agent-facing version, with the reasoning, is the "Things that look right but are wrong" and "Gotchas" sections of SKILL.md.

• Variable frame rate (phone and screen recordings). probe.py flags it; every re-encoding tool conforms to a constant rate automatically. cut.py samples the frame timing before a copy and switches to frame-accurate mode when it is variable or too short to judge, because copy-cuts on VFR land on the wrong frame (--vfr-guard average restores 2.x's rule, re-encoding whenever the nominal and average rates differ; --vfr-guard off keeps the copy). Choose the rate yourself with fit.py input.mp4 --fps 30 when the measured average is odd.
• Lossless cuts snap to keyframes. A stream-copy cut can start up to one GOP earlier than asked. cut.py re-encodes when the snap exceeds 0.5 s (--tolerance changes the limit). For a strictly lossless file pass --tolerance -1 (plus --vfr-guard off on a variable-frame-rate source), and expect the cut to land on the nearest earlier keyframe; the JSON result lists them under nearest_keyframes. A --segments join can still be re-cut: open-GOP video, a later segment of B-frame .mp4/.mov video that starts between keyframes (start it on a keyframe, or write .mkv), or a join that fails its check. A single .mp4/.mov copy keeps its edit list by default (since 3.0.0), so the picture starts where asked: the keyframe's pre-roll is stored but hidden by an MP4 edit list, which a player that ignores edit lists shows (--no-edit-list starts the file at the keyframe instead).
• HDR stays HDR. When the probe reports HDR (HDR10, HLG, Dolby Vision, BT.2020), the tools keep it rather than flatten it. Convert deliberately with color.py --to-sdr before H.264 deliverables or LUT work. export.py platform presets are SDR and warn on HDR input.
• Loudness targets. −14 LUFS / −1 dBTP for YouTube and social platforms (the loudness.py default), -I -16 --tp -1.5 for podcasts, -I -23 for broadcast. A clip measured at −40 LUFS or below is room tone, not content; raising it raises the noise. Check true peak as well as LUFS: check.py file --platform podcast measures both.
• Frame changes first, text second. Captions and overlays burned before a crop or resize end up off-frame. Reframe, then caption.
• Cropping 16:9 to 9:16 discards 70 % of the width. fit.py --fit crop centres by default; pass --crop-x/--crop-y toward the subject, or pad with --fit pad --pad-fill blur. Look at the contact sheet before deciding.
• Phrase-aware caption breaking (1.16). caption.py/graphics.py --wrap phrase (the default) never breaks inside a word or on the wrong side of a hyphen, never leaves a lone digit, kana or punctuation pair on a line, prefers Japanese sentence ends and particles over a mid-word break, and never ends a line on an article or preposition. All four are penalties over break positions that already fit, so no line is widened and the line count never changes; --wrap measured restores 1.15's width-only wrap. The text itself is never rewritten or shortened. Since 1.16.1 a Thai run and a katakana word are never broken inside (Thai writes no space inside a phrase and there is no dictionary: the break goes where you put a space or |), and a line wider than the safe width is reported as overlong with the fix named.
• Caption size fitted to the cue (1.17, reachable from the templates since 1.17.1). At a platform caption size a line holds about six em, so an ordinary sentence needs four lines and --max-lines 2 used to cut it into consecutive cues — half the sentence arriving late. caption.py --fit-size (default auto) walks the size down until every cue fits, before laying the cues out, with a legibility floor of 4.5 % of the frame height (--min-size, default 13 ASS units). An explicit --size or a brand.json size is a statement about the look and is never overridden — which in 1.17.0 also silenced the fitter on every render.py --template run, since a template fills the size from the platform table; 1.17.1 marks that size as the default it is ("fit_size": "on" in the filled project), so the type shrinks and no cue is split. --fit-size off restores that earlier behaviour byte for byte, and the caption text is still never rewritten to make it fit.
• Beat-synced cuts (1.17). scenes.py --beats reports the measured grid — tempo, beat times, and a confidence built from how far the winning autocorrelation lag stands above the others and how many onsets land on it. cut.py --snap beats (and a "snap" block in a render.py project) moves in/out points to the nearest beat within --snap-tolerance — and only onto the grid points a measured onset actually marks, never onto the regular grid's continuation through a passage with no music in it. Below --min-confidence it refuses: a cut point may move to a measured beat and may not appear from one, so speech and ambience get an honest "no steady pulse here" instead of an invented grid.
• Filler words (1.17). silence.py --filler --words transcript.json removes "um" and "uh" through the same cut graph the silences use. Never without measured word timings — there is no heuristic that finds an "um" without them that would not also cut real speech — and like, tipo and cioè are deliberately not in the built-in lists, because a discourse marker is a content word. Built-in lists since 2.19: English, Japanese, Korean, Chinese, Spanish, German, French, Portuguese, Italian, Dutch, Polish, Russian and Turkish; any other language takes --filler-words FILE. Whisper stays optional: --transcribe with no engine installed refuses and names the five installs.
• Throughput (1.17). batch.py --jobs N runs several files at once, capped at min(N, cpu_count, 8) and sharing one --timeout budget rather than one per item; the per-item table keeps its order. render.py --cache DIR reuses stages whose inputs and arguments did not change, so swapping an export preset re-runs export only. The cache is opt-in with no default directory, and the ffmpeg, skill and contract versions are part of every key, so a cache is never reused across them.
• Audiogram (1.16). waveform.py --image cover.png (or render.py --template audiogram) puts the waveform over a still plate for an episode that has no picture, with --platform for the frame, --title and burnt-in captions. The image is a local file you give: nothing is fetched and no cover art is ever invented.
• Emoji in captions and titles (1.15). caption.py/graphics.py --emoji-assets DIR composites a PNG per emoji (Twemoji/Noto naming, 1f389.png) on top of the text, because drawtext cannot load a colour emoji font at all and an installed one does not prove libass will draw it in colour — doctor --json's fonts.emoji answers that from a render probe. Without assets the run still succeeds and reports mode: mono. Nothing is ever downloaded.
• Indic and Thai text shaped correctly in titles and lower-thirds (1.15). graphics.py renders Devanagari, Bengali, Tamil, Thai and Lao through libass automatically (text_renderer: "ass"), because drawtext never reorders matras or re-clusters marks; Arabic and Hebrew were already correct on a fribidi build. --text-render drawtext with such a script is refused, never rendered wrongly.
• Non-Latin text picks a font by script (1.12). Japanese, Chinese, Korean, Arabic, Hebrew, Devanagari, Thai, Cyrillic and Greek cues, titles and overlays resolve a font file that covers them automatically, and a machine with no such font fails the job (kind: input) instead of rendering boxes. doctor --json's fonts.scripts says which languages this machine can render; --lang ja|ko disambiguates Han-only text, and --lang zh-TW (or zh-HK, zh-Hant) picks a Traditional Chinese face (2.19); an explicit --font/--font-file is always kept.
• Silence detection finds nothing? The default threshold is −35 dBFS. The tool prints a hint with the track's measured level; raise the threshold (silence.py --threshold -25) or shorten --min-silence.
• Sync results carry a confidence. Below 0.3, or an offset near the edge of the analysis window, is probably wrong: enlarge --analyze-seconds or find a clap. Recordings over ten minutes from separate devices need sync.py --fix-drift.
• Outputs are never overwritten silently. An existing output path is refused (kind: input, error.reason: output_exists, before anything runs); pass --overwrite where a replacement is intended.
• Nothing happens silently. A refusal names its error.reason and error.details; a stale output lock taken over, a run without a lock, a plan input nobody could fingerprint, a fallback (an odd-sized frame scaled to even, a substituted font, libaom for SVT-AV1), a skipped step and every warning are recorded in diagnostics and on stderr (codes: json_output.diagnostic_codes); tools that draw text name the font they drew with (font_used). A refused plan and a lock takeover also append a line to an audit log (<plan>.audit.jsonl, or render.py --audit-log FILE). A degraded or partial result says so: render.py's verified is every stage's, an unmeasured loudness or a report section that could not be built is a failing verification step, export.py reports trimmed, multicam.py's cuts name the camera rendered, and batch.py rows carry the failing step's error, verified, and a row for every input after Ctrl-C.
• Long masters need a longer --timeout. The default is 1800 s per ffmpeg call, which is there to catch a hang. A full re-encode of an hour of 1080p at the default preset ran past it on a 4-core machine (see A one-hour recording). Pass --timeout 0 or a larger value, or --fast. Analysis and stream-copy cuts are far below it.
• Long chains belong in a plan. Three hand-chained re-encodes lose quality and are hard to change; render.py runs the whole edit from one JSON file, and --dry-run shows every ffmpeg command before anything is written.

FAQ

Can I pass raw ffmpeg arguments, or a filter_complex?

Each operation is a script whose flags are its argparse parser, and that parser is what contract --json and the MCP inputSchema are built from. CI fails the build when those drift from the scripts. A caller-supplied filter graph, -vf string, or other ffmpeg option is not an argument any script accepts. doctor reads ffmpeg -filters (and -encoders, -bsfs) and reports a filter a tool needs before a job runs into it. MCP does accept an argv array, and that array is the named script's own CLI flags, still bound to that script: the script's flags, never an ffmpeg command line and never a shell.

Why 42 tools? Isn't that overkill?

One tool per job, because each job promises something different, and the tool measures that promise after the run. loudness.py re-measures integrated loudness and true peak. cut.py reports how far a cut snapped to a keyframe. silence.py returns the ranges it kept. export.py checks the preset's maximum length. A value a tool cannot read fails that step as not_measured; it does not pass. One tool with a mode flag would need as large a schema, and its checks would be vaguer.

An agent does not read 42 schemas. Over MCP, tools/list advertises the core 12 (bold below). The other 30 are called by name through tools/call when a job needs one, and FFMPEG_SKILL_MCP_FULL=1 lists all 42. The groups are the ones in Tools.

Without the other 30, an agent writes raw ffmpeg for those jobs, and a mistake there often still exits 0:

• stabilize.py runs vidstab in two passes, and the second pass needs the first pass's transforms file.
• color.py builds the HDR-to-SDR chain. With a wrong colour tag the run still finishes, and the picture comes out washed out.
• join.py puts transitions between clips that differ in size, frame rate or audio layout. Done by hand, those clips have to be normalised first or xfade fails.
• sync.py and multicam.py find the offset between two recordings by audio cross-correlation. No ffmpeg filter measures it.

Every command a tool ran is in its --json commands, shell-quoted so it can be pasted and run again, and --dry-run prints the commands without running anything. In the 100-prompt agent eval (1.17.0, Tested on real footage) the agent made no raw ffmpeg calls and reported no false successes.

What does verified check, and what can it not tell me?

verified covers what can be measured from the file. Each tool measures its output again: the probe (the file opens, its duration, codecs, size and frame rate) and the tool's own promise. For example, loudness and true peak after loudness.py or export.py, the length against the asked one, and for cut.py, join.py and export.py the stream count, where picture and sound end, and whether both ends of every stream decode. check.py grades a file against a platform's limits. A value that cannot be read fails its step as not_measured; it does not pass.

It cannot tell you whether the result looks or sounds right, and the result says so: every writing tool lists the properties it did not measure in unverified. Examples are picture_content (what is in the frame), subject_framing after a reframe, rendered_placement and legibility of captions and titles, grade_look after a colour conversion, removed_span_content after a silence cut (whether a removed span held speech), mix_balance and lip_sync. For those, look at frames with look.py (a contact sheet, or --safe for a platform's UI zones) and listen where the result points you. silence.py lists the level at every cut, and cut_warnings names the cuts that may have landed in a breath or a word's tail.

Are silence removal and captions stable?

They are the most used tools here, and they are tested on every pull request and every push to main on Linux, macOS and Windows, with FFmpeg 6.1 to 9. On 20 test files with known gaps, silence.py missed none and left at most 1 ms of silence (see Tested on real footage). A cut keeps --margin seconds of air on each side, 0.2 s by default; raise it to 0.3 s for a speaker who trails off. --speech-aware keeps the short breaths inside a sentence. Filler words are removed only from measured word timings (--words or a local --transcribe), never guessed. --timemap writes where each kept and removed range sits in the source and the output, for re-timing subtitles. If --threshold is set high enough to cut into a breath or a weak word ending, the result warns at that cut.

caption.py burns SRT/ASS or muxes them as soft tracks, fits the size to the platform's safe area, and picks a font that covers the script (Japanese, Chinese, Korean, Arabic, Thai, Hindi and others). It needs FFmpeg's subtitles filter (libass); doctor reports whether this build has it. Placement and legibility are listed as unverified, so look at a contact sheet before delivering. Speech-to-text runs on a local engine you install; its first run may download a model.

How well does HDR to SDR work, and what should I watch for?

color.py --to-sdr converts PQ (HDR10), HLG and iPhone Dolby Vision 8.4 to SDR BT.709 with real tone mapping (zscale and tonemap, hable by default; mobius, reinhard, clip, linear and gamma with --tonemap). BT.2020 footage on an SDR transfer gets a gamut conversion only. Watch for four things:

• It needs zscale (libzimg). The plain Homebrew ffmpeg lacks it, so use ffmpeg-full (keg-only: see Install for putting it on PATH); doctor reports whether it is there.
• --peak (default 1000 nits) should match how bright the source was mastered. A wrong value makes highlights dull or clipped.
• Tone mapping is a judgement, and the result says so (grade_look in unverified). Compare frames with look.py, and try another --tonemap if skin or skies look off.
• An HDR source that only needs to play everywhere may not need converting at all. --strip-dovi removes the Dolby Vision layer from an iPhone clip, keeping its HLG picture, with a stream copy.

How does ffmpeg-skill compare with Remotion?

ffmpeg-skill edits footage you already have, on this machine, with FFmpeg tools whose flags are a machine-readable contract (contract --json). Remotion renders a video from React components. They complement each other: this repository does not call Remotion, and a file Remotion writes is an ordinary input (probe.py, cut.py, fit.py, export.py, check.py). remotion-ffmpeg-skill joins the two. It measures the footage with this repo, draws the graphics in Remotion from those measurements, and checks and delivers the result with this repo again. Install both (npx ffmpeg-skill, then npx remotion-ffmpeg-skill). As with the other skills, the dependency runs one way: it calls these tools, and nothing here calls it. HyperFrames renders a video from HTML and is the same kind of neighbour: a file it writes is an ordinary input too.

Does it validate the filter graph before running?

No. --dry-run prints the ffmpeg command a writing tool would run and does not start ffmpeg, so ffmpeg never parses that filter graph. ffprobe still runs when the tool probes an input that exists. Unless --overwrite is passed, an existing output is refused (kind: input) before ffmpeg. An output that is the same file as an input is refused either way. No media file is written, and verified is false; --plan FILE does write the plan JSON. A path that is not on disk yet is not measured: the probe is a stub (0×0, duration 0), so a number taken from it is not a measurement. The measuring tools (probe, check, sync, multicam, scenes, cropdetect, report, silence, loudness, stabilize) still run their measurements; only the artifact is skipped, and silence with --filler --transcribe also runs the speech engine, which may download a model. overlay measures the lines of a multi-line --text with one drawtext on a generated frame on FFmpeg 8.0, 8.0.1 and 8.1.0, where it draws them one by one. verify accepts --dry-run and ignores it: its steps run. --plan FILE is that dry run written down — the planned argv, the command lines, and a fingerprint of each existing input (size, plus a sha256 of the first and last 8 MiB). render.py and verify.py refuse --plan. render.py FILE runs a plan only when those fingerprints still match (a mismatch is refused with each input's expected and actual fingerprint in error.details, and logged to <plan>.audit.jsonl), by running the tool again with the planned argv, not by executing the recorded ffmpeg lines; --dry-run on that run only prints them. doctor reports whether the filters, encoders and bitstream filters the contract names are in this build (ffmpeg -filters, -encoders, -bsfs) and which fonts are installed. A name in that listing is not a check of the graph this command would build, and a listed GPU encoder is not a successful encode.

Can it remove burned-in subtitles or logos?

A rectangle you already know, sitting still for the whole clip, can be filled from the picture around it with redact.py --mode delogo (ffmpeg's delogo filter). That is a 1 px border blend. It is not inpainting: a logo that moves, or burned-in subtitles whose position changes, is out of scope. The same known box can be obscured instead, with --mode blur or --mode pixelate. None of the three finds the box. delogo also needs the box at least 1 px inside the frame, and it only interpolates 8-bit YUV, so an HDR or 10-bit source is refused until color.py --to-sdr.

Does it auto-track faces or subjects for reframing?

fit.py --fit crop centres the crop unless you pass --crop-x and --crop-y. crop.py cuts the rectangle you pass. cropdetect.py measures letterbox bars, and --motion-centre reports where motion sat each second; it writes no file and picks no crop. sphere.py points a 360 view where you aim it. look.py writes a contact sheet. Nothing in this repository detects a face, a product or a subject. Choosing what to keep in frame is the caller's.

Does it encode on the GPU?

The encode path a tool will actually take is Apple VideoToolbox, for h264, hevc and prores, and only on Apple Silicon. --hw asks for it on that call. FFMPEG_SKILL_HW=1 makes it the default for every re-encoding tool except export.py's delivery presets, which take --hw on their own (or render.py --hw for a whole project). AV1 stays on SVT-AV1. nvenc, QSV, VAAPI and AMF are reported by doctor --json's gpu_encoders when the ffmpeg build was compiled with them, and no tool encodes with them. One build is the exception to opt-in: with no libx264 and no libx265, and with h264_videotoolbox or hevc_videotoolbox, those encodes use VideoToolbox without --hw and the result says hw.source is "auto". --no-hw still asks for the CPU encoder. A VideoToolbox job the hardware refuses is re-encoded on the CPU and the result says so (hw.fallback).

FFmpeg compatibility

The tools need FFmpeg 6.1 or later and Python 3.10 or later (standard library only). 3.0.0 removed FFmpeg 5.x and Python 3.9: every tool refuses an ffmpeg/ffprobe whose version reads as older than 6.1 (kind: missing_tool, error.reason: ffmpeg_unsupported; a git build whose version is not a release number is not refused), and doctor lists an unsupported FFmpeg or Python under unsupported with ok: false. What CI actually exercises on every pull request is FFmpeg 6.1 (Ubuntu 24.04 apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew), 9.x (Windows gyan.dev) and 8.0.1 (Ubuntu 26.04 apt), on Python 3.10 and 3.13 (the two ends of the supported range). The capability parser has been run against the listings of these builds:

FFmpeg 8 shortened the flag column of ffmpeg -filters. A parser anchored on the old width matches nothing on FFmpeg 8 and, if "nothing matched" is read as "nothing installed", reports every filter missing; that is what 0.9.0 did on macOS and Windows. Since 0.9.1 rows are recognised by their io-spec token (A->A, AA->A, |->V, N->N), so the flag width, the legend and the separator do not matter, and a listing that still cannot be read yields unknown rather than missing. The captured listings live in tests/fixtures/ with their provenance; CI uploads each runner's listing and doctor --json as an artifact so a new layout is visible before it bites.

Tested on real footage

What is tested where. The contract and the test suite (tests/test_contract.py, tests/test_all.py, which aggregates one module per tool group — test_analysis.py, test_editing.py, test_audio.py, test_picture.py, test_delivery.py, test_orchestration.py, test_accel.py, test_asr.py, test_cut_copy.py — over the shared footage in tests/_fixtures.py) run on Linux, macOS and Windows on every pull request, minus the handful of POSIX-shim tests listed under Development. The real-device media corpus (tests/corpus.py) has been run on Linux and macOS; the full corpus has not been run on Windows yet, and neither has an install by someone other than the maintainer been reproduced there — issue #143 tracks both. Treat the numbers below as measured on Linux (and, where stated, macOS), not as a claim about every file type on every OS.

python3 tests/corpus.py --fetch --verify     # ~1.4 GB download, then verify (slow on 4K)
python3 tests/bench_sync.py --cases 100
python3 tests/bench_silence.py
python3 tests/bench_scenes.py

Benchmarks live in tests/bench_*.py, agent evals in evals/, results by iteration in evals/results/.

A one-hour recording

Measured at 2.17.0 (2026-10-25) on one 60-minute 1080p30 H.264 file (4.3 GB, AAC mono 48 kHz, synthetic testsrc2 picture and a tone). The machine was a 4-vCPU Xeon at 2.1 GHz with FFmpeg 6.1.1 on Linux, and each tool ran alone. The analysis rows read the whole hour (silence.py, scenes.py and check.py report 3600 s). The edit and export rows used 10-minute segments cut from it with stream copy, and the last row is the whole hour.

A full-length re-encode of an hour does not fit in the default --timeout. The limit is 1800 s per ffmpeg call. On this machine export.py --preset youtube on the whole hour was killed at 1802 s with kind: timeout (exit 124), and nothing was written. At the 10-minute segment's rate it would have needed about 50 minutes. A whole-hour join.py would land at the limit. The error message names the fix. For a long master, pass --timeout 0 (no limit) or a larger value, or --fast, which at the measured rate takes about 16 minutes for the hour. Analysis tools and stream-copy cuts stay far below the limit.

Install

npx ffmpeg-skill              # Claude Code   → ~/.claude/skills/ffmpeg-skill
npx ffmpeg-skill --cursor     # Cursor        → ~/.cursor/skills/ffmpeg-skill
npx ffmpeg-skill --codex      # Codex         → ~/.agents/skills/ffmpeg-skill (Cursor reads this location too)
npx ffmpeg-skill --all        # all three
npx ffmpeg-skill --project    # this project  → ./.claude/skills/ffmpeg-skill
npx ffmpeg-skill --dir ./my-skills
npx ffmpeg-skill --uninstall  # remove from the selected targets (--codex also clears the older ~/.codex/skills location)

As a Claude Code plugin (no Node needed, updates with claude plugin update). This repository is its own plugin marketplace:

/plugin install ffmpeg-skill --marketplace kajisho5/ffmpeg-skill      # in Claude Code 2.1.275 or later
claude plugin marketplace add kajisho5/ffmpeg-skill                    # older versions: add the marketplace,
claude plugin install ffmpeg-skill@ffmpeg-skill                        # then install from it

The plugin namespaces the skill as ffmpeg-skill:ffmpeg-skill. The manifests are .claude-plugin/plugin.json, whose version follows every release automatically, and .claude-plugin/marketplace.json, which lists the plugin from the repository root. Before 2.17.1 the README's one-line claude plugin install kajisho5/ffmpeg-skill could not work, because there was no marketplace file.

Without Node: clone this repository and copy SKILL.md, package.json, scripts/, templates/, references/, docs/ and mcp/ into your agent's skills directory (the same set npx ffmpeg-skill installs; without templates/ no --template renders, and without package.json the contract reports its version as unknown).

After installing:

npx ffmpeg-skill doctor           # every required FFmpeg component present?
npx ffmpeg-skill contract --json  # what the agent framework will see

FFmpeg itself:

On macOS, ffmpeg-full is keg-only: Homebrew installs it without linking it, so after brew install ffmpeg-full the ffmpeg on PATH is still the lean ffmpeg formula (often present as a dependency of another formula), or no ffmpeg at all. If the ffmpeg on PATH is Homebrew's lean formula, the skill uses the ffmpeg-full of the same Homebrew prefix by itself (ffmpeg and ffprobe both, from opt/ffmpeg-full/bin; doctor says so, and doctor --json gives ffmpeg_path / ffmpeg_source); any other ffmpeg on PATH (a tap build, MacPorts, a static download) is used as it is. With no ffmpeg on PATH at all, or to make the whole shell use it, do one of two things:

• Put it first on PATH. Add export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH" to your shell profile. brew --prefix ffmpeg-full is the stable opt/ path, so this survives upgrades, but it only reaches processes started from a shell that read the profile.
• Link it over the lean formula: brew unlink ffmpeg 2>/dev/null; brew link --overwrite --force ffmpeg-full. Every process finds this one, but brew doctor warns about a linked keg-only formula, and an upgrade of the lean ffmpeg has been seen to link the lean build back on top without a message. After upgrading, check that command -v ffmpeg still resolves into ffmpeg-full, and re-run the link if it doesn't.

Requirements

• FFmpeg 6.1+ (3.0.0 removed 5.x; an older build is refused). Required by at least one tool (so doctor's ok needs them all): libx264, aac, and the drawtext, subtitles (libass), loudnorm, xfade, acrossfade, amix, overlay, scdet, silencedetect, cropdetect, tile, tpad, boxblur, hqdn3d, yadif, reverse, rotate, showwaves, v360, xstack and vidstabdetect/vidstabtransform (libvidstab, stabilize.py only) filters; doctor --json lists them as capabilities.required. Needed only by the flags that use them: libx265, prores_ks, libzimg / zscale, libmp3lame, libopus, libvorbis, the ass filter. doctor tells you which are present. The apt and gyan.dev builds carry all of them; some Homebrew bottles lack libass / libfreetype / libzimg, which doctor reports as missing.
• Python 3.10+, standard library only (3.0.0 removed 3.9)
• Node 16+ only for the npx installer

doctor's own introspection calls (ffmpeg -filters/-encoders/-bsfs/-version) time out after 10s and report failed rather than hanging forever — those are meant to be fast. Every tool's actual media-processing ffmpeg invocation (cut, fit, caption, ...) runs under --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT, 0 = none): past the limit the process is killed, its partial output removed, and the failure reported as kind: timeout (exit 124) — a legitimately long --accurate re-encode should raise the limit rather than run unbounded. -nostdin is always passed, so a hung ffmpeg process waiting on stdin cannot happen.

Stability

3.x keeps every tool name, CLI argument, JSON output key and exit code working: nothing is removed or renamed, and nothing optional becomes required, until 4.0. The full list of what is promised and what is not, and the three-step deprecation policy, is in docs/contract.md. It is enforced by a test that pins every tool's argument names against a snapshot, so a breaking change fails CI instead of slipping into a patch. 2.0.0 made the five changes announced since 1.10.0 -- --crf removed in favour of --quality (except on export.py, whose preset chooses the encoder), an existing output refused without --overwrite, probe's hdr narrowed to a real HDR signal, json/progress out of the MCP schema, the result_v2 preview withdrawn -- listed with what to change in docs/contract.md and under removed in contract --json. 3.0.0 is the second break: it removed FFmpeg 5.x and Python 3.9 (announced in 2.14.0 and 2.10.9), made cut.py keep an .mp4/.mov copy's edit list, keep an SDR HEVC source HEVC and use --vfr-guard sampled by default (--no-edit-list, --no-keep-hevc and --vfr-guard average restore 2.x), and changed what cut.py's precision (now the least exact segment's) and keyframe_snapped (now equal to start_snapped) mean (contract_version 2.0) -- see docs/contract.md.

Development

npm test                      # tests/run_parallel.py (test_all.py's end-to-end modules, sharded across the cores) + tests/test_contract.py
python3 tests/test_picture.py # one tool group on its own (analysis, editing, cut_copy, audio, picture, delivery, orchestration, accel, asr)
npm run release-check         # pack, install, contract from the installed copy, MCP == contract, doctor, tests, contract evals
npm run demo                  # python3 demos/build.py: synthetic footage -> every before/after demo + docs/demos/*.gif
npm run demo:pipeline         # examples/make_demo.sh: the older single end-to-end run of every script
python3 evals/run.py --list   # agent eval prompts (see evals/); regex-only grading, runnable from any agent harness -- see evals/README.md "Running this from Cursor, Codex, or another harness"
node bin/install.js --dir /tmp/skills   # try the installer without touching ~/.claude

CI (.github/workflows/ci.yml) runs on every pull request and on pushes to main, on Ubuntu (FFmpeg 6.1 with Python 3.10 on 24.04, FFmpeg 8.0.1 with Python 3.13 on 26.04), macOS (Homebrew FFmpeg 8.x) and Windows (gyan.dev FFmpeg 9.x), plus a Linux job on FFmpeg 7.1 (Debian trixie container), and uploads each runner's FFmpeg listings as an artifact.

tests/test_contract.py runs on all three OSes, but a handful of its tests build a fake ffmpeg as a #!/bin/sh script on a PATH shim to force specific FFmpeg 6/7/8/9 fixture layouts through doctor's parser — that technique isn't portable to Windows, so test_dry_run_never_runs_ffmpeg_and_writes_nothing and the whole DoctorDetectionTests class (fixture-driven layout parsing) are individually skipIf'd there and show as skipped, not silently absent, in the Windows job's log. Everything else — contract schema, reencodes_*, doctor.tools, MCP derivation, and every tool exercised through the contract, including cut.py's provenance fields — runs against the real Windows ffmpeg on every PR. See references/ci-platform-pitfalls.md for this and other per-OS behaviour differences already diagnosed, before spending a CI cycle re-diagnosing a platform-only failure.

Releasing is fully automated end to end, including the version number itself — a PR doesn't need to touch package.json, docs/contract.md, or CHANGELOG.md at all. Once a PR merges to main, .github/workflows/release.yml takes it from there: if nobody bumped the version by hand, it resolves the next version (.github/scripts/resolve_version.py) from the labels on every PR merged since the last tag (minor/feature/enhancement → minor, fix/bug/patch → patch, an unlabeled PR defaults to patch; a PR whose only labels are chore, ci, docs or dependencies is not releasable, so a merge that changes no shipped file releases nothing). Most PRs don't need a label added by hand: release-drafter.yml's autolabel job applies one automatically from the PR's title/changed files (Fix ... → fix, Add .../feat ... → feature, docs/.md/.github//build(deps) changes → chore) as soon as it's opened — add a label yourself only to override that. A major version is never chosen automatically: no label rule produces major, and the workflow refuses to auto-bump across a major boundary even if someone applies that label — a real major release is a deliberate package.json bump in a PR, which the manual path below already handles. It bumps package.json, .claude-plugin/plugin.json, docs/contract.md and docs/roadmap.md's released-version sentence, writes a CHANGELOG.md section listing those PRs (and any issues they closed), and pushes that commit to main itself. Either way — auto-bumped or hand-bumped in the PR — it then creates the vX.Y.Z tag, publishes a GitHub Release with notes extracted from CHANGELOG.md's matching section, and publishes the package to npm. A PR that still wants to write its own version bump and CHANGELOG.md prose (e.g. to explain the "why" of a release by hand) can — the automation only fills in when nobody made that call already. A push to main with nothing new to release is a no-op. npm publishing needs an NPM_TOKEN repo secret (an npm access token with publish rights on this package) — without it the tag and GitHub Release still happen, only the npm step is skipped. A repo that depends on this one (an editing skill, an agent) should pin an ffmpeg-skill version by tag or npm version, not by tracking main — a merged-but-not-yet-released commit on main can be ahead of the last published npm version for the few minutes between merge and this workflow completing.

Contributing a change: see CONTRIBUTING.md.

Docs

Support

If this skill saves you time, you can help keep it maintained through GitHub Sponsors. Issues and pull requests are just as welcome.

License

MIT