Ffmpeg

FFmpeg

CLI skill for local audio/video inspection and transformation via ffmpeg and ffprobe. Invoke as /ffmpeg.

Scope: Probe metadata, trim clips, transcode containers/codecs, concatenate segments, extract audio, capture thumbnails, and build GIF previews from files on disk. NOT for AI image or video generation (draw-thing), UI or layout design (design), networked downloads (yt-dlp), or broadcast/streaming pipelines.

Canonical Vocabulary

Dispatch

Auto-Detection Heuristic

1. Install/tooling doubt → Doctor.
2. "metadata", "codec", "duration", "how long", "what format" → Probe.
3. "cut", "clip", "from ... to ...", time range → Trim.
4. "mp4", "webm", "h264", "aac", "smaller", "compress" → Transcode.
5. "join", "merge clips", "append videos" → Concat.
6. "mp3", "wav", "m4a", "strip video", "audio only" → Extract audio.
7. "poster frame", "screenshot", "still", "thumbnail" → Thumbnail.
8. "gif", "animated preview" → GIF.
9. Generative image/video language → refuse; redirect to draw-thing.
10. UI/page/layout design → refuse; redirect to design.
11. Ambiguous → ask which mode and state copy vs re-encode tradeoff.

Critical Rules

1. Probe before mutate — run probe_media.py on every source file before trim, transcode, concat, extract-audio, thumbnail, or gif. Use probe fields to choose maps, codecs, and duration bounds. See references/probe-fields.md.
2. Never overwrite in-place (default) — always write to a new output path. In-place replace requires explicit user approval plus backup/temp-file replace. See references/safety.md.
3. Recipe-only mutations — build ffmpeg commands only from references/recipes-trim-transcode.md and references/recipes-thumbnail-gif.md. No improvised filter chains or destructive batch jobs without approval.

Prerequisite Protocol

Run before any mutation:

uv run python scripts/doctor.py --format json

Stop when JSON ok is false. Install guidance:

brew install ffmpeg

For each input file:

uv run python scripts/probe_media.py /absolute/path/to/input.mp4

Parse summary.duration_seconds, summary.stream_counts, and codec fields before selecting a recipe.

Mode Protocols

Doctor

1. Run uv run python scripts/doctor.py --format json.
2. Report checks statuses and remediation for any fail.
3. Do not run ffmpeg mutations when ffmpeg-binary or ffprobe-binary fails.

Probe

1. Require a readable local file path.
2. Run uv run python scripts/probe_media.py <path>.
3. Summarize: container, duration, video/audio codecs, resolution, stream counts.
4. Load references/probe-fields.md when interpreting rotation, multi-track audio, or subtitle streams.

Trim

1. Probe source; validate start/end against duration_seconds.
2. Prefer stream copy when keyframe alignment is acceptable; otherwise use re-encode trim recipe.
3. Output to basename.trim.ext or user-provided new path.
4. Load references/recipes-trim-transcode.md.

Transcode

1. Probe source; decide copy vs H.264/AAC re-encode.
2. Map explicit streams when multiple tracks exist.
3. Include -movflags +faststart for MP4 web delivery unless user forbids.
4. Load references/recipes-trim-transcode.md.

Concat

1. Probe every segment; confirm compatible codecs/resolution for copy concat.
2. Build concat list file with absolute paths; never concat unrelated codecs with copy without warning.
3. Output to a new *.concat.mp4 path.
4. Load references/recipes-trim-transcode.md.

Extract audio

1. Probe source; fail gracefully when stream_counts.audio is zero.
2. Choose MP3, M4A, or copy recipe based on target format.
3. Write basename.audio.ext as a new file.
4. Load references/recipes-trim-transcode.md.

Thumbnail

1. Probe source; require at least one video stream.
2. Pick timestamp (user value, or 10% duration clamped 1–10s).
3. Write JPG/PNG under OUTPUT/ or sibling path — never overwrite source.
4. Load references/recipes-thumbnail-gif.md.

GIF

1. Probe source; cap duration (default max 5s unless user expands).
2. Use two-pass palette recipe for quality; single-pass only for quick previews.
3. Write clip.gif and optional palette.png as new files.
4. Load references/recipes-thumbnail-gif.md.

Help (empty)

Show dispatch table, critical rules, doctor/probe commands, reference index, and the gallery below.

Gallery (Empty Arguments)

Present common local media tasks when $ARGUMENTS is empty:

Pick a number, a mode from the dispatch table, or paste a file path and describe the edit.

Skill Awareness

Reference Files

Scripts

Validation:

uv run python scripts/check.py

Reporting Template

After any mutation, report:

1. Doctor status (if run this session)
2. Probe summary (duration, codecs, streams)
3. Recipe name (copy vs re-encode)
4. Exact ffmpeg command(s) executed
5. Output path(s) and size change
6. Caveats (keyframe trim, missing audio, GIF duration cap)