Ffmpeg

ffmpeg Workbench

Transform media with a disciplined loop: probe the environment → probe the input → transform → verify the output. Never assume; always measure.

The core loop

1. Probe the environment (once per session)

Before the first ffmpeg operation in a session, run:

node "${CLAUDE_PLUGIN_ROOT}/skills/ffmpeg/scripts/probe_env.mjs"

(${CLAUDE_PLUGIN_ROOT} is exported by Claude Code for plugin skills. If it's unset — e.g. this skill is running outside the plugin runtime — substitute this skill's own directory for the path prefix.)

It prints JSON: ffmpeg/ffprobe versions, which encoders are actually compiled in (libx264, libx265, libsvtav1, libopus, aac, ...), and available hardware acceleration (videotoolbox, cuda, qsv, vaapi). If ffmpeg is missing it prints per-OS install commands — relay them and stop.

Use the result to pick encoders. Never emit a command using an encoder the probe didn't confirm. If hardware acceleration is available and the task is a big re-encode, offer it (see references/encoding.md → Hardware acceleration), noting the quality/size trade-off vs software encoding.

2. Probe the input

Before transforming any file:

ffprobe -v error -print_format json -show_format -show_streams "input.ext"

Read duration, resolution, codecs, rotation metadata, audio channels/sample rate. Decisions that depend on this: whether -c copy is possible, whether scaling is needed, whether the source has audio at all, and which concat method is valid.

3. Transform

Pick the recipe. Non-negotiable correctness rules (these fix real-world failures):

• Even dimensions: with libx264/libx265 use scale=-2:720 (never -1) so the computed side is divisible by 2. Odd widths abort the encode.
• Audio-aware speed changes: pair setpts with atempo. atempo accepts 0.5–100 per instance; chain for values outside (e.g. 4x = atempo=2.0,atempo=2.0). Never silently drop audio with -an unless the user asked.
• No -strict experimental for AAC — obsolete since ffmpeg 3.0. Plain -c:a aac is correct.
• Never overwrite blind: default to a new output name (input_converted.mp4). Only pass -y if the user explicitly approved overwriting.
• Quote every path. Assume spaces and unicode.
• Stream copy when possible: if only the container changes, or trimming at keyframes is acceptable, use -c copy — instant and lossless. Re-encode only when filters, codec change, or frame-accurate cuts require it.
• Web output: add -movflags +faststart to any MP4 destined for browsers/upload.
• Portable shell: no process substitution <(...). For concat lists, write a temp file and delete it after.
• Long operations: for inputs over ~5 minutes of re-encode, first do a 10-second test slice (-t 10) to validate settings, then run the full job with -nostats -loglevel warning (or -progress) so output stays readable.

Recipe references — read the one that matches the task:

Task	Read
Convert, compress, resize, quality/CRF, HEVC/AV1, hardware accel	references/encoding.md
Trim, cut, concat/merge, speed change, rotate	references/edit-and-concat.md
GIFs, thumbnails, frame extraction, image↔video	references/gif-and-frames.md
Audio: extract, convert, replace, mix, normalize	references/audio.md
Subtitles: burn-in, soft subs, extract	references/subtitles.md
Platform packaging (YouTube/Instagram/TikTok/X)	references/platform-presets.md

4. Verify

Every produced file gets checked before you declare success:

node "${CLAUDE_PLUGIN_ROOT}/skills/ffmpeg/scripts/verify_output.mjs" output.mp4 \
  --expect-vcodec h264 --expect-duration 30 --duration-tolerance 0.5 \
  --expect-width 1280 --expect-height 720

Pass only the expectations relevant to the task (all flags optional; with none it just confirms the file is readable media and prints its properties). Exit code 0 = verified. On failure, read the JSON diagnostics, fix the command, re-run. Report the verified facts to the user (duration, resolution, codecs, size, and size delta vs input for compression jobs) — not just "done".

5. Batch jobs

For "convert all X in this directory": probe one representative file, validate the recipe on it end-to-end (including verify), then loop over the rest with a for loop, running verify on each output and reporting a pass/fail summary. Continue past individual failures; list them at the end.

Scope boundaries

This skill transforms media. If the user wants Claude to understand video content (summarise, describe frames, transcribe), that's a video-analysis job — do frame extraction here only as a mechanical step if asked, but recommend a dedicated analysis workflow for the understanding part.