ffmpeg-skill

What it does

ffmpeg-skill is a set of 42 Python scripts that drive the ffmpeg and ffprobe already installed on your machine: inspecting files, cutting and joining, removing silence, fitting clips to a length or aspect ratio, burning captions, adding overlays and motion graphics, HDR-to-SDR conversion, audio clean-up, loudness normalisation, multicam alignment, platform export presets and delivery checks. It is packaged first as an Agent Skill (a SKILL.md that Claude Code, Cursor or Codex reads), and it also ships mcp/server.py, a stdio JSON-RPC server that turns each script into an MCP tool.

The server builds its tool list from each script's own argument parser at start-up, so the MCP schemas follow the command-line flags. By default tools/list advertises only 12 core tools (render, look, caption, export, check, fit, cut, audio, loudness, graphics, silence, probe); setting FFMPEG_SKILL_MCP_FULL to anything but empty or 0 lists all 42, and every tool can be called by name either way. It also offers five prompts (reel, podcast, multicam, delivery_check, hdr) that return the command lines for a common workflow.

Editing runs on your machine. Tools write new files named after the input and refuse to replace an existing output unless --overwrite is passed. Each ffmpeg call is stopped after 1800 seconds by default (FFMPEG_SKILL_TIMEOUT, 0 for none). In scripts/_common/runner.py a value that is not a number falls back to 1800 and a negative one means no limit, and the server kills a tool process that runs past four times that limit plus 60 seconds. caption and silence can transcribe speech locally when a speech engine is installed (parakeet-mlx, parakeet.cpp, whisper.cpp, faster-whisper or openai-whisper), chosen with --engine/--model or the FFMPEG_SKILL_ASR_ENGINE and FFMPEG_SKILL_ASR_MODEL defaults. An engine name the code does not know is refused rather than ignored (scripts/_common/asr.py).

What it needs

Install ffmpeg first: brew install ffmpeg-full on macOS (the skill finds it by itself when the lean Homebrew ffmpeg is first on PATH), sudo apt install ffmpeg on Ubuntu or Debian, winget install Gyan.FFmpeg on Windows. Some flags need more of ffmpeg (libx265, prores_ks, zscale, libmp3lame, libopus, libvorbis). Node is needed only for the npx installer. Without it, clone the repository and copy SKILL.md, package.json, scripts/, templates/, references/, docs/ and mcp/ into place. For transcription, pip install faster-whisper is the simplest engine. It and openai-whisper and parakeet-mlx download model weights the first time they run.

Limits

• Not covered tools/list shows 12 tools unless FFMPEG_SKILL_MCP_FULL is set; a client that only offers listed tools will not see the other 30.
• Limit A tool whose filters or encoders are missing from your ffmpeg build cannot run; the plain Homebrew ffmpeg lacks subtitles, drawtext and zscale. Run doctor to see which tools are usable.
• Limit Every tool refuses an ffmpeg or ffprobe whose version reads older than 6.1 (a git build with no release number is let through). The npx installer refuses Python below 3.10.
• Limit The npm package's program is an installer that copies the skill files, not the MCP server; the client must start python3 on the copied mcp/server.py.
• Platform On Windows with a python.org install, python3 may not be on PATH; change the command to python.
• Not covered It finds nothing in the picture: crops, redaction boxes and reframes take coordinates you give, and highlight ranking is a loudness or length proxy.
• Not covered Transcription needs a separately installed speech engine; without one, caption --transcribe and silence --filler refuse and print install lines.

tools/list shows 12 tools unless FFMPEG_SKILL_MCP_FULL=1 is set; a client that only offers listed tools will not see the other 30. Tools whose filters are missing from your ffmpeg build cannot run; run doctor to see which. The npm package only installs the skill files: its program is an installer, not the MCP server, so the client must point python3 at the copied mcp/server.py. On Windows with a python.org install, python3 may not be on PATH and the command must be changed to python. Highlight ranking is a loudness or length proxy, not a judgement of quality, and the tools do not decide what to cut or rewrite caption text.

Who it suits

Suits developers and editors who want an assistant to edit local footage with ffmpeg without uploading it or holding any credential, and who are comfortable installing a full-featured ffmpeg build and Python. Because it writes files on your machine and needs no account, it fits private material. If you would rather not install ffmpeg locally, a hosted ffmpeg service such as ffmpeg-micro-mcp (which we also list) processes files on the vendor's servers instead, at the cost of sending your media there.