ffmpeg
Transform audio and video files with ffmpeg and inspect
them with ffprobe. Operations are non-destructive: always write to a new
output file. Re-encoding can be slow on long media — set realistic expectations.
Setup health check (run first, every session)
Verify with one solo step:
[{ "tool": "os.shell.run", "args": { "cmd": "ffmpeg", "args": ["-version"] } }]
Outcome map:
exit 0 + version → ready, proceed.command not found: ffmpeg → enter Setup playbook → "ffmpeg missing".
Setup playbook (when prerequisites are missing)
ffmpeg missing
Reply (solo reply step):
"ffmpeg is not installed. I can install it: brew install ffmpeg. Install it?"
On yes:
[{ "tool": "os.shell.run", "args": { "cmd": "brew", "args": ["install", "ffmpeg"] } }]
On Linux: apt-get install ffmpeg.
When to use
- "Convert this video/audio to ", "extract the audio from this mp4".
- "Trim from 0:30 to 1:00", "resize to 720p", "make a GIF from this clip".
- "What codec / duration / resolution is this file?" (use
ffprobe).
When NOT to use
- Downloading media from URLs — that's
yt-dlp territory (separate skill).
- Still-image editing — use the
imagemagick skill.
- Lossless container-only edits where a remux suffices — still fine here, just
use
-c copy to avoid re-encoding.
Common operations
All examples invoke os.shell.run. Inspect first with ffprobe; the approval
gate surfaces each write. Use -c copy to remux without re-encoding when only
the container changes.
| Goal |
cmd / args |
| Inspect media |
ffprobe ["-hide_banner", "in.mp4"] |
| Convert MOV → MP4 |
ffmpeg ["-i", "in.mov", "-c:v", "libx264", "-c:a", "aac", "out.mp4"] |
| Extract audio (MP3) |
ffmpeg ["-i", "in.mp4", "-vn", "-q:a", "2", "out.mp3"] |
| Trim (start 30s, 30s long) |
ffmpeg ["-ss", "00:00:30", "-i", "in.mp4", "-t", "30", "-c", "copy", "clip.mp4"] |
| Resize to 720p |
ffmpeg ["-i", "in.mp4", "-vf", "scale=-2:720", "out_720p.mp4"] |
| Video → GIF |
ffmpeg ["-i", "in.mp4", "-vf", "fps=12,scale=480:-1", "out.gif"] |
| Extract one frame |
ffmpeg ["-ss", "00:00:05", "-i", "in.mp4", "-frames:v", "1", "frame.png"] |
| Remux only (fast) |
ffmpeg ["-i", "in.mkv", "-c", "copy", "out.mp4"] |
Rules
- Always write to a NEW output path; never overwrite the source.
- Inspect with
ffprobe first when unsure of codecs/duration/resolution.
- Warn the user that long re-encodes can take a while; prefer
-c copy when
only the container changes.
- Echo the output path (and
ffprobe duration if relevant) after each run.
1---2name: ffmpeg3description: Process audio and video with the `ffmpeg` / `ffprobe` CLIs — convert, trim, extract audio, resize, change format, make GIFs, inspect media. Use for any audio/video transformation.4---56# ffmpeg78Transform audio and video files with [`ffmpeg`](https://ffmpeg.org/) and inspect9them with `ffprobe`. Operations are non-destructive: always write to a new10output file. Re-encoding can be slow on long media — set realistic expectations.1112## Setup health check (run first, every session)1314Verify with **one solo step**:1516```17[{ "tool": "os.shell.run", "args": { "cmd": "ffmpeg", "args": ["-version"] } }]18```1920Outcome map:21- `exit 0` + version → ready, proceed.22- `command not found: ffmpeg` → enter **Setup playbook → "ffmpeg missing"**.2324## Setup playbook (when prerequisites are missing)2526### ffmpeg missing2728Reply (solo `reply` step):2930> "`ffmpeg` is not installed. I can install it: `brew install ffmpeg`. Install it?"3132On yes:3334```35[{ "tool": "os.shell.run", "args": { "cmd": "brew", "args": ["install", "ffmpeg"] } }]36```3738On Linux: `apt-get install ffmpeg`.3940## When to use4142- "Convert this video/audio to <format>", "extract the audio from this mp4".43- "Trim from 0:30 to 1:00", "resize to 720p", "make a GIF from this clip".44- "What codec / duration / resolution is this file?" (use `ffprobe`).4546## When NOT to use4748- Downloading media from URLs — that's `yt-dlp` territory (separate skill).49- Still-image editing — use the `imagemagick` skill.50- Lossless container-only edits where a remux suffices — still fine here, just51 use `-c copy` to avoid re-encoding.5253## Common operations5455All examples invoke `os.shell.run`. Inspect first with `ffprobe`; the approval56gate surfaces each write. Use `-c copy` to remux without re-encoding when only57the container changes.5859| Goal | cmd / args |60|---|---|61| Inspect media | `ffprobe` `["-hide_banner", "in.mp4"]` |62| Convert MOV → MP4 | `ffmpeg` `["-i", "in.mov", "-c:v", "libx264", "-c:a", "aac", "out.mp4"]` |63| Extract audio (MP3) | `ffmpeg` `["-i", "in.mp4", "-vn", "-q:a", "2", "out.mp3"]` |64| Trim (start 30s, 30s long) | `ffmpeg` `["-ss", "00:00:30", "-i", "in.mp4", "-t", "30", "-c", "copy", "clip.mp4"]` |65| Resize to 720p | `ffmpeg` `["-i", "in.mp4", "-vf", "scale=-2:720", "out_720p.mp4"]` |66| Video → GIF | `ffmpeg` `["-i", "in.mp4", "-vf", "fps=12,scale=480:-1", "out.gif"]` |67| Extract one frame | `ffmpeg` `["-ss", "00:00:05", "-i", "in.mp4", "-frames:v", "1", "frame.png"]` |68| Remux only (fast) | `ffmpeg` `["-i", "in.mkv", "-c", "copy", "out.mp4"]` |6970## Rules71721. Always write to a NEW output path; never overwrite the source.732. Inspect with `ffprobe` first when unsure of codecs/duration/resolution.743. Warn the user that long re-encodes can take a while; prefer `-c copy` when75 only the container changes.764. Echo the output path (and `ffprobe` duration if relevant) after each run.
AtomicBot-ai