ffmpeg-skill is a local, agent-oriented FFmpeg toolkit comprising 42 Python 3.10+ standard-library scripts that expose a probe → edit → verify workflow for AI coding agents (Claude Code, Cursor, Codex) and direct CLI use. Every tool derives its CLI flags and MCP input_schema from a shared argparse parser at runtime; CI fails if the generated contract (contract --json) drifts. The skill installs via npx ffmpeg-skill, validates the local FFmpeg build with doctor (checking encoders, decoders, filters such as libx264, libass, zscale, loudnorm, xfade, vidstab), and advertises 12 core MCP tools by default (all 42 with FFMPEG_SKILL_MCP_FULL=1). Core tools include probe.py (duration, fps with VFR detection, resolution, HDR/Dolby Vision, colour tags, audio layout), cut.py (lossless stream-copy first, --smart for frame-exact H.264 GOP-boundary cuts, --accurate for frame/sample-exact re-encode), join.py (xfade transitions with stream normalisation, --copy --transition none for matching streams), fit.py (duration via pitch-preserving speed change or trim, aspect 9:16/16:9 via pad/crop/blur, --crop-x/--crop-y anchor), silence.py (dead-air removal with --margin 0.2s, --filler for timed filler words, --speech-aware sentence-boundary cuts, --sentence-min-silence/--sentence-margin-tail), loudness.py (two-pass EBU R128 loudnorm to −14 LUFS/−1 dBTP or custom targets, re-encode until measured TP met), caption.py (burn SRT/ASS with phrase-aware wrap, --platform safe zones, --transcribe via faster-whisper/parakeet-mlx/openai-whisper locally), audio.py (voice chain light/medium/strong, FFT denoise, typed compressor/limiter/gate, sidechain ducking, tempo with atempo 0.5–2.0), sync.py (cross-correlation offset, clock-drift correction), and render.py (templates for tiktok/reels/shorts/youtube/x/linkedin/facebook/podcast/audiogram, --template all writes a *_pack.md table). All tools support --dry-run, --plan FILE, --json/--json-brief, --progress, --timeout, and --overwrite; verification runs probe.py, check.py, and look.py contact sheets (PNG) for visual diffs. Optional local ASR engines download weights on first run; audio never leaves the machine. The repo is standalone (no cloud, no API keys) and serves as the execution layer for a wider ecosystem (video-editing-skill, remotion-ffmpeg-skill, etc.) that consumes its JSON contract and tool outputs.

Read original