FFmpeg Local Video Editor
Give coding agents a local FFmpeg workflow for cutting, captioning, reframing, and checking video deliverables.
- Source repo
- kajisho5/ffmpeg-skill
- Stars
- ★ 2k
- Last updated
- today
- License
- MIT
- Primary language
- Python
- FA score
- 80/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- 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.
- A short-form video team needs to turn interview segments into Reels or TikTok deliverables and check framing, loudness, and platform requirements.
- A creator wants to remove silence, join clips, change aspect ratio, and produce contact sheets for local review.
- A podcast editor needs voice cleanup, audio joins, loudness normalization, and checks for chapter markers and channel count.
- A multilingual content team needs to burn existing subtitles into video or mux them as selectable language tracks.
- 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?
- 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.
- 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?
Why each dimension lost points
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.
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.
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.
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.
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.
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.
- 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.