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

Term	Meaning	NOT
probe	Read-only ffprobe inspection	transcode
trim	Shorten by time range	crop UI mockup
transcode	Re-mux or re-encode to new container/codec	generate new imagery
concat	Join multiple inputs sequentially	merge git branches
extract-audio	Strip video, keep audio track	speech-to-text
thumbnail	Single still frame from video	design a poster layout
gif	Animated GIF preview from video clip	CSS animation
stream copy	`-c copy` without re-encode	always safe for all trims
recipe	Approved command template from `references/`	ad-hoc filter graph

Dispatch

`$ARGUMENTS`	Mode	Action
`doctor` / `check` / `preflight`	Doctor	Run PATH doctor; stop if ffmpeg/ffprobe missing
`probe <path>` / `info <path>` / `metadata <path>`	Probe	Run probe helper; summarize streams and duration
`trim <path> <start> <end>` / `clip <path> ...`	Trim	Probe, pick copy vs re-encode recipe, new output path
`transcode <path>` / `convert <path> to mp4`	Transcode	Probe codecs; apply H.264/AAC or copy recipe
`concat <file1> <file2> [...]` / `join ...`	Concat	Verify probes; concat demuxer recipe + new output
`extract-audio <path>` / `audio <path>`	Extract audio	Probe audio stream; MP3/M4A/copy recipe
`thumbnail <path>` / `thumb <path> [timestamp]`	Thumbnail	Seek frame; write JPG/PNG to new path
`gif <path>` / `animate <path> [start] [duration]`	GIF	Palette GIF recipe with duration cap
Path to media + natural language edit intent	Auto	Classify trim/transcode/thumbnail/gif from intent
(empty)	Help	Show modes, critical rules, script commands, references

Auto-Detection Heuristic

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

Critical Rules

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
```
.
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
```
.
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:

bash

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

Stop when JSON

ok

is false. Install guidance:

bash

brew install ffmpeg

For each input file:

bash

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

Run

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

Report
```
checks
```
statuses and remediation for any
```
fail
```
.
Do not run ffmpeg mutations when
```
ffmpeg-binary
```
or
```
ffprobe-binary
```
fails.

Probe

Require a readable local file path.

Run

uv run python scripts/probe_media.py <path>

Summarize: container, duration, video/audio codecs, resolution, stream counts.
Load
```
references/probe-fields.md
```
when interpreting rotation, multi-track audio, or subtitle streams.

Trim

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

Transcode

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

Concat

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

Extract audio

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

Thumbnail

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

GIF

Probe source; cap duration (default max 5s unless user expands).
Use two-pass palette recipe for quality; single-pass only for quick previews.
Write
```
clip.gif
```
and optional
```
palette.png
```
as new files.
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:


/ffmpeg doctor
/ffmpeg probe ~/Movies/clip.mp4
/ffmpeg trim ~/Movies/clip.mp4 00:00:05 00:00:15
/ffmpeg transcode ~/Movies/clip.mov
/ffmpeg concat part1.mp4 part2.mp4
/ffmpeg extract-audio ~/Movies/clip.mp4
/ffmpeg thumbnail ~/Movies/clip.mp4 00:00:03
/ffmpeg gif ~/Movies/clip.mp4 00:00:02 4

#	Task	Example
1	Preflight tooling	`/ffmpeg doctor`
2	Inspect metadata	`/ffmpeg probe ~/Movies/clip.mp4`
3	Trim a clip	`/ffmpeg trim ~/Movies/clip.mp4 00:00:05 00:00:15`
4	Transcode container	`/ffmpeg transcode ~/Movies/clip.mov`
5	Join segments	`/ffmpeg concat part1.mp4 part2.mp4`
6	Extract audio	`/ffmpeg extract-audio ~/Movies/clip.mp4`
7	Poster frame	`/ffmpeg thumbnail ~/Movies/clip.mp4 00:00:03`
8	GIF preview	`/ffmpeg gif ~/Movies/clip.mp4 00:00:02 4`

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

Skill Awareness

Signal	Redirect
"generate an image", "txt2img", "AI video", local Draw Things	`draw-thing`
"design a landing page", "Figma", "React layout"	`design`
"download from YouTube/URL"	`yt-dlp`
Live streaming, RTMP, OBS wiring	out of scope — suggest streaming docs

Reference Files

File	Load when
`references/safety.md`	Any mutation; in-place overwrite questions
`references/probe-fields.md`	Interpreting probe JSON
`references/recipes-trim-transcode.md`	trim, transcode, concat, extract-audio
`references/recipes-thumbnail-gif.md`	thumbnail, gif

Scripts

Script	Purpose
`scripts/doctor.py`	Verify ffmpeg/ffprobe on PATH ( `--format json` )
`scripts/probe_media.py`	ffprobe wrapper with summary ( `--raw` for full payload)
`scripts/check.py`	Validate SKILL.md, evals, package dry-run, audit

Validation:

bash

uv run python scripts/check.py

Reporting Template

After any mutation, report:

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

ffmpeg

NPX Install

Tags

SKILL.md Content

FFmpeg

Canonical Vocabulary

Dispatch

Auto-Detection Heuristic

Critical Rules

Prerequisite Protocol

Mode Protocols

Doctor

Probe

Trim

Transcode

Concat

Extract audio

Thumbnail

GIF

Help (empty)

Gallery (Empty Arguments)

Skill Awareness

Reference Files

Scripts

Reporting Template