ffmpeg-skill: A local 42-tool video editor for coding agents
A local video editor for Claude Code, Cursor, and Codex that replaces hand-written commands with 42 structured FFmpeg tools.
GitHub kajisho5/ffmpeg-skill Updated 2026-11-17 Branch main Stars 6.7K Forks 601
Python FFmpeg MCP Claude Code Cursor Codex Video editing Local processing

🧭 Decision Guide

Try it if you

  • You process local video in Claude Code, Cursor, or Codex and want the agent to inspect real media properties first.
    The README's Why section states that every job starts with probe.py and decisions use duration, fps, resolution, colour, and audio layout.
  • Your MCP client needs tool parameters synchronized from argparse instead of maintaining a second schema.
    The README's What is SPEC? section says input_schema is generated at runtime from the argparse parser, and tests/test_contract.py checks for drift.
  • You need ready-made video operations such as captions, silence removal, loudness, or platform export instead of composing shell strings directly.
    The README lists caption.py, silence.py, loudness.py, export.py, and 42 tools, and says operations use typed arguments.
  • You need a smaller default MCP tool list while retaining name-based access to the full tool set.
    The README FAQ says tools/list advertises 12 core tools by default, the other 30 are callable by name through tools/call, and FFMPEG_SKILL_MCP_FULL=1 lists all 42.

Skip it if you

  • Your workflow requires cloud video processing or uploading audio for transcription.
    The README's Local first section explicitly says No cloud and No API keys, and says the transcription engine runs locally without uploading audio.
  • You need to pass arbitrary filter_complex or raw FFmpeg shell strings to the caller.
    The README's Why section says tools do not run through a shell and do not accept a filter graph from the caller.
  • Your deployment environment does not have ffmpeg or python3 on PATH.
    The README states, “If ffmpeg and python3 are on your PATH, it works”.
  • You require automatic face or subject tracking for reframing.
    The README lists “Does it auto-track faces or subjects for reframing?” as an FAQ, but the supplied material does not state that this capability is supported.

Requirements

  • The README Quick start requires FFmpeg first; for example, Ubuntu/Debian uses sudo apt install ffmpeg.
  • The README requires ffmpeg and python3 to be on PATH.
  • The installation entry point is npx ffmpeg-skill; the README Quick start also provides npx ffmpeg-skill doctor.
  • Local transcription is optional; caption.py --transcribe or silence.py --transcribe requires an installed Parakeet or whisper engine.
  • parakeet-mlx, faster-whisper, and openai-whisper download model weights on first use; the README gives whisper.cpp's large-v3-turbo as an example.

First step (verbatim from README)

npx ffmpeg-skill

Watch out

  • When running stabilize.py, do not omit the transforms file generated by the first pass, because the second pass needs it.
    The README FAQ says stabilize.py uses two passes and the second pass needs the first pass's transforms file.
  • For HDR-to-SDR processing, watch the colour tag; color.py can finish successfully with an incorrect configuration.
    The README FAQ says a wrong colour tag can let the run finish while producing washed-out footage.
  • When join.py handles clips with different size, frame rate, or audio layout, normalize them first or xfade can fail.
    The README FAQ says clips with differing media properties must be normalized first.
  • When local transcription is enabled, parakeet-mlx, faster-whisper, and openai-whisper download model weights on first use.
    The README's Local first section explicitly lists engines that download weights on first use.
  • If an MCP client only reads tools/list, it sees only the core 12 tools by default.
    The README FAQ says tools/list exposes 12 tools by default, while FFMPEG_SKILL_MCP_FULL=1 lists all 42.

Alternatives

  • Remotion:When your decision centers on comparing the approach with Remotion, inspect the differences in video generation or editing workflows directly; the supplied material gives no specific conclusion.
    README FAQ: How does ffmpeg-skill compare with Remotion?

