ffmpeg
Probe, trim, transcode, concat, and extract local A/V with ffmpeg/ffprobe. Use when converting or inspecting media files. NOT for AI image generation (draw-thing) or UI design (design).
How do I install this agent skill?
npx skills add https://github.com/wyattowalsh/agents --skill ffmpegIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is generally safe but processes untrusted media metadata which provides a surface for indirect prompt injection.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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.pyon every source file before trim, transcode, concat, extract-audio, thumbnail, or gif. Use probe fields to choose maps, codecs, and duration bounds. Seereferences/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.mdandreferences/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
- Run
uv run python scripts/doctor.py --format json. - Report
checksstatuses and remediation for anyfail. - Do not run ffmpeg mutations when
ffmpeg-binaryorffprobe-binaryfails.
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.mdwhen interpreting rotation, multi-track audio, or subtitle streams.
Trim
- Probe source; validate
start/endagainstduration_seconds. - Prefer stream copy when keyframe alignment is acceptable; otherwise use re-encode trim recipe.
- Output to
basename.trim.extor 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 +faststartfor 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.mp4path. - Load
references/recipes-trim-transcode.md.
Extract audio
- Probe source; fail gracefully when
stream_counts.audiois zero. - Choose MP3, M4A, or copy recipe based on target format.
- Write
basename.audio.extas 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.gifand optionalpalette.pngas 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:
| # | 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:
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)
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/wyattowalsh/agents/ffmpeg">View ffmpeg on skillZs</a>