ffmpeg-skill
ffmpeg-skill — a skill and MCP server: an agent cuts and joins video, fixes audio, adds captions and exports for TikTok and Reels with local FFmpeg
- 2,052 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The agent runs Python scripts and FFmpeg on your files and writes new files next to the originals, with overwriting allowed only through `--overwrite`
- The installer copies the skill into `~/.claude`, `~/.cursor` or `~/.agents` and it applies to every project
- For speech transcription the local engine downloads model weights from the network on first run
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/ffmpeg-skillDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent runs Python scripts and FFmpeg on your files and writes new files next to the originals, with overwriting allowed only through `--overwrite`
- The installer copies the skill into `~/.claude`, `~/.cursor` or `~/.agents` and it applies to every project
- For speech transcription the local engine downloads model weights from the network on first run
This is third-party code. Review the repository files before installing.
What it does
ffmpeg-skill teaches an agent to edit video and audio through the FFmpeg installed on the machine and gives it 42 Python tools. The working order is written in `SKILL.md`: first `probe.py` measures duration, frame rate, resolution, colour and audio tracks, then the agent edits without re-encoding where possible, shows the plan with `--dry-run`, runs a step, checks the file with `check.py` and looks at the picture through `look.py`, which builds a contact sheet as a PNG. The tools do not overwrite the source file: the result goes to a new file named `<input>_<operation>.<extension>`. The tools cover routine jobs: cutting and joining, silence removal, fitting to a duration and aspect ratio (for example 9:16), animated and karaoke captions, logos and titles, HDR to SDR and LUTs, audio clean-up and loudness normalization, external microphone sync, camera switching, blurring regions and batch processing of folders. For platforms there are templates for TikTok, Reels, Shorts, YouTube, X, LinkedIn, Facebook and podcast: `render.py --template tiktok` builds a clip that respects the app's interface zones and checks it. The same tools are available over MCP through `mcp/server.py` on stdio. The server has no tool table of its own: the list is built from the machine-readable contract `contract --json`, so a new script flag shows up in MCP by itself. Captions from speech come from a local Parakeet or whisper engine when one is installed. Otherwise the agent uses a ready text or a file with timings.
Who it is for. For video creators, podcasters and developers who hand Claude Code, Cursor or Codex the cutting of video, vertical versions and captions on their own machine without uploading files to the cloud.
Good fit when
- From an interview you need to keep 0:45–3:10 and 5:00–6:30 and fit the result to exactly 60 seconds for Reels
- A horizontal clip has to become a vertical 9:16 one with captions that do not cover the app's buttons
- In a podcast recording you need to remove pauses and level the loudness to a set LUFS target
- Footage from two cameras and an external microphone needs audio sync and camera switching
- iPhone HDR video has to be converted to SDR and checked before upload with `check.py --platform`
Not a fit when
- You need an edit where something decides which parts to cut: the skill executes an edit and leaves the choice of segments and approval of the result to a person or the calling agent
- You need video generation from text, voice-over or stock footage: the tools work only with your files and create nothing themselves
- The machine has no FFmpeg 5.0 or newer with `libass` and the `drawtext` and `loudnorm` filters: without them captions and normalization will not run
- You need an editing program with a timeline for manual work: the skill drives files with commands and has no editor window
- You need a clip assembled with animated inserts: the catalog has video-use for that, and it also removes pauses and slips
Example request
Take interview.mp4, keep 0:45–3:10 and 5:00–6:30 and make a vertical clip of exactly 60 seconds for ReelsLimitations
- MIT license. You need Python 3.9 or newer and FFmpeg 5.0 or newer with libx264, aac, libass and the drawtext, loudnorm, xfade and silencedetect filters. Node 16 is needed only by the `npx` installer. On macOS the plain Homebrew `ffmpeg` formula lacks the subtitles, drawtext and zscale filters, so you install `ffmpeg-full` and put it on PATH.
- An installed copy does not update itself: rerun `npx ffmpeg-skill` for a fresh version, or `claude plugin update` for the Claude Code plugin. Over MCP only 12 of the 42 tools are listed by default; the rest are callable by name.
- The skill does not choose segments or approve the result. Checking the picture relies on the agent's own vision: `look.py` only builds a PNG. Without vision, the report states that pixels were not inspected.
- Captions from speech and filler-word removal need a local Parakeet or whisper engine. Without one the tool refuses and prints install commands. Models download on first run, and `parakeet-mlx` takes its weights from Hugging Face by default.
- The author reports a fixed vulnerability in `batch.py`, where a recipe step could escape `scripts/` through an absolute path. Only the latest version is supported, with no long-term branches.
How to disable. `npx ffmpeg-skill --uninstall` removes the skill from the selected folders: `--codex` clears `~/.agents/skills` and the older `~/.codex/skills`, `--cursor` clears `~/.cursor/skills`. Remove the Claude Code plugin with Claude Code's own plugin tools. For MCP, delete the `ffmpeg-skill` entry from `mcpServers` in the client's settings. Clips already created sit next to the source files and have to be removed by hand.
FAQ
How do I install ffmpeg-skill and check that it works?
Run `npx ffmpeg-skill` for Claude Code, add `--cursor` for Cursor or `--codex` for Codex, and `--all` installs into all three. Then `npx ffmpeg-skill doctor` reads the encoder, filter and bitstream filter lists of your FFmpeg and reports what is missing. Exit code 0 means everything needed is there, 1 that something is missing, 2 that some capabilities could not be determined. The plugin installs with `claude plugin install kajisho5/ffmpeg-skill`.
How do I make a TikTok or Reels clip with one command?
`python3 $S/render.py talk.mp4 --template tiktok --cues cues.txt` fills the platform template: a 9:16 crop, captions popped word by word above the description bar, −14 LUFS loudness, the export preset and a `check.py --platform tiktok` pass. Templates exist for tiktok, reels, shorts, youtube-shorts, youtube, x, linkedin, facebook and podcast. `--template all` renders versions for every platform from one edit.
Which tools does an agent see over MCP, and how do I see all of them?
By default `mcp/server.py` lists the core 12: `render`, `look`, `caption`, `export`, `check`, `fit`, `cut`, `audio`, `loudness`, `graphics`, `silence`, `probe`. The `FFMPEG_SKILL_MCP_FULL=1` variable lists all 42. The rest are callable by name without it. Besides tools, the server offers five ready recipes: `reel`, `podcast`, `multicam`, `delivery_check` and `hdr`.
Do videos go to the cloud, and are keys needed?
No keys or accounts are needed, a local FFmpeg does the processing and there are no Python dependencies beyond the standard library. Video and audio are not uploaded. The exception is speech recognition model weights: `parakeet-mlx`, `faster-whisper` and `openai-whisper` download them on first run if you ask for a transcript.
Does the skill overwrite source files?
No. The result gets a name like `<input>_<operation>.<extension>`, and the tool refuses to touch an existing output file until you pass `--overwrite`. A test hashes every input file after the run to confirm it did not change. The output path should not point at a file that was not created in this job.
What if captions do not render on macOS?
The plain Homebrew `ffmpeg` formula is built without libass, so it has no subtitles filter. Install `brew install ffmpeg-full`. That formula is keg-only, which means it is not linked into PATH automatically. The skill itself uses `ffmpeg-full` from the same Homebrew prefix when PATH holds the lean formula, and `doctor --json` shows which FFmpeg it used.
Discussion
No questions or reviews yet.
Related
SkillsA Claude Code skill that downloads a YouTube video, splits it into semantic chapters, cuts chosen clips, translates subtitles and burns bilingual ones in
ChatGPT short-video editing skills
ChatGPT 剪短影音 Skills
Two agent skills: set up the editing environment and build a vertical short video in eight verified steps
A skill and MCP server for cutting long videos: the agent takes a link or file and builds Shorts, Reels and TikTok clips with a cover, post text and ZIP
An MCP server and REST API to assemble short vertical videos with captions, voiceover and music for TikTok, Reels and Shorts
Video skills for Claude Code and Codex: break a clip into a shot-by-shot analysis and render video with a storyboard overlay
A video editing skill for Claude Code and Codex: the agent cuts pauses and filler words, grades color, burns subtitles and adds animated overlays
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| ffmpeg-skill (this entry) | no | 2,052 | |
| video-use | no | 29,550 | cuts pauses and slips, does colour correction, captions and animated inserts, a skill for Claude Code and Codex |
| Open Edit (VEED) | no | 1,706 | from the VEED organization, builds an MP4 from an edit description with motion graphics and installs dependencies via Homebrew on a Mac |
| chengfeng-videocut | no | 3,117 | a plugin for talking-head video editing: removes slips, adds captions and on-screen graphics |
README in short
The repository holds `SKILL.md`, 42 Python scripts, references on flags, devices and pitfalls, platform templates and the MCP server. Alongside are documents on the contract and design decisions, a roadmap and a gallery of 53 before and after examples with the command under each. The test side contains FFmpeg output snapshots for versions 6.1, 7.1, 8 and 9 and agent evaluation runs with independent grades. The stability section promises that 2.x versions will not remove or rename any tool, flag or JSON key before 3.0.
README badge
Original SKILL.md
--- name: ffmpeg-skill description: 'Edit video and audio with local FFmpeg from natural-language requests: cut, trim, join, resize/reframe (9:16, 1:1), speed change, captions and subtitles (SRT/ASS, animated, karaoke), logos and text overlays, lower-thirds and titles, silence removal, multicam and external-mic sync, loudness normalisation, HDR/Dolby Vision to SDR, LUTs, background music with ducking, platform exports (YouTube, Reels, TikTok, X), compliance checks, scene detection and highlight reels, contact sheets to inspect results, and whole-edit project files.' --- # ffmpeg-skill Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`.