Not stated in the README

  • The supplied material does not provide performance, processing speed, or hardware requirements for individual operations.
  • The supplied material does not specify supported operating-system versions or an FFmpeg version range.
  • The supplied material does not say whether GPU encoding is supported; the README only lists “Does it encode on the GPU?” as an FAQ heading.
  • The supplied material does not provide success rates or quality metrics for HDR-to-SDR, captions, or silence removal on real footage.
  • The supplied material does not specify the Node.js or npm versions required by the npx installation route.
  • The supplied material does not provide the complete parameters, output formats, or FFmpeg component dependencies for all 42 tools.
  • The supplied material does not provide a concrete feature, performance, or maintenance comparison with Remotion.
  • The supplied material does not establish a causal link between the 367 new stars, v3.10.1, and the 10 recent commits.

💡 Deep Analysis

6
Yes I maintain FFmpeg tools in Python with argparse and worry that CLI flags, MCP schemas, contracts, and documentation will drift. Is this project’s SPEC pattern worth adopting?
For: A Python tool developer familiar with FFmpeg who wants to reduce complex parameter maintenance and integrate with coding agents

Yes, especially if you must maintain a CLI, an MCP interface, and a machine-readable contract rather than a one-off FFmpeg script.

  • The project generates each tool’s input_schema at runtime from its own argparse parser, including flags, types, choices, defaults, required arguments, and mutually exclusive groups.
  • The MCP server does not maintain a separate schema; it translates the contract. Adding an argparse flag can therefore update the CLI and MCP tool definition without a second schema edit.
  • TOOL_META remains hand-authored for roles, capabilities, inputs, outputs, and verification details because those semantics cannot be expressed by argparse alone.
  • tests/test_contract.py checks code, contracts, documentation, and metadata for drift in CI. It detects inconsistencies but does not repair them automatically.

SPEC is therefore a good fit for reducing duplicate definitions and interface drift. It is not a complete metadata-generation system: maintainers still own TOOL_META, verification logic, and documentation.

  • README, “What is SPEC?”: “input_schema ... is derived ... from the live parser directly”
  • README, “What is SPEC?”: “The MCP server ... carries no schema of its own”
  • README, “What is SPEC?”: `TOOL_META` contains semantics that the parser cannot express
  • README, “What is SPEC?”: “tests/test_contract.py ... fails the build if ... drift”
Not stated in the README:The supplied README excerpt does not provide the minimum file checklist or development command for adding a complete new tool.;It does not specify the CI Python versions, test runner, or support matrix.
Yes I use Claude Code, Cursor, or Codex and want the agent to process local video without generating arbitrary FFmpeg shell commands. Can this project provide a controlled MCP tool interface?
For: A developer using Claude Code, Cursor, or Codex who wants a coding agent to process local video through MCP

Yes. It is designed for this constraint: FFmpeg is exposed as structured tools through MCP rather than as arbitrary shell text.

  • The project provides 42 task-specific tools covering cuts, captions, loudness, reframing, delivery checks, and project rendering.
  • Tools use typed arguments. Callers cannot submit arbitrary shell strings or filter_complex, reducing command-injection and parameter-misuse risks.
  • MCP advertises only 12 core tools through tools/list by default to keep client context small. FFMPEG_SKILL_MCP_FULL=1 exposes all 42, while every tool remains callable by name.
  • MCP schemas are derived from the same argparse parsers used by the CLI and from the machine-readable contract, so the CLI and MCP interface do not require separate parameter definitions.

It is therefore suitable for agents that must plan and invoke bounded media operations. It is not suitable when the workflow depends on arbitrary FFmpeg filter graphs that the project has not wrapped.

  • README, “Built for agents”: “ships 42 tools”
  • README, “Why”: “Structured tools, not shell strings”
  • README, MCP description: “tools/list advertises a core 12 by default”
  • README, “What is SPEC?”: “input_schema ... is derived ... from the same argparse parser”
