FFmpeg Local Video Editor

Give coding agents a local FFmpeg workflow for cutting, captioning, reframing, and checking video deliverables.

Stars
★ 2k
Last updated
today
License
MIT
Primary language
Python

At a glance

How it runs
CLIAgent plugin / skillMCP server
Works with
Universal · cross-platformCodex · Claude Code
Cost
Free, no paid service needed
Setup effort
Low · running in minutes
You'll need
FFmpeg 5.0 or laterPython 3.9 or laterNode.js (for npx installation)Shell / CLILocal filesystemMCP Server
Typical use
A short-form video team needs to turn interview segments into Reels or TikTok deliverables and check framing, loudness, and platform requirements.
Not a fit if
  • Teams that need automatic face or subject tracking for reframing
  • Users who need cloud editing or uploaded media processing
Source review
80/100 · Good

What does this agent do, and when should you use it?

ffmpeg-skill is a local media-processing toolkit for Claude Code, Cursor, Codex, and MCP clients, with 42 tools implemented as Python scripts. An agent probes a file first, runs typed command-line tools for editing, audio, captions, reframing, or platform export, then checks the result. The tool contract is generated from each script's argparse parser and is available through contract --json; it also supplies the MCP tools/list and tools/call interfaces. The tools invoke ffmpeg and ffprobe on the user's machine without a cloud service or API key. They require FFmpeg 5.0 or later and Python 3.9 or later.

Install and run the CLI with npx ffmpeg-skill, or configure mcp/server.py as a stdio server for an MCP client. A typical workflow uses probe.py to read duration, frame rate, resolution, color, and audio streams; calls tools such as cut.py, fit.py, caption.py, audio.py, loudness.py, or render.py; then verifies the output with probe.py, check.py, and, when needed, look.py. Each tool takes structured argparse arguments and supports --dry-run to preview commands and --json for structured results; --plan FILE saves a plan for later execution. The MCP server derives its tool definitions from the contract. It lists 12 core tools by default, or all 42 when FFMPEG_SKILL_MCP_FULL=1. Tools create new output files and do not overwrite inputs; an existing output is not silently replaced.

  1. A short-form video team needs to turn interview segments into Reels or TikTok deliverables and check framing, loudness, and platform requirements.
  2. A creator wants to remove silence, join clips, change aspect ratio, and produce contact sheets for local review.
  3. A podcast editor needs voice cleanup, audio joins, loudness normalization, and checks for chapter markers and channel count.
  4. A multilingual content team needs to burn existing subtitles into video or mux them as selectable language tracks.
  5. A team using an MCP client wants its coding agent to edit local media through structured tools instead of arbitrary FFmpeg command strings.

How do you install or deploy this agent?

Install ffmpeg, ffprobe, and Python 3.9 or later first. The README quick start uses npx to install the Claude Code skill; add --cursor for Cursor, --codex for Codex, or --all for all three. Run doctor after installation to check the available FFmpeg capabilities. To connect an MCP client, configure server.py as a stdio server:

How do you use this agent?

After installation, ask the agent to process a file or run the scripts directly from a shell. Use contract --json to inspect the machine-readable tool contract; --dry-run previews a plan and --json returns structured output details. For example:

What are this agent's strengths and limitations?

Pros
  • Its 42 tools cover editing, captions, audio, picture processing, platform exports, and whole-edit rendering, with a machine-readable contract describing inputs and verification.
  • It runs FFmpeg and ffprobe locally, with no cloud service or API key required, so media does not need to be uploaded.
  • Dry runs, fingerprinted plans, output probes, and contact-sheet inspection support review before and after processing.
  • The same contract serves the CLI and MCP interfaces; MCP lists only 12 core tools by default to limit client context.
Limitations
  • Users must provide compatible FFmpeg and Python installations; individual tools may also need specific FFmpeg encoders, filters, or subtitle support.
  • It does not detect faces, products, or subjects, or choose a crop anchor automatically; the caller must make those decisions.
  • Optional local transcription requires a supported speech engine, and some engines download model weights on first use.
  • FFmpeg builds differ in their capabilities, so a specific tool may be unavailable even when the overall doctor check passes.

How does this agent compare with similar options?

