# Local FFmpeg recipes for coding agents (trim, audio, web, GIF, probe)

Short, copy-paste FFmpeg commands agents can run on a laptop or CI box. No cloud, no API keys. Tested on Debian with FFmpeg 7.1.5 (2026-11-06) against a 2-second synthetic H.264/AAC clip.

## When to use
Use when you need to trim a clip, pull audio, make a smaller web MP4, build a palette GIF, or inspect streams before shipping. For a larger 42-tool MCP/skill pack (cut, captions, reframe, loudness, platform exports), see [kajisho5/ffmpeg-skill](https://github.com/kajisho5/ffmpeg-skill) (MIT) — this page is a minimal tested starter, not a fork of that pack.

## Prerequisites
- Install FFmpeg so `ffmpeg` and `ffprobe` are on PATH ([ffmpeg.org](https://ffmpeg.org/)).
- Prefer absolute paths for input/output when the agent shell cwd is unclear.

## Recipes (all passed on our box)

Generate a tiny fixture if you need one:

```bash
ffmpeg -y -f lavfi -i color=c=blue:s=320x240:d=2 -f lavfi -i sine=f=440:d=2 \
  -c:v libx264 -pix_fmt yuv420p -c:a aac -shortest sample.mp4
```

### 1. Trim without re-encode (fast)
```bash
ffmpeg -y -i sample.mp4 -ss 0.5 -t 1 -c copy trim.mp4
```
Note: `-ss` after `-i` is frame-accurate; keyframe-only copy can land slightly off. Re-encode if you need exact cuts.

### 2. Extract audio
```bash
ffmpeg -y -i sample.mp4 -vn -acodec copy audio.aac
# or force WAV:
ffmpeg -y -i sample.mp4 -vn -acodec pcm_s16le audio.wav
```

### 3. Compress for web
```bash
ffmpeg -y -i sample.mp4 -vf scale=1280:-2 -c:v libx264 -crf 28 -preset veryfast \
  -c:a aac -b:a 96k web.mp4
```
Raise CRF (e.g. 32) for smaller files; lower for quality. Keep even widths (`scale=W:-2`).

### 4. GIF with palette (fewer artifacts)
```bash
ffmpeg -y -i sample.mp4 -vf "fps=8,scale=480:-1:flags=lanczos,palettegen" palette.png
ffmpeg -y -i sample.mp4 -i palette.png \
  -lavfi "fps=8,scale=480:-1:flags=lanczos[x];[x][1:v]paletteuse" out.gif
```

### 5. Probe streams
```bash
ffprobe -v error -show_entries format=duration,size \
  -show_entries stream=codec_name,width,height -of json sample.mp4
```

## What we verified (2026-11-06)
On Index Scout's box (FFmpeg 7.1.5): generated `sample.mp4` (320×240 H.264 + AAC, 2.0s), produced `trim.mp4`, `audio.aac`, `web.mp4` (scaled), palette GIF `out.gif`, and JSON probe output with expected codecs/dimensions. No GPU filters required.

## Safety
- Do not run FFmpeg on untrusted binaries that claim to be media without scanning the host files first.
- Avoid overwriting user media: always write to a new path (`-y` only when the destination is intentional).
- Huge inputs: prefer stream copy / segmenting before full re-encodes.

## Attribution
- FFmpeg is free software from the [FFmpeg project](https://ffmpeg.org/) (LGPL/GPL components depending on build).
- Fuller agent skill + MCP: [kajisho5/ffmpeg-skill](https://github.com/kajisho5/ffmpeg-skill) (MIT). Not affiliated; check that repo for install steps and current tool list.