kajisho5/ffmpeg-skill

Give your coding agent a video editor.
Claude Code, Cursor, Codex or any MCP client edits your footage with local FFmpeg, then checks its own output.
No cloud · No API keys · Python standard library

Quick start · Demos · Tools · MCP · npm

npx ffmpeg-skill

caption.py --animate pop --karaoke	fit.py --aspect 9:16 --fit crop
silence.py --threshold -35	loudness.py -I -14 --tp -1

Left half is the input, right half is what the command produced. All 53 before/after demos, 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, 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 · FFmpeg compatibility · Tested on real footage · Install · Requirements · Development · Docs

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

# 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

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: no are different signals: ok means nothing required by every tool is missing, but a plain Homebrew ffmpeg on macOS can still be ok while caption.py specifically can't run (no subtitles filter) — 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.

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 and podcast; --template all (or a comma-separated list) renders every destination 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).

flowchart TD
    U[User request] --> A[AI agent<br/>Claude Code · Cursor · Codex]
    A -->|reads| S[SKILL.md<br/>workflow, request → tool map, report format]
    A -->|runs| T[Structured tool<br/>scripts/&lt;name&gt;.py, typed argparse flags]
    T --> C[Contract<br/>input schema · role · capabilities · verification policy]
    C --> D[Capability detection<br/>doctor: available / missing / unknown]
    D --> F[FFmpeg execution<br/>no shell, stream copy when possible]
    F --> V[Verification<br/>probe · check · look.py contact sheet]
    V --> R[Structured result<br/>--json: status, output, commands, probe]
    R --> A

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

flowchart LR
    M[MCP client<br/>Claude Desktop · Cursor · any client] --> P[mcp/server.py<br/>stdio JSON-RPC]
    P -->|tools/list| C[Contract-derived ToolSpecs<br/>names · order · inputSchema]
    P -->|tools/call| T[scripts/&lt;name&gt;.py]
    C -.derived from.-> K[scripts/_contract.py]
    T -.described by.-> K

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.

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, join.py and loudness.py stream-copy what they do not need to touch. 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.

42 public tools, all Python 3.9 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 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.

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.

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.

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 (1.10): what 2.0.0 removes, since when, the replacement and the surface it lives on. docs/contract.md "What 2.0 changes" is written from it.

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": …}}), 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.

{"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.

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

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, th, ru, el) 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).

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 switches to frame-accurate mode on it, because copy-cuts on VFR land on the wrong frame, and samples the frame timing to say whether that was needed (--vfr-guard sampled decides on the sample instead; --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. For a single .mp4/.mov cut, --edit-list keeps the copy and starts the picture where asked: the keyframe's pre-roll is stored but hidden by an MP4 edit list, which a player that ignores edit lists shows.
• 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. 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; 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, before anything runs); pass --overwrite where a replacement is intended.
• 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.

The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only). What CI actually exercises on every pull request is FFmpeg 5.1.1 (static build), 6.1 (Ubuntu apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew) and 9.x (Windows gyan.dev), on Python 3.9 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.

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

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):

claude plugin install kajisho5/ffmpeg-skill

The plugin namespaces the skill as ffmpeg-skill:ffmpeg-skill; the manifest is .claude-plugin/plugin.json and its version follows every release automatically.

Without Node: clone this repository and copy SKILL.md, scripts/, references/ and mcp/ into your agent's skills directory.

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.

• FFmpeg 5.0+. Always required: libx264, aac, and the drawtext, subtitles (libass), loudnorm, xfade, acrossfade, scdet, silencedetect and tile filters. 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.9+, standard library only
• 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.

2.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 3.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, 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.

npm test                      # tests/test_all.py (end-to-end incl. VFR, rotated, 5.1, HDR10, drifting sources) + tests/test_contract.py
python3 tests/test_picture.py # one tool group on its own (analysis, editing, audio, picture, delivery, orchestration)
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, Python 3.9 and 3.13), macOS (Homebrew FFmpeg 8.x) and Windows (gyan.dev FFmpeg 9.x), plus two Linux jobs on FFmpeg 5.1.1 (static build) and 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 and docs/contract.md, 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.

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

MIT