The README positions this as an editor for existing local media files: Remotion renders video from React components, and HyperFrames renders from HTML, while ffmpeg-skill edits existing media with FFmpeg and can accept videos produced by either. It also distinguishes this tool from video-production-agent and AI-video-production-OS in the author's ecosystem: those projects decide cut points, approve deliverables, and plan whole edits; ffmpeg-skill performs the media operations.

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
FFmpeg Local Video Editor This agent 80 · Good CLIFree ★ 2k today Python Codex · Claude Code
Generative Media Skills 41 · Major gaps CLIFree + model costs ★ 5.9k today Python Claude Code · Claude.ai
Pireel Studio 40 · Major gaps Web appFreemium ★ 1.3k 1mo ago TypeScript Codex · Claude Code
HTML Video Studio 53 · Major gaps CLIFree + model costs ★ 4.7k 4mo ago HTML Codex · Claude Code · Claude API

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Good
80/ 100 5-point scale 4.0 / 5
Trust 23/29
Reliability 9/14
Adaptability 15/18
Convention 15/18
Effectiveness 12/13
Verifiability 6/8
Why each dimension lost points
Trust23 / 29 · 4.0/5

The tools use local FFmpeg and typed arguments, reject caller-supplied filter graphs, and do not run through shell strings. Inputs are not overwritten; replacing an existing output requires --overwrite, and dry runs, fingerprinted plans, and cleanup of partial output on interruption are described. Optional speech recognition runs locally, but model weights may be downloaded from Hugging Face or elsewhere, so sensitive-data handling and least privilege are not fully established. A private vulnerability-reporting path and CodeQL are documented, but the supplied material contains no dependency audit or vulnerability status. Publisher identity is unknown; package metadata naming an author does not verify identity.

Reliability9 / 14 · 3.2/5

The README, package metadata, CI configuration, and test fixtures are broadly consistent. CI is described as covering several operating systems, Python versions, and FFmpeg versions, but no actual results for this revision are supplied, so compatibility and self-check claims remain primarily repository claims. doctor reports missing or unknown capabilities, and tools are documented to return a reason on stderr with a non-zero exit; the failure-message implementation is not fully shown, so this does not merit full marks.

Adaptability15 / 18 · 4.2/5

The repository names Claude Code, Cursor, Codex, and MCP clients and gives concrete workflows from probing and editing through platform delivery. It also clearly states boundaries: it does not detect faces or subjects, judge highlights by content, or choose a crop anchor for the caller. Trigger conditions and environment needs are documented, but there is no complete platform installation matrix; FFmpeg build features, optional fonts, and ASR models affect availability.

Convention15 / 18 · 4.2/5

The README has clear sections, a contents list, tool tables, flow diagrams, quick start, examples, and a distinction between standalone use and the wider ecosystem. Install instructions, Windows command differences, per-tool doctor status, FAQ, demos, and limitations are useful. The MIT license is explicit. Package version, CI, and a security policy provide some update information, but the supplied material does not include CHANGELOG contents or a clearly identified maintenance owner or support identity, limiting confidence in version history and responsibility.

Effectiveness12 / 13 · 4.6/5

The 42 structured tools, machine-readable contract, MCP interface, JSON output, probe-and-verify workflow, and platform templates can produce inspectable media deliverables. Local processing reduces the need to upload footage. The standard-library implementation and lack of API keys reduce adoption cost, while requiring users to install a compatible FFmpeg and sometimes optional components, fonts, or ASR models leaves configuration and maintenance costs.

Verifiability6 / 8 · 3.8/5

Many claims point to specific repository material such as the package manifest, CI workflow, test fixtures, security policy, and README feature descriptions. However, the supplied evidence omits full source, CHANGELOG contents, and revision-specific CI results, limiting cross-source confirmation. The README separates capabilities from limitations and says visual judgment is performed by the calling agent while highlight ranking uses proxies. Confidence remains low for this static review.

Risks and how to mitigate them
  • This is a low-confidence static review; tools were not run and CI results for this revision were not verified.
  • ASR features such as --transcribe may download model weights from external sources; the repository says audio itself is not uploaded.
  • Some tools may be unavailable when an FFmpeg build lacks required filters, encoders, or fonts; consult doctor’s per-tool report.
Evidence confidence: Low Reviewed Oct 21, 2026 Reviewed revision 4334225e4a61
See the full review method →

FAQ

Does it require a paid service or API key?
No. The project describes local, offline use without a cloud service or API key, and is licensed under MIT.
Are media files uploaded?
No. Editing uses local FFmpeg and ffprobe. Optional transcription also runs on the machine and does not upload audio; some speech engines download model weights on first use.
Can I pass arbitrary FFmpeg options or a filter_complex graph?
No. Each script accepts only the arguments defined by its argparse parser; callers cannot supply arbitrary filter graphs or FFmpeg commands.
Can it automatically track faces or subjects when reframing?
No. fit.py uses a centered crop by default, and callers can set crop-x and crop-y. look.py creates a contact sheet for caller review; the tools do not identify subjects.
What if an FFmpeg component required by a tool is missing?
Run doctor or doctor --json to see per-tool usability and missing capabilities. Some tools may be unavailable on that build; failures report a reason rather than treating an undetected capability as available.
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related agents