name: ffmpeg-skill description: 'Edit video and audio with local FFmpeg from natural-language requests: cut, trim, join, resize/reframe (9:16, 1:1), speed change, captions and subtitles (SRT/ASS, animated, karaoke), logos and text overlays, lower-thirds and titles, silence removal, multicam and external-mic sync, loudness normalisation, HDR/Dolby Vision to SDR, LUTs, background music with ducking, platform exports (YouTube, Reels, TikTok, X), compliance checks, scene detection and highlight reels, contact sheets to inspect results, and whole-edit project files. Use this skill whenever the user mentions a video or audio file (mp4, mov, mkv, wav, m4a), footage, a clip, captions, subtitles, a reel or short, YouTube/Instagram/TikTok delivery, LUFS, sync, transcoding, ffmpeg, or asks to make something "60 seconds", "vertical", "louder", "captioned" — even when they do not say "edit". Python 3.9 standard library only, no cloud, no API keys.'

ffmpeg-skill

Scripts live in scripts/ next to this file; run them with python3 <skill-dir>/scripts/<name>.py, and delivery templates in templates/. This file is enough to do a job: the table below routes the request, and --help on the script about to run is the cheapest full flag list. A reference file costs as much as this one; open one only for a question you have: references/scripts.md (every flag of all 42 scripts), references/devices.md (iPhone HDR, GoPro, DJI, screen recordings, Zoom), references/gotchas.md (the long form of the one-line rules at the end). MCP: tools/list shows only the core 12 by default; the other 30 (per this table) stay callable by name via tools/call, described by contract --json; set FFMPEG_SKILL_MCP_FULL=1 for all 42.

Shared flags (every script): --dry-run; --json (output path, its probe, the commands run); --json-brief (status/output/verified + a summary; prefer on writing steps); --fast (preview quality); --progress (percent/ETA); --timeout SECONDS (kind: timeout, default 1800); --overwrite (step 7); --plan FILE (a dry run render.py FILE runs later; refuses if an input changed). Re-encoding tools also take --hw (Apple Silicon GPU, big files; FFMPEG_SKILL_HW=1 = default, not export), --codec h264|hevc|av1|prores and --quality N: unset, SDR is x264 (cut.py --keep-hevc: HEVC source stays HEVC), HDR is x265 Main10; prores needs -o NAME.mov, h264 refuses HDR (color.py --to-sdr first).

Writing tools run nothing under --dry-run; the measuring tools (probe, check, sync, multicam, scenes, cropdetect, report, silence, loudness, stabilize) may still run ffmpeg/ffprobe, skipping artifacts/side files (--edl, --sheet, a generated .ass); verify ignores the flag. Per tool: contract --json dry_run.

Workflow (in this order)