npx ffmpeg-skill
Not stated in the README:The supplied README excerpt does not show the exact registration format for each MCP client.;The excerpt does not enumerate which tools belong to the default core 12.
Yes Our footage cannot be uploaded to the cloud and we do not want API keys. If we also need local captions using Parakeet, faster-whisper, openai-whisper, or whisper.cpp, is this project suitable?
For: A privacy-sensitive media team that cannot upload footage and wants local processing with FFmpeg and the Python standard library

Yes, provided that your team can absorb the local compute and storage cost of FFmpeg, the speech engine, and model weights.

  • The README explicitly states “No cloud · No API keys” and says the core setup requires ffmpeg and python3 on PATH, with no additional Python dependencies.
  • Optional local transcription supports Parakeet, faster-whisper, openai-whisper, and whisper.cpp. The engine runs on the machine and audio is never uploaded.
  • caption.py --transcribe and silence.py --transcribe accept --engine and --model; FFMPEG_SKILL_ASR_ENGINE and FFMPEG_SKILL_ASR_MODEL can define machine defaults.
  • The trade-off is local resource usage: the README notes that some engines download model weights on first use and that ASR can require substantial time, disk space, and hardware.

It is a strong fit when privacy and offline execution are mandatory. It is a poor fit if the team cannot download local model weights or lacks the required compute capacity.

  • README introduction: “No cloud · No API keys · Python standard library”
  • README, “Why”: “Optional local transcription”, listing Parakeet and whisper engines
  • README, “Why”: “The engine runs on your machine and the audio is never uploaded”
  • Project insight, user_experience.common_pitfalls: local ASR may require large model weights, first-run time, and extra hardware
npx ffmpeg-skill
Not stated in the README:The supplied README excerpt does not specify operating-system support, GPU models, RAM requirements, or model download sizes for each ASR engine.;It does not say how model weights should be obtained from an internal mirror in a restricted environment.
Yes I use Cursor as an MCP client and want to keep the default context small while occasionally calling multicam, batch-folder processing, and full project rendering. How should I determine whether this project meets that need?
For: A Cursor or other MCP client user who needs on-demand access to all 42 video tools while keeping the default MCP context small

Yes. The project separates limited default discovery from name-based access to the full tool set, matching your need to control context while retaining advanced capabilities.

  • MCP tools/list advertises only the core 12 tools by default, preventing all 42 schemas from entering Cursor’s context at once.
  • All 42 tools remain callable by name. If the client needs the complete advertised list, set FFMPEG_SKILL_MCP_FULL=1.
  • The scope includes more than basic cuts: it covers multicam, batch folders, whole-edit project rendering, delivery checks, and platform exports.
  • This design does not mean the agent will automatically understand complex timelines. The project insights note that timeline order, transitions, subtitle placement, and multi-track or multicam relationships can still be decomposed incorrectly.

It is suitable for MCP integrations with on-demand discovery and name-based invocation. If you require the client to expose all 42 schemas automatically without configuration, enable full mode.

  • README, “Built for agents”: “tools/list advertises a core 12 by default”
  • README, “Built for agents”: “FFMPEG_SKILL_MCP_FULL=1 listing all 42”
  • README, “Built for agents”: lists multicam, batch folders, and whole-edit project rendering
  • Project insight, user_experience.common_pitfalls: complex editing intent may be decomposed incorrectly
npx ffmpeg-skill
Not stated in the README:The supplied README excerpt does not show where Cursor should configure `FFMPEG_SKILL_MCP_FULL=1`.;It does not state whether a particular Cursor version has compatibility limits when calling tools not shown in `tools/list`.
It depends I need lossless-first cuts, followed by captions, reframing, or HDR-to-SDR conversion, and I need to confirm that the picture is actually correct. Is this more reliable than calling FFmpeg directly?
For: A content creator or media engineer who needs lossless-first cuts, keyframe-offset reporting, and caption/picture verification

