{"slug": "ffmpeg-skill-local-video-editing-mcp-for-claude-code-cursor-and-codex", "title": "ffmpeg-skill: Local Video Editing MCP for Claude Code, Cursor and Codex", "summary": "The open-source kajisho5/ffmpeg-skill repository had 6,158 GitHub stars as of November 16, 2026, offering coding agents 42 FFmpeg-backed Python tools plus an MCP server for local video editing inside Claude Code, Cursor and Codex with no cloud upload or API keys. The skill enforces a probe-edit-verify workflow, exposes tool schemas via `contract --json` generated from argparse, and installs through `npx ffmpeg-skill` with `--cursor`, `--codex` or `--all` flags. Its author documents the design in a Zenodo position paper (DOI 10.5281/zenodo.23720216) and acknowledges the skill does not yet fully meet its own verification ideal.", "body_md": "**ffmpeg-skill gives coding agents a local video department: 42 FFmpeg-backed Python tools, an MCP server, and a probe-edit-verify discipline — with no cloud upload and no API keys.** The [kajisho5/ffmpeg-skill](https://github.com/kajisho5/ffmpeg-skill?ref=explainx) repository listed **6,158 GitHub stars** when we fetched it on **November 16, 2026**.\n\nIf you already use **[cinecode for generative films](https://explainx.ai/blog/cinecode-claude-code-skill-films-from-code-three-js-ffmpeg-mit-github-trending-2026)**, think of ffmpeg-skill as the **operator bench** for real footage: cuts, captions, loudness, reframes, and **TikTok or YouTube export presets** agents can verify before they say \"done.\"\n\n## TL;DR\n\n| Piece | What it does | \n|---|---|\n| **SKILL.md** | Maps user requests → scripts; enforces probe → edit → verify reporting | \n| **42 tools** | cut, join, captions, loudness, scenes, render templates, batch, etc. | \n| **contract --json** | Schemas generated from argparse — CI blocks drift | \n| **MCP** | `mcp/server.py` exposes tools/list derived from contract | \n| **Install** | `npx ffmpeg-skill` (+`--cursor` ,`--codex` , or`--all` ) | \n\n## Why agents need a video skill — not raw FFmpeg\n\nAgents that \"know FFmpeg\" still **hallucinate frame rates**, pick **codecs containers reject**, and **re-encode** when **stream copy** would work. ffmpeg-skill's README states the fix plainly: **probe first**, **structured tools**, **contract**, **verification**.\n\nThat mirrors **[Plannotator's human-in-the-loop review](https://explainx.ai/blog/plannotator-plan-code-review-workspace-coding-agents-claude-code-codex-github-trending-2026)** for plans, but for **pixels and loudness**.\n\nThe author documents the design in a **Zenodo position paper** (DOI [10.5281/zenodo.23720216](https://doi.org/10.5281/zenodo.23720216?ref=explainx)) and notes the skill **does not yet fully meet its own verification ideal** — honest scope for adopters.\n\n## Quick start\n\nPrerequisites: **ffmpeg** on PATH (README shows `sudo apt install ffmpeg` on Debian).\n\n```\nnpx ffmpeg-skill\nnpx ffmpeg-skill doctor\nnpx ffmpeg-skill contract --json | head -40\n```\n\nRe-run **`npx ffmpeg-skill`** to refresh `~/.claude/skills/ffmpeg-skill`; copies do not auto-update.\n\nOptional captions from speech need a **local ASR** (`pip install faster-whisper` is the simplest path per README). Audio never uploads; models download on first run.\n\n## Workflow the skill enforces\n\nCream scissors trim a short green section from a filmstrip — the probe-then-cut loop ffmpeg-skill asks agents to follow\n\n1. **`probe.py`** — duration, fps, HDR, rotation, audio layout.\n2. **Edit tools** — prefer**lossless stream copy** when filters are not required (`cut.py` , parts of`loudness.py` ).\n3. **`--dry-run` / `--plan`** — print ffmpeg lines or save a fingerprinted plan for` render.py` .\n4. **Verify** — probe output,`check.py` against platform specs,**`look.py` contact sheets** when pixels change.\n\nAgents must end reports with **`Done:`** or **` Failed:`** per SKILL rules — no invented partial states.\n\n## Tool surface (selected)\n\nThe README groups **42 public tools**. Highlights for builders:\n\n| Category | Examples | \n|---|---|\n| **Analysis** | `probe.py` ,`scenes.py` (cuts, peaks, beats — ranking is proxy-based, not semantic) | \n| **Editing** | `cut.py` ,`join.py` ,`silence.py` ,`fit.py` ,`reframe.py` | \n| **Captions** | `caption.py` with karaoke and animation modes | \n| **Delivery** | `export.py` presets, `render.py --template tiktok | \n| **Audio** | `loudness.py` (-14 LUFS targets), noise reduction, dynamics | \n| **QC** | `check.py --platform` ,`metadata.py` ,`verify.py` orchestration | \n\n**render.py** can emit a **multi-platform pack** (`--template all`) — useful for shorts workflows next to **[Seedance video APIs](https://explainx.ai/blog/seedance-2-5-bytedance-30-second-4k-ai-video-2026)** where you still need **mechanical compliance** (loudness, aspect, safe zones).\n\n## MCP integration\n\nA tower with a green beacon linked to small boxes — how MCP exposes ffmpeg-skill tools to Claude Code, Cursor and Codex\n\n`mcp/server.py` implements JSON-RPC stdio. **`tools/list`** schemas are **generated at startup from argparse**, so new flags cannot desync MCP silently — a regression test copies the repo and mutates scripts to prove it.\n\nDefault **`tools/list` exposes 12 core tools** to protect context windows. Set **`FFMPEG_SKILL_MCP_FULL=1`** to advertise all **42**.\n\nSame pattern as **[Google Stitch Skills MCP](https://explainx.ai/blog/google-stitch-skills-agent-skills-mcp-claude-code-cursor-install-2026)**: contract-first, host-agnostic.\n\n## Ecosystem note (optional brain layer)\n\nThe README positions **ffmpeg-skill as \"hands\"** in kajisho5's wider video stack — **`video-production-agent`** and **` remotion-ffmpeg-skill`** sit above as planners. This repo **does not call upstream**; dependency is one-way. Standalone adopters can ignore the ecosystem block.\n\n## Security and privacy\n\n- **Local-only video** — good for**NDA footage** and**pre-release game capture** unlike cloud editors.\n- **ASR models** download from Hugging Face or whisper.cpp hosts on first transcribe — air-gap if needed.\n- **No shell injection** — tools use typed argparse, not arbitrary filter strings from the model.\n\nFor agent misuse (destructive batch deletes), combine with **[human approval workflows](https://explainx.ai/blog/plannotator-plan-code-review-workspace-coding-agents-claude-code-codex-github-trending-2026)** — the skill verifies **technical** output, not **editorial** intent.\n\n## Compared to cinecode and Cursor FFmpeg credits\n\n| Tool | Best for | \n|---|---|\n| **ffmpeg-skill** | Operator edits on existing video inside agent sessions | \n| **[cinecode](https://explainx.ai/blog/cinecode-claude-code-skill-films-from-code-three-js-ffmpeg-mit-github-trending-2026)** | Procedural films from code | \n| **[Cursor FFmpeg credits](https://explainx.ai/blog/cursor-ai-ffmpeg-developers-free-credits-2026)** | Sponsorship for upstream FFmpeg devs, not agent tooling | \n\n## Caption, karaoke, and accessibility workflows\n\n`caption.py` burns user-supplied cue text — the README promises it **never rewrites** lines to fit timing. That is important for **legal and marketing review**: agents cannot silently soften claims in supers.\n\nAnimation modes (`--animate pop`, karaoke styles in README demos) pair with **` fit.py --aspect 9:16`** for vertical social delivery. When captions must meet **WCAG contrast**, run `look.py` and inspect PNGs yourself; the skill does not auto-score contrast ratios.\n\nFor multilingual pipelines, feed SRT or VTT you already audited; optional `--transcribe` stays **on-device** with faster-whisper or parakeet-mlx per README install lines.\n\n## Cost comparison versus cloud video APIs\n\nCloud editors charge **per minute rendered** and often retain **content on their servers**. ffmpeg-skill's economic model is **cap-ex on CPU** you already own:\n\n- **Pros** — predictable cost at scale, NDA-safe footage, scriptable QC.\n- **Cons** — you maintain ffmpeg builds, ASR models, and agent guardrails.\n\nIf your product mixes **generative inserts** and **human A-roll**, use generative APIs for B-roll only, then pass through ffmpeg-skill for **loudness, captions, and platform compliance** — the division of labor [cinecode](https://explainx.ai/blog/cinecode-claude-code-skill-films-from-code-three-js-ffmpeg-mit-github-trending-2026) and ffmpeg-skill were designed for.\n\n## When to adopt\n\nAdopt ffmpeg-skill if your agent routinely:\n\n- Produces **Shorts/Reels** variants from one master clip.\n- Needs **LUFS normalization** before upload.\n- Must prove **9:16 reframes** with contact sheets.\n- Runs **offline** on laptops without GPU video APIs.\n\nSkip it if you only need **generative video** — use **[fal or BytePlus video models](https://explainx.ai/blog/seedance-2-5-flash-byteplus-0-152-per-second-claimed-vs-verified-2026)** instead.\n\n## Platform export templates explained\n\n`render.py --list-templates` advertises presets such as **tiktok**, **reels**, **shorts**, **youtube-shorts**, **youtube**, **x**, **linkedin**, **facebook**, **podcast**, and **audiogram**. Each JSON template encodes:\n\n- **Target aspect ratio** (for example 9:16 crop with safe zones)\n- **Caption placement** above platform chrome (TikTok description bar called out in README demos)\n- **Loudness targets** (for example −14 LUFS integrated)\n- **`check.py --platform`** validation after render\n\nThe README's demo gallery (`npm run demo`) rebuilds **before/after frames** via `python3 demos/build.py`, using synthetic FFmpeg sources — proof the scripts are **reproducible**, not cherry-picked stills.\n\n| Platform preset | Typical agent task | \n|---|---|\n| **tiktok / reels / shorts** | Crop talking-head to vertical, pop captions | \n| **youtube** | 16:9 deliverable with broadcast safe guides in `look.py` | \n| **podcast / audiogram** | Audio-first exports when video is static waveform | \n| **linkedin / x / facebook** | Corporate talking clips with conservative loudness | \n\nPair exports with **[Seedance-generated B-roll](https://explainx.ai/blog/seedance-2-5-bytedance-30-second-4k-ai-video-2026)** only after you **probe** generative files — AI video often ships variable frame rate or odd color tags `probe.py` must measure.\n\n## Silent removal, fillers, and podcast cleanup\n\n`silence.py` removes dead air; with **`--transcribe`** it can align cuts to speech (optional local ASR). **`--filler`** modes target verbal fillers when transcript timing exists. For interview podcasts, the README recommends measuring **sentence-level silences** with `--sentence-min-silence` — tunable margins matter because aggressive silence stripping sounds robotic on Zoom recordings.\n\nAgents should run **`--dry-run` first** and attach **`look.py` sheets** when the video track changes — audio-only jobs explicitly end with **Look: not needed** per SKILL reporting rules.\n\n## Multicam, sync drift, and HDR\n\nAdvanced tools include **multicam switching**, **audio drift correction**, and **HDR → SDR** with LUT support. `doctor` lists whether your ffmpeg build exposes **zscale**, **libass**, and **loudnorm** — Homebrew defaults sometimes lack subtitles filters, producing **`missing`** not **` unknown`** in capability tables.\n\nIf `doctor` reports **unknown** for a filter listing, treat the host as **untrusted for production** until you install a full ffmpeg build (static builds from upstream are the usual fix on macOS).\n\n## Batch folders and CI\n\n`batch.py` walks directories with consistent operations — useful when an agent generates **hundreds of UGC variants**. Combine with **`--plan`** files so CI replays the exact ffmpeg graph later; plans **fingerprint inputs** and refuse stale reruns if source media changed.\n\nFor GitHub Actions, mount ffmpeg once in the runner image, run `npx ffmpeg-skill doctor` in a setup step, and cap parallelism — ffmpeg is CPU-heavy and agents may spawn concurrent tools unless you throttle MCP calls.\n\n## SPEC contract discipline\n\nThe README's **SPEC (Self-Producing Execution Contract)** promise matters for MCP users: **input_schema** is generated from argparse at runtime, and CI fails if schemas drift. That is stricter than ad-hoc \"tool JSON\" many agent demos ship. When you add a wrapper skill on top, **do not duplicate schemas** — call `npx ffmpeg-skill contract --json` and ingest it.\n\n## Installing across Claude Code, Cursor, and Codex\n\n```\nnpx ffmpeg-skill --all\n```\n\nlays skill copies for each host. Re-run after upgrades so MCP `tools/list` schemas refresh. IT should ship **libass-enabled ffmpeg** on agent laptops used for caption workflows.\n\nSKILL.md requires agent reports to end with **`Done:`** or **` Failed:`**, JSON probes, and **` Look:`** paths when pixels change — add that rule to your AGENTS.md or agents skip verification.\n\nFor workshop teams comparing agent stacks, ffmpeg-skill is a useful **shared homework assignment**: give every attendee the same master clip, let Claude Code and Cursor each run `npx ffmpeg-skill`, and compare LUFS and contact sheets. The exercise surfaces host differences faster than abstract benchmark slides, and it mirrors how we teach verification in live **[AI workshops](https://explainx.ai/workshops)** without uploading client media to the cloud. Bring your own ffmpeg build so everyone measures the same loudnorm filter chain locally.\n\n*Tool count, MCP defaults, and Zenodo paper reference match kajisho5/ffmpeg-skill README November 16, 2026.*", "url": "https://wpnews.pro/news/ffmpeg-skill-local-video-editing-mcp-for-claude-code-cursor-and-codex", "canonical_source": "https://explainx.ai/blog/ffmpeg-skill-local-video-mcp-coding-agents-github-trending-2026?utm_source=rss&utm_medium=feed&utm_campaign=blog", "published_at": "2026-11-16 00:00:00+00:00", "updated_at": "2026-11-16 14:22:48.972892+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "agent-protocols", "developer-tools", "artificial-intelligence"], "entities": ["ffmpeg-skill", "kajisho5", "Claude Code", "Cursor", "Codex", "FFmpeg", "Zenodo", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/ffmpeg-skill-local-video-editing-mcp-for-claude-code-cursor-and-codex", "markdown": "https://wpnews.pro/news/ffmpeg-skill-local-video-editing-mcp-for-claude-code-cursor-and-codex.md", "text": "https://wpnews.pro/news/ffmpeg-skill-local-video-editing-mcp-for-claude-code-cursor-and-codex.txt", "jsonld": "https://wpnews.pro/news/ffmpeg-skill-local-video-editing-mcp-for-claude-code-cursor-and-codex.jsonld"}}