0. Environment, only on failure. Never start a job with doctor: a broken machine fails with kind: missing_tool or an ffmpeg error naming the filter/encoder. Run python3 <skill-dir>/scripts/_contract.py doctor (or npx ffmpeg-skill doctor) after such a failure, or when asked what the machine can do: read ok/usable, report the missing capability. contract --json's tool schema is for a planning agent, not this workflow.
1. Probe what you must plan from. Run probe.py on each input you plan from — duration, fps, resolution, codecs, channels, variable_frame_rate_suspected — and whenever the user asks about a file. No separate probe before every edit: every writing tool's --json already carries its input and a probe of the output. Plan from real numbers, never assumptions.
2. Prefer lossless. If the request can be met without re-encoding (plain cuts on keyframes, remuxing, audio-only changes), do not re-encode. cut.py and loudness.py stream-copy video by default; --accurate on cut.py only for frame-exact cuts.
3. Plan with --dry-run --json, then execute. Trust --json, not a dry run's summary line, for any number in the plan (a dimension there can be a placeholder). Use before long encodes, to report facts. Never point -o at a file you did not create in this job unless the user asked for it to be replaced; pass --overwrite only then.
4. Chain in a sensible order. A delivery request with no other editing is one template run (render.py --template NAME INPUT), not a hand-built chain. Otherwise: colour (HDR→SDR / LUT) → cut → join → silence → fit → caption/overlay → sync → audio → loudness → export. Frame changes before captions, so text is sized for the final frame. Re-encode as few times as possible: intermediates at CRF 18, export.py last. Three or more steps: render.py with a project.json.
5. Check the deliverable. Before reporting, run check.py OUTPUT --platform X for the destination named (a template run already does). Format rows (codec, pixel format, size, true peak, colour tags, VFR) are safe to fix. Judgement rows change content: duration (cut loses material), aspect (crop loses edges), fps (drops motion), loudness (ambience must not be boosted) — fix only when the request implies the answer, else state the choice and its cost. Mention WARNs; do not chase them.
6. Verify the output. Confirm duration, resolution, fps and audio match the request, from the writing tool's --json/--json-brief probe or probe.py, and report those numbers ("final.mp4: 59.98 s, 1080x1920, 30 fps, AAC stereo"). A step is done only when the script exited 0 and the output probes as expected: a non-zero exit, a missing or empty file, or a probe that contradicts the request is a failure reported with the script's error message.
7. Keep the user's originals. Never overwrite the source; write new files next to input or where asked. An existing output path is refused (kind: input); --overwrite is the one way to say "yes, replace it".
8. Look at the picture. Whenever the picture changed (captions, overlays, graphics, crop/pad, resize, colour, transitions, a join.py scaling a clip to the first clip's frame, color.py --to-sdr) run look.py OUTPUT --tiles 3x2 (or --at T for one frame) and view the PNG (4x3 for whole-clip layout). Not finished until Look: names that PNG — a probe cannot see a caption on a face. Audio-only: Look: not needed. What to look for splits like check.py's rows in step 5:
   • Mechanical (this skill's own job to verify and report): the specified text/logo is at the specified position, subtitles appear at the specified timestamps, dimensions are even. Letterboxing from fit.py --fit pad is the correct result of that mode, never a defect to flag.
   • Judgement (report it, don't silently pass or fail): whether a subject or face is cut off, text sits over a face, colours look washed out, a transition lands. These need deciding what the subject is, the calling agent's call — say what you see in one line; they judge. With no vision capability, write Look: PATH (pixels not inspected; agent has no image view) — never claim a picture was inspected when it wasn't, without stalling for a capability that isn't there.

Before you run anything: what to ask, what to assume

Ask a short question only when the answer changes the output materially and the request does not imply it. When several things are open at once (a vague "make it for social media" leaves destination, aspect, length and captions open), don't ask one per turn: propose one bundle with your defaults and let the user change any part ("Reels: 9:16 padded, 60 s, -14 LUFS, no captions — OK?"). One question, one answer, then the run. Never ask for what probe.py can tell you.

• Destination decides aspect, length limit, loudness and codec; "for Reels" answers all four and names a template. No destination and a plain cut/caption: keep the source format and say so. If the user says "export", "post" or "deliver", ask where.
• Duration ("make it 60 s") without a method: speed up for ≤1.5× changes, trim otherwise, say which. Ask when the content is a talk (trimming loses words) and the change is large.
• Captions without a text source: --transcribe if a local engine exists, else ask for the text or a timed file; never invent dialogue.
• Fonts and brand: if the user mentions a brand, colours or "our font", ask for or create brand.json once, reuse it.
• CJK / non-Latin text: let the tool pick the font by script (--font turns it off); --lang ja|ko for Han-only text. doctor --json .fonts.scripts says what renders here. Tofu is a failed job.
• Crop position for --fit crop: centre by default, but when the request or the source names an off-centre subject ("keep the product on the right", someone visibly off-centre in the sheet) use --crop-x/--crop-y (0=left/top, 1=right/bottom) instead of guessing centre, or ask which edge to keep.
• Anything else (transition type, caption style): pick the conventional default, say what you picked, offer the alternative in one line.

What this skill does and does not decide

This skill cuts, joins, measures, syncs, exports and checks files — it executes an edit, it does not decide one. What belongs to the human, the calling agent or another skill:

• Which cut is right, or whether a deliverable is approvable — this skill measures and reports (check.py's PASS/WARN/FAIL, cut.py's duration error); the user or production agent decides whether that ships.
• What makes a highlight interesting — scenes.py --highlights ranks by a measured proxy (audio energy, duration): candidates, not a verdict.
• Thumbnail or cover composition — a design decision, not measurement.
• Understanding what a video is about — there is no vision here beyond look.py's contact sheets, for the calling agent's eyes, not for this skill to interpret.
• Judging what looks good — "apply this LUT", "correct exposure by +0.3 stops" (color.py) is mechanical; "grade this scene to look cinematic" belongs to a colour-grading skill (color-grading-skill) that decides the parameters, then calls color.py.
• The words in a caption — cue text is burned as written. Too long for the frame means a smaller size, --max-lines, or the user's own edit; never rewrite, shorten or paraphrase it, even when asked to "make it fit" — say so, offer --max-lines 1 at a smaller size.
• Picking a subject or region you were not given — "crop to x=200,y=0" is mechanical once the box is known; "crop to keep the speaker in frame" needs deciding what the speaker is, a judgement for the calling agent (from a look.py sheet).

The line: same input + same explicit parameters always producing the same verifiable output belongs here; anything depending on taste, understanding or what looks or sounds good belongs to whoever makes that judgement.

If a request needs an FFmpeg feature none of the 42 scripts expose, say so and name the closest built-in option — never guess a raw ffmpeg/ffprobe invocation outside scripts/*.py. It bypasses every guarantee this skill makes, so it is never a fallback.

Request → script

This table and doctor --json's tools list are the source of truth for what exists: name only a script you have seen in one of them (there is no doctor.py, no trim.py, no subtitle.py).

Timestamp flags (--start, --end, --at, --from, --duration, --offset, and the times in cue and chapter files) take seconds, mm:ss(.fff), hh:mm:ss(.fff) or SMPTE hh:mm:ss:ff with @fps (00:01:02:15@29.97) — paste an NLE cue sheet as-is; length flags (--min-silence, --margin, --fade) are plain seconds.

Audio-only files

Audio is a first-class input: probe, cut, silence, loudness, audio, sync, check --platform podcast, render --template podcast take WAV, FLAC, MP3, M4A/AAC, OGG, Opus; output extension picks the format. Scripts needing a picture (fit, caption, overlay, graphics, color, export, scenes, look) refuse audio with "input has no video stream" — don't force a video wrapper. Recipes: references/gotchas.md#audio-only-files.

Report format

Reply in the language the request is written in — subtitles in another language are still reported in the request's language. Keep the labels (Done:, Steps:, Check:, Look:, Notes:) in English; everything else is the user's language. Never drift because the job was short or failed: even a one-line "file does not exist". A mid-conversation switch follows the user's latest message.

Finish every job with this shape (numbers from --json or probe.py/check.py, not memory):

Done: final.mp4 — 59.98 s, 1080x1920, 30 fps, H.264, AAC stereo, -14.1 LUFS
Steps: cut 0:12-1:12 (lossless) -> fit 9:16 crop -> captions (pop, karaoke) -> loudness -14 -> export reels
Check: reels — all 12 checks pass (verified: true)
Look: final_sheet.png (captions inside the safe area, logo top-right)
Notes: source was VFR, conformed to 30 fps; audio was mono, made stereo

The same five lines for a Japanese request:

Done: final.mp4 — 59.98 秒、1080x1920、30 fps、H.264、AAC ステレオ、-14.1 LUFS
Steps: 0:12-1:12 をカット（無劣化）-> 9:16 にクロップ -> 字幕（ポップ、カラオケ）-> ラウドネス -14 -> Reels 書き出し
Check: reels — 12 項目すべて合格（verified: true）
Look: final_sheet.png（字幕はセーフエリア内、ロゴは右上）
Notes: 元は VFR だったので 30 fps に揃えた。音声はモノラルだったのでステレオにした

Keep it to those five lines plus anything the user must decide. Never report success without the output probe; never describe a fix you did not run.

When a step fails, replace Done: with Failed: and keep the rest honest:

Failed: color.py --lut grade.cube exited 1 — ffmpeg: "Unable to parse LUT file" (the .cube is not a valid LUT)
Steps: probe -> color (failed); nothing written
Check: nothing to verify
Look: not needed
Notes: send a valid .cube, or say if you want the clip left as is

Those filler lines are sentences, not labels: the same report for a Japanese request ends Check: 検証するものなし / Look: 不要.

A refusal uses the same shape: Failed: names what was refused and why, Steps: lists what did run, Look: not needed. The shortest failure gets all five labels, never headings. A partial result is Done: with the shortfall in Notes:; a refusal that still delivers something is Failed: — never a third label like Done (partially):. Quote a failure's error.hint in Notes: — the flag change a retry needs.

Every script prints {"status": "failed", "error": {"kind": input | ffmpeg | output | missing_tool | timeout | verification | interrupted, "message": ...}} with --json and exits non-zero; quote the message, never paraphrase it.

Things that look right but are wrong

One line each; open the linked references/gotchas.md section when the job is in that area.

• HDR (iPhone, HDR10) re-encoded through an SDR path goes flat; the scripts keep HDR; hdr: true is a real PQ/HLG/DV signal, bt2020_or_hdr: true also BT.2020 SDR. -> #hdr-and-colour
• Log footage (S-Log/V-Log/C-Log) is tagged SDR and looks grey: probe.py --analyze, then color.py --lut first. -> #log-footage
• A -c copy cut can start on a wrong/frozen frame; cut.py re-encodes past a 0.5 s snap, respect it; --edit-list hides an .mp4's pre-roll. -> #keyframe-cuts
• VFR phone/screen clips: re-encodes go CFR; cut.py re-encodes (--vfr-guard sampled: only measured VFR); odd rate: fit.py --fps. -> #variable-frame-rate
• Sync/multicam confidence under 0.3 (or a huge offset) is suspect — check every camera; these align audio, never lip sync. -> #sync-multicam-and-drift
• "Normalised" audio can still clip (check true peak); ambience at -40 LUFS or below must never be raised to a speech target. -> #loudness-and-ambience
• Captions burned before a crop/resize land off-frame; burned small then upscaled by export.py come out soft. -> #captions-fonts-and-text-order
• Emoji need --emoji-assets DIR (a PNG per glyph) to render in colour; without it they come out monochrome, reported. -> #emoji
• Non-Latin text picks a font by script (graphics.py shapes Devanagari, Bengali, Tamil, Thai via libass; drawtext cannot); no font = failed job. -> #fonts-by-script
• --fit crop 16:9→9:16 throws away 70% of the width; "60 seconds" by speed or by trim are different answers — say which and why. -> #reframing-fps-and-duration
• TikTok/Reels cover the bottom fifth and right column with their own UI — templates keep text out of those zones; look.py --safe tiktok shows them. -> #platform-safe-zones
• scenes.py --highlights ranks by loudness (or duration), never by meaning: check the sheet before trusting picks. -> #highlights
• CPU re-encodes: x264 medium; chain 3+ in one render.py project. -> #chaining-and-speed

npx ffmpeg-skill

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

Quick start

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

Deliver to a platform

One command per destination, with the app's own UI taken int