← Blog Content Creators Nov 21, 2026 · 7 min read

FFmpeg Skill: Edit Videos by Chatting With Your Coding Agent

The open-source FFmpeg skill gives Claude Code, Cursor or Codex 42 local video tools. Trim, caption, resize for Reels and batch-export just by asking.

FFmpeg Skill: Edit Videos by Chatting With Your Coding Agent

The FFmpeg skill is an open-source toolkit that turns your coding agent into a local video editor: you describe the edit, and Claude Code, Cursor or Codex runs real FFmpeg commands on your own machine. This tutorial covers what the repo is, how to install it from the official README, practical requests for trimming, captions, Reels crops and batch exports, and the limits you should know before relying on it.

What is the FFmpeg skill?

kajisho5/ffmpeg-skill is a GitHub repository created on 3 September 2026. When I checked it on 21 November 2026, it had about 8.8k stars and 807 forks, and it is released under the MIT license. Always check the repo yourself before installing, since releases are frequent.

The README describes it as an Agent Skill for Claude Code, Cursor, Codex "and any agent that reads SKILL.md," and every tool is also available as an MCP tool. The key ideas:

  • 42 tools built on ffmpeg and ffprobe: cut, join, silence removal, fit to duration and aspect ratio, captions and karaoke, overlays, LUTs, audio clean-up, loudness, multicam, delivery checks and batch folders.
  • A fixed workflow: probe the file, edit losslessly where possible, check, then verify.
  • Local only: the README says "No cloud · No API keys," and the tools work offline on footage you would rather not upload.
  • 12 stable tools and 30 beta tools in version 4.x.

The difference from asking an AI to "write me an ffmpeg command" is verification. The README points out that an agent that merely knows FFmpeg still guesses frame rates and codecs and reports "done" without opening the result. This skill probes the output so the agent can check real duration, frame size and audio.

Requirements

From the README:

  • FFmpeg 6.1 or newer (tested with 6.1, 7.1, 8 and 9).
  • Python 3.10+, standard library only.
  • Node 16+, only for the npx installer.

How to install (official steps)

The README's one-line setup installs the skill for the agents it finds, installs FFmpeg if it is missing, and runs a health check:

npx ffmpeg-skill setup

Or step by step:

# 0. FFmpeg itself, once (Ubuntu/Debian shown)
sudo apt install ffmpeg

# 1. install the skill for Claude Code (Cursor: --cursor, Codex: --codex, all three: --all)
npx ffmpeg-skill

# 2. check the machine
npx ffmpeg-skill doctor

The README's FFmpeg table lists brew install ffmpeg-full for macOS and winget install Gyan.FFmpeg for Windows. On Windows with Git Bash, it notes that a python.org install exposes python rather than python3, so replace it in raw script examples if you see "command not found."

Claude Code users can also install it as a plugin, and there are routes for Codex, Gemini CLI and MCP clients listed in the README's install table.

Captions from speech

Automatic captions need a local speech engine, installed separately. The README's simplest option is:

pip install faster-whisper

The first run downloads its model; after that, the README says the audio never leaves your machine.

What to ask your agent

Once installed, you just talk. The README's own example:

"Take interview.mp4, keep 0:45–1:20 and 5:00–5:25, and make it a 60-second Reel."

According to the README, the agent then probes the file, cuts the two segments, crops to 9:16, exports with the Reels preset, checks the result against the platform and reports something like "final.mp4: 60.00 s, 1080×1920, 30 fps, AAC stereo."

More requests creators can try

  • Trim: "Cut vlog.mp4 from 2:10 to 3:05 without re-encoding if possible."
  • Remove pauses: "Remove silences longer than half a second from tutorial.mp4, keep natural breaths."
  • Captions: "Transcribe talk.mp4 and burn in captions that pop word by word."
  • Reels and Shorts: "Make a 9:16 version of podcast.mp4 for Reels and check it fits the safe area."
  • Loudness: "Normalize episode.mp4 to -14 LUFS."
  • One edit, many platforms: "Render this edit for TikTok, Reels, Shorts and YouTube."
  • Batch: "Export every video in the raw/ folder as 1080p MP4 for Instagram."

Platform templates

The README lists delivery templates for tiktok, reels, shorts, youtube-shorts, youtube, x, linkedin, facebook, podcast and audiogram. The TikTok template, for example, crops to 9:16, places captions above TikTok's description bar and clear of the like column, targets -14 LUFS and runs a platform check. Using --template all renders the seven video destinations from one edit. For a broader strategy, see our guide to repurposing one video for every platform.

The review page

After an edit you can ask the agent for a review page: a local HTML file showing sources, every step with its checks, the result in a phone frame with the platform's safe area, and a timeline. You can click a clip or caption, write what should change and copy the instruction back to your agent. The README says nothing is uploaded.

Safety features worth knowing

  • Source protection: a destination that matches an input is refused, and replacing an existing output needs --overwrite.
  • Typed options: the agent passes named options like --aspect 9:16 instead of writing raw filter graphs.
  • Timeouts: media jobs run under a default 30-minute timeout, and partial output is removed if killed.

Still, keep backups of raw footage. Our AI agent safety guide explains why you should review what any agent runs on your files.

Limits and honest caveats

  • No automatic face tracking. The README's FAQ says a 9:16 crop is centered unless you set the crop position, and "subject framing still needs visual review."
  • Captions are not fully verified. Placement and legibility are marked "unverified," so look at a contact sheet before delivering.
  • GPU encoding is limited to Apple VideoToolbox on Apple Silicon; other GPU encoders are detected but not used.
  • It does not decide your edit. The README says this repo is the "hands"; choosing what to cut and what captions say is your job (or another tool's).
  • Demo footage in the repo is partly AI-generated with Google Veo, as the README notes.

Compared with app-based editors, this is for people comfortable in a terminal. If you prefer a visual timeline, our AI video editing workflow with Descript and CapCut is the easier route. If you want animated graphics on top, the README points to a related Remotion skill, and our motion graphics with Claude and Remotion guide shows that side.

Who should try it

  • Creators who batch-export the same video to many platforms.
  • Developers and agencies automating client video delivery.
  • Anyone editing private footage who does not want to upload it to a cloud tool.

Key takeaways

  • The FFmpeg skill gives Claude Code, Cursor, Codex and MCP clients 42 local FFmpeg tools under the MIT license.
  • Install with npx ffmpeg-skill setup; it needs FFmpeg 6.1+, Python 3.10+ and Node 16+ for the installer.
  • You describe edits in plain language, and the agent probes, edits, checks and verifies the output.
  • Platform templates handle Reels, TikTok, Shorts and more, including safe areas and loudness.
  • Crops are centered by default and captions need a visual check, so review before publishing.

FAQ

Is the FFmpeg skill free?

Yes. It is open source under the MIT license, and the README says it needs no cloud account or API key.

Does it work with Claude Code on Windows?

The README lists a Windows FFmpeg install with winget and notes Windows-specific Python naming in Git Bash.

Does it upload my videos?

The README says the tools run locally and offline. Speech engines download their model on first run.

Sources

Read next