ffmpeg

Files (2)

• SKILL.md
• recipes.md · references/

SKILL.md (first lines)

# FFmpeg Skill for Computer-Use Agents

Process media files with ffmpeg and ffprobe. This skill adds agent-specific safety rules and decision logic on top of ffmpeg knowledge the model already has.

For additional recipes (convert, remux, extract audio, replace audio, remove audio, GIF, subtitles, overlays, and more), see `references/recipes.md`.

---

## Safety Policy

### No-overwrite default

Use `-n` unless the user explicitly asks to overwrite.

```bash
ffmpeg -n -i "$INPUT" [output options] "$OUTPUT"
```

If overwriting is explicitly requested, use `-y`.

### Temp-file workflow

Write to a temporary file with the same extension as the intended output, verify, then rename:

```bash
# Derive temp path preserving the target extension
TMP_OUTPUT="${OUTPUT%.*}.tmp.${OUTPUT##*.}"

ffmpeg -n -i "$INPUT" [output options] "$TMP_OUTPUT" &&
ffprobe -v error "$TMP_OUTPUT" &&
mv "$TMP_OUTPUT" "$OUTPUT"
```

### Other rules

- Quote all file paths.
- Only use local file paths with `-i`. Do not pass user-supplied URLs directly to ffmpeg/ffprobe without validating the protocol (stick to `file://` or bare paths).
- Do not delete the input file unless the user explicitly requests it.
- After generating output, verify with `ffprobe`.
- Clean up temp directories after successful operations.

---

## Inspect First

Always probe unknown media before complex operations:

```bash
# Human-readable
ffprobe -hide_banner -i "$INPUT"

# Machine-readable JSON
ffprobe -v error -show_format -show_streams -of json "$INPUT"

# Quick queries
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$INPUT"          # duration
ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=s=x:p=0 "$INPUT"        # resolution
ffprobe -v error -show_entries stream=index,codec_type,codec_name -of table "$INPUT"                    # codecs
```

---

## Decision Tree: Copy vs Re-encode

### Use `-c copy` when

- Changing container only (e.g. `.mkv` to `.mp4`)
- Removing or extracting a stream
- Approximate keyframe-aligned trim
- Avoiding quality loss

```bash
ffmpeg -n -i "$INPUT" -c copy "$OUTPUT"
```

### Re-encode when

- Resizing, cropping, padding, rotating
- Applying any `-vf` or `-af` filter
- Changing codec, frame rate, or pixel format
- Frame-accurate trim required
- Web/browser compatibility required

### Audio codec decision

| Goal | Audio option |
|------|-------------|
| Preserve source audio exactly | `-c:a copy` (may not be compatible with all containers) |
| Web-compatible MP4 | `-c:a aac -b:a 128k` (always safe) |
| Audio for transcription | `-vn -acodec pcm_s16le -ar 16000 -ac 1` |

When the target is a web-compatible MP4, prefer `-c:a aac` over `-c:a copy` -- copied audio may retain a codec the browser cannot play.

---

## Web-Compatible MP4 Defaults

```bash
ffmpeg -n -i "$INPUT" \
  -c:v libx264 -crf 23 -preset medium -threads 4 \
  -c:a aac -b:a 128k \
  -pix_fmt yuv420p \
  -movflags +faststart \
  "$OUTPUT"
```

Always include `-threads 4` when re-encoding. Without it, ffmpeg uses all CPU cores, which causes severe contention when multiple agents run concurrently.

| Profile | Codec | CRF | Preset | Audio | Notes |
|---------|-------|-----|--------|-------|-------|
| General (default) | libx264 | 23 | medium | aac 128k | Best compatibility |
| High quality | libx264 | 18 | slow | aac 192k | Archival, mastering |
| Smaller file | libx264 | 28 | medium | aac 96k | |
| Minimum size | libx264 | 32 | slow | aac 64k | |
| Modern smaller MP4 | libx265 | 24 | medium | aac 128k | Add `-vtag hvc1`; less compatible, smaller files |
| WebM/VP9 | libvpx-vp9 | 15 | n/a | libopus | Add `-b:v 0`; web-native, slow encode |

When the user does not specify a codec, default to H.264 (libx264). Use H.265/VP9 only when the user asks for smaller files or specifies these codecs.

From Matrixx0070/xclaw, MIT.

More from Matrixx0070/xclaw