ffmpeg

# ffmpeg Transform audio and video files with [`ffmpeg`](https://ffmpeg.org/) 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 <format>", "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 1. Always write to a NEW output path; never overwrite the source. 2. Inspect with `ffprobe` first when unsure of codecs/duration/resolution. 3. Warn the user that long re-encodes can take a while; prefer `-c copy` when only the container changes. 4. Echo the output path (and `ffprobe` duration if relevant) after each run.