FFmpeg Agent — Video Processing CLI

Agent-native CLI wrapper for FFmpeg. Provides compound commands with JSON output for Claude Code and other agents. Wraps FFmpeg v8.1 on Windows.

Install

cd D:\ClaudeDev\00_GITHUB\cliit\clis\ffmpeg-agent
pip install -r requirements.txt
python cli.py --help

FFmpeg binary: C:\Users\mikem\AppData\Local\Microsoft\WinGet\Links\ffmpeg.exe

Override with env: FFMPEG_BIN, FFPROBE_BIN

Agent Pattern

Always run info first to get metadata before processing. Add --json to any command for machine-readable output.

python cli.py info video.mp4 --json
# Returns: {"ok": true, "duration_seconds": 120.5, "video": {"width": 1920, "height": 1080}}

Commands

| Command | Purpose | Example | |---------|---------|---------| | info | Get metadata | python cli.py info video.mp4 --json | | cut | Trim video | python cli.py cut input.mp4 --start 00:01:00 --end 00:02:00 -o out.mp4 | | concat | Join files | python cli.py concat a.mp4 b.mp4 -o merged.mp4 | | extract-audio | Pull audio | python cli.py extract-audio input.mp4 -o audio.mp3 | | thumbnail | Single frame | python cli.py thumbnail input.mp4 --time 00:00:05 -o thumb.jpg | | thumbnails | Batch frames | python cli.py thumbnails input.mp4 --interval 10 --dir ./thumbs/ | | convert | Transcode | python cli.py convert input.mp4 --format mp4 --quality high -o out.mp4 | | compress | Smart compress | python cli.py compress input.mp4 --target-size 10MB -o compressed.mp4 | | add-subs | Burn subtitles | python cli.py add-subs input.mp4 --srt captions.srt -o out.mp4 | | resize | Resize/reframe | python cli.py resize input.mp4 --width 1080 --height 1920 -o vertical.mp4 --fit crop | | audio-normalize | EBU R128 | python cli.py audio-normalize input.mp4 -o normalized.mp4 --target-lufs -16 | | gif | Video to GIF | python cli.py gif input.mp4 --start 00:00:05 --duration 3 -o output.gif | | speed | Speed control | python cli.py speed input.mp4 --factor 2x -o fast.mp4 |

Quality levels for convert: high (CRF 18), medium (CRF 23), low (CRF 28). Target LUFS for normalize: -23 (broadcast), -16 (social, default), -14 (streaming). Fit modes for resize: crop (center-crop, default), pad (letterbox/pillarbox), stretch.

JSON Response Schema

Success: {"ok": true, "output": "path/to/output.ext", "size_mb": 12.4} Error: {"ok": false, "error": "Actionable error message"}

Social Content Workflow

python cli.py extract-audio interview.mp4 -o podcast.mp3 --json
python cli.py audio-normalize podcast.mp3 -o podcast-normalized.mp3 --target-lufs -16 --json
python cli.py resize interview.mp4 --width 1080 --height 1920 --fit crop -o vertical.mp4 --json

All commands are non-destructive (never modify the input file). Output directories auto-created.