It depends. It is more reliable than checking only the FFmpeg exit code, but it cannot fully automate subjective quality judgment or complex editorial decisions.

  • The project enforces “probe → edit losslessly where possible → check → verify”, measuring real media properties before selecting stream copy or re-encoding.
  • cut.py reports how far a cut moved because of keyframe alignment, making the trade-off between lossless cutting and frame-accurate cutting explicit.
  • When the picture changes, the workflow probes the result again, checks it against the target specification, and can generate a contact sheet. This is more informative than treating process success as output correctness.
  • However, the project insights state that verification cannot fully judge aesthetics, narrative continuity, subtitle semantics, or skin tones. Automatic reframing is also not equivalent to continuous subject or face tracking.

It fits verifiable cutting and transcoding workflows. It is not a complete nonlinear editor for professional grading, complex timelines, or detailed review.

  • README introduction: “fixed workflow (probe → edit losslessly where possible → check → verify)”
  • README FAQ, “Why 42 tools?”: “cut.py reports how far a cut snapped to a keyframe”
  • README, “Why”: “Verification after execution”, including contact sheets when the picture changes
  • Project insight, user_experience.usage_limitations: it is not a complete nonlinear editor and cannot fully judge subjective results
Not stated in the README:The supplied README excerpt does not show the contact-sheet command, output format, or resolution.;It does not specify the exact color-management workflow or target-display range for HDR-to-SDR conversion.
It depends I need to batch-process videos into platform versions and check maximum duration, loudness, true peak, aspect ratio, and codec requirements. Can this project serve as a layer in an automated media pipeline?
For: A media automation engineer who needs batch-folder processing, platform exports, and delivery checks

It depends. The project is suitable as a scriptable, verifiable media execution layer, but it cannot replace real playback testing or complete broadcast-grade QC.

  • The 42 tools include platform exports, delivery checks, batch folders, and whole-edit project rendering, covering common automation stages.
  • export.py checks a preset’s maximum length; loudness.py re-measures integrated loudness and true peak; outputs are probed again and checked against the destination specification.
  • The workflow is “probe → edit → check → verify”, using measured duration, frame rate, resolution, color, and audio layout rather than merely trusting the FFmpeg exit code.
  • The limitation is platform variability: codecs, pixel formats, audio sample rates, and color metadata are not handled identically by every platform, browser, or player. Delivery checks cannot fully replace actual playback tests.

It fits standardized exports and machine-readable checks. It should not be the sole system for professional grading, detailed mixing, or strict broadcast QC.

  • README, “Built for agents”: lists platform exports, delivery checks, and batch folders
  • README FAQ, “Why 42 tools?”: “loudness.py re-measures integrated loudness and true peak”
  • README FAQ, “Why 42 tools?”: “export.py checks the preset's maximum length”
  • README, “Why”: “Verification after execution”
Not stated in the README:The supplied README excerpt does not list the exact platform presets, duration limits, codecs, bitrates, or loudness thresholds.;It does not describe retry, concurrency, or intermediate-file management for failed batch jobs.

✨ Highlights

  • 42 FFmpeg tools cover editing, captions, HDR-to-SDR, and export
  • probe.py first reads duration, fps, resolution, and audio layout
  • SPEC generates input_schema at runtime from argparse
  • MCP exposes 12 tools by default and can list all 42 with an environment variable

🔧 Engineering

  • Use cut.py, caption.py, and loudness.py for editing, captions, and loudness processing
  • contract --json describes tool inputs, outputs, FFmpeg components, and verification
  • MCP tools/call can invoke all 42 tools by name, while tools/list shows 12 by default

⚠️ Risks

  • parakeet-mlx, faster-whisper, and openai-whisper download model weights on first run
  • MCP lists only 12 tools by default; without FFMPEG_SKILL_MCP_FULL, all 42 are not advertised
  • color.py can finish with a wrong color tag while producing washed-out footage
  • stabilize.py runs in two passes and the second pass needs the first pass's transforms file

👥 For who?

  • Developers using Claude Code, Cursor, or Codex to process local video
  • Agent-framework integrators who need MCP contracts and typed arguments
  • Teams wanting offline FFmpeg and ffprobe processing without uploading footage