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.

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
ffmpegandffprobe: 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
npxinstaller.
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.mp4from 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.mp4and burn in captions that pop word by word." - Reels and Shorts: "Make a 9:16 version of
podcast.mp4for Reels and check it fits the safe area." - Loudness: "Normalize
episode.mp4to -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:16instead 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
NEW
Free Apps for Content Creators: Best Open-Source Stack for 2027
The best free apps for content creators for 2027: recording, screen capture, editing, audio, subtitles and thumbnails, all open source and watermark-free.
Read more
NEW
Facebook Creator Fast Track: Guaranteed Pay for Moving Creators
Facebook Creator Fast Track pays established creators for three months to post Reels. Who qualifies, the posting rules, pay tiers and whether to repurpose.
Read more
NEW
Instagram Your Algorithm: How to Reset What Reels Show You
Use Instagram Your Algorithm to clean up Reels, Explore and Feed step by step, and see how creators can read the same topic signals to reach the right viewers.
Read more