Skip to content
Skills Library
Marketing & content · Conversion & formats

ffmpeg-transcode

/ffmpeg-transcode

Transcode video/audio between codecs and containers with ffmpeg (H.264, HEVC, AV1, VP9, ProRes, AAC, Opus; MP4, MKV, WebM, MOV). Use when the user asks to convert a video, change codec, re-encode, reduce file size with CRF, target a bitrate, do 2-pass encoding, change container, or make a file web/mobile/social-media compatible.

Repository
media-os ↗
Licence
MIT
Last repository change
17.05.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.05.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/transcode.py

What it does and when to use it

Transcode video/audio between codecs and containers with ffmpeg (H.264, HEVC, AV1, VP9, ProRes, AAC, Opus; MP4, MKV, WebM, MOV). Use when the user asks to convert a video, change codec, re-encode, reduce file size with CRF, target a bitrate, do 2-pass encoding, change container, or make a file web/mobile/social-media compatible.

Arguments

/ffmpeg-transcode [input] [target-format]
Original author description

Transcode video/audio between codecs and containers with ffmpeg (H.264, HEVC, AV1, VP9, ProRes, AAC, Opus; MP4, MKV, WebM, MOV). Use when the user asks to convert a video, change codec, re-encode, reduce file size with CRF, target a bitrate, do 2-pass encoding, change container, or make a file web/mobile/social-media compatible.

How it works

  1. Quick start
  2. When to use
  3. Step 1 — Pick container + codecs (and decide remux vs re-encode)
  4. Step 2 — Choose rate control
  5. Step 3 — Build the command
  6. Step 4 — Verify output
  7. Gotchas
  8. Examples
  9. Troubleshooting
  10. Reference docs
Original SKILL.md headings · 277 lines, 1,586 words
SKILL.md preview
---
name: ffmpeg-transcode
description: >
  Transcode video/audio between codecs and containers with ffmpeg (H.264, HEVC, AV1, VP9, ProRes, AAC, Opus; MP4, MKV, WebM, MOV). Use when the user asks to convert a video, change codec, re-encode, reduce file size with CRF, target a bitrate, do 2-pass encoding, change container, or make a file web/mobile/social-media compatible.
argument-hint: "[input] [target-format]"
---

# Ffmpeg Transcode

**Context:** $ARGUMENTS

## Quick start

- **Web MP4 (H.264 + AAC, most compatible):** → Step 3, recipe A
- **Change container only, keep codecs:** → Step 1 (remux path)
- **Smaller file at same quality (HEVC/AV1):** → Step 3, recipes B / C

## When to use

- User says "convert", "re-encode", "transcode", "change format", "make smaller".
- Target codec differs from source, OR target container doesn't support source codec.
- CRF / bitrate / 2-pass / preset tuning for size vs quality.
- For GPU encoding use `ffmpeg-hwaccel`; for trimming/joining use `ffmpeg-cut-concat`;
  for filters/scaling use `ffmpeg-video-filter`; for raw inspection use `ffmpeg-probe`.

## Step 1 — Pick container + codecs (and decide remux vs re-encode)

First probe the input:

```bash
ffprobe -v error -show_entries stream=index,codec_type,codec_name,pix_fmt,profile,channels,sample_rate -of json "$IN"
```

**Decision tree:**

1. If the user only wants a different container AND the source codecs are supported
   by the target container (see matrix below), **remux** — no quality loss, fast:
   ```bash
   ffmpeg -i in.mkv -c copy -map 0 out.mp4
   ```
   Caveats: H.264/HEVC in raw `.ts` vs `.mp4` need a bitstream filter — see
   `ffmpeg-bitstream`. AAC from `.ts` → `.mp4` needs `aac_adtstoasc`.
2. If codecs are incompatible with the target container (e.g. Opus → MP4 is
   technically allowed but fragile; FLAC → MP4 not allowed), re-encode that stream only.
3. Otherwise full re-encode — continue to Step 2.

**Container → codec compatibility matrix:**

| Container | Video codecs (common)              | Audio codecs (common)            | Subtitles        |
|-----------|------------------------------------|----------------------------------|------------------|
| MP4 / M4V | H.264, HEVC, AV1, MPEG-4           | AAC, ALAC, AC3, MP3 (avoid Opus) | mov_text only    |
| MOV       | H.264, HEVC, ProRes, DNxHD         | AAC, PCM, ALAC                   | mov_text         |
| MKV       | anything                           | anything                         | SRT/ASS/PGS/...  |
| WebM      | VP8, VP9, AV1 only                 | Vorbis, Opus only                | WebVTT           |

If unsure which codec to pick, default to **H.264 + AAC in MP4** — works on every
browser, every phone, every social platform.

## Step 2 — Choose rate control

Three modes, pick exactly one per video encode:

- **CRF (constant quality)** — best default. Pick a target quality; filesize varies
  with content. Use when output size doesn't have to be exact.
- **Bitrate target** — `-b:v 5M`. Single pass is fine for live/streaming targets;
  otherwise 2-pass is higher quality at the same size.
- **2-pass** — use when you must hit a specific size (e.g. Twitter 512MB, Discord 25MB).
  Two ffmpeg invocations; first pass writes stats to `ffmpeg2pass-*.log`.

**CRF typical ranges (NOT comparable across codecs):**

| Encoder      | Sane CRF range | Visually-lossless-ish | Notes                                     |
|--------------|----------------|-----------------------|-------------------------------------------|
| libx264      | 18–28 (default 23) | 17–18             | `-crf 0` = mathematically lossless        |
| libx265      | 20–28 (default 28) | 18–20             | `-crf 0` = lossless                        |
| libsvtav1    | 25–40 (default 35) | 20–25             | Higher numbers than x264 for same quality |
| libaom-av1   | 25–40 (set `-b:v 0 -crf N` for CRF) | 20–25 | Slow; prefer libsvtav1 |
| libvpx-vp9   | 24–37 (set `-b:v 0 -crf N`)          | 15–23 | Must pass `-b:v 0` to enable constant-quality |

**2-pass recipe (size-targeted):**

```bash
# Pass 1: analyse only, no audio, discard output
ffmpeg -y -i "$IN" -c:v libx264 -b:v 5M -preset medium \
       -pass 1 -an -f null /dev/null

# Pass 2: real encode, reuse stats
ffmpeg -i "$IN" -c:v libx264 -b:v 5M -preset medium \
       -pass 2 -c:a aac -b:a 128k \
       -movflags +faststart "$OUT"
```

Compute `-b:v` from a size budget: `bitrate_bps = target_size_bits / duration_seconds − audio_bps`.

## Step 3 — Build the command

**Recipe A — Web MP4 (default go-to):**

```bash
ffmpeg -i "$IN" \
  -c:v libx264 -preset medium -crf 20 \
  -pix_fmt yuv420p \
  -c:a aac -b:a 128k -ac 2 \
  -movflags +faststart \
  "$OUT.mp4"
```

**Recipe B — HEVC in MKV (archive / smaller size):**

```bash
ffmpeg -i "$IN" \
  -c:v libx265 -preset medium -crf 22 \
  -pix_fmt yuv420p10le \
  -c:a libopus -b:a 128k \
  "$OUT.mkv"
```

Put HEVC in MP4 instead by adding `-tag:v hvc1` (Apple/QuickTime requires it).

**Recipe C — AV1 in MP4 (modern web / YouTube-style):**

```bash
ffmpeg -i "$IN" \
  -c:v libsvtav1 -preset 6 -crf 30 \
  -pix_fmt yuv420p10le \
  -c:a libopus -b:a 96k \
  -movflags +faststart \
  "$OUT.mp4"
```

(Use `-preset 4` for better quality / slower, `-preset 8` for faster / larger.)

**Recipe D — WebM (VP9 + Opus):**

```bash
ffmpeg -i "$IN" \
  -c:v libvpx-vp9 -b:v 0 -crf 32 -row-mt 1 -cpu-used 2 \
  -pix_fmt yuv420p \
  -c:a libopus -b:a 96k \
  "$OUT.webm"
```

**Recipe E — ProRes for editing (MOV):**

```bash
ffmpeg -i "$IN" \
  -c:v prores_ks -profile:v 3 -pix_fmt yuv422p10le \
  -c:a pcm_s16le \
  "$OUT.mov"
```

Profiles: 0=proxy, 1=lt, 2=standard, 3=hq, 4=4444, 5=4444xq.

**Stream selection (`-map`):**

```bash
# Keep video 0 + audio 1 only, drop all subs:
ffmpeg -i "$IN" -map 0:v:0 -map 0:a:1 -c:v libx264 -crf 20 -c:a aac "$OUT"
# Preserve all streams + copy metadata + copy chapters:
ffmpeg -i "$IN" -map 0 -map_metadata 0 -map_chapters 0 -c copy "$OUT"
```

**Preset runner:**

```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/transcode.py \
  --input "$IN" --output "$OUT" --preset web-mp4
```

Presets: `web-mp4` (H.264/AAC MP4), `hevc-mkv`, `web-webm`, `av1-mp4`, `prores`, `archive`.

## Step 4 — Verify output

```bash
ffprobe -v error -show_format -show_streams -of json "$OUT" | jq '.format.duration, .streams[].codec_name'
```

Check:
- Duration roughly matches input (within ~0.1s, short container padding is normal).
- Video `codec_name` + audio `codec_name` are what you asked for.
- `pix_fmt` is `yuv420p` if you need browser/phone playback.
- For MP4: `ffprobe -v trace ... 2>&1 | head | grep moov` should show moov atom early
  (or simply: the file starts playing instantly in a browser = faststart worked).

## Gotchas

- **`yuv420p` is required** for broad playback (browsers, iOS, most TVs). ProRes captures
  and RGB sources often land on `yuv444p`/`yuv422p` — always add `-pix_fmt yuv420p`
  for web output, or `yuv420p10le` for 10-bit HDR-ish HEVC/AV1.
- **`-movflags +faststart` is MP4/MOV only.** Does nothing for MKV/WebM. Without it,
  web players have to download the whole file before playback starts.
- **Stream copy across containers may need a bitstream filter** (e.g. H.264 MP4 → TS,
  AAC TS → MP4). See the `ffmpeg-bitstream` skill.
- **CRF values are NOT comparable across codecs.** x264 crf 23 ≠ x265 crf 23 ≠ av1 crf 23.
  Use the table in Step 2.
- **`-crf 0` is lossless only for libx264 / libx265.** For AV1 / VP9 it's the best-quality
  CRF value but still lossy. For true lossless VP9 use `-lossless 1`.
- **`-b:v` is ignored when `-crf` is set** on libx264/libx265 unless you also pass
  `-maxrate`/`-bufsize` (then CRF becomes a capped-CRF ceiling). Pick one mode.
- **Audio must be re-encoded when container doesn't support source codec** — e.g. Opus
  in MP4 is shaky, FLAC in MP4 is unsupported, AAC in WebM is unsupported.
  Re-encode the audio even if you're copying video: `-c:v copy -c:a aac -b:a 128k`.
- **HEVC in MP4 needs `-tag:v hvc1`** to play on Apple QuickTime / Safari / iOS.
- **2-pass requires matching `-b:v` and `-preset` between the two passes.** Stats log
  is per-working-directory — run both passes from the same cwd.
- **libfdk_aac is non-free** and absent from most ffmpeg builds. Use the native `aac`
  encoder unless you know your build has fdk.

## Examples

### Example 1: "Make this MOV playable in browsers"

```bash
ffmpeg -i in.mov -c:v libx264 -preset medium -crf 20 -pix_fmt yuv420p \
       -c:a aac -b:a 128k -movflags +faststart out.mp4
```

### Example 2: "Shrink a 4GB recording for Discord (25MB cap)"

Duration 10 min = 600s. Budget: 25 MB × 8 / 600s ≈ 333 kbps total. Reserve 64k audio,
leave 260k video. 2-pass mandatory at that ratio:

```bash
ffmpeg -y -i in.mp4 -c:v libx264 -b:v 260k -preset slow -pass 1 -an -f null /dev/null
ffmpeg    -i in.mp4 -c:v libx264 -b:v 260k -preset slow -pass 2 \
          -c:a aac -b:a 64k -ac 1 -movflags +faststart out.mp4
```

### Example 3: "Change MKV container to MP4 without re-encoding"

```bash
ffprobe in.mkv            # confirm codecs are H.264/HEVC + AAC/AC3
ffmpeg -i in.mkv -c copy -map 0 -movflags +faststart out.mp4
```

If subtitle streams are SRT/ASS, add `-map 0:v -map 0:a` to drop them (MP4 only takes
mov_text) or add `-c:s mov_text` to convert.

### Example 4: "Archive master to HEVC 10-bit"

```bash
ffmpeg -i master.mov -c:v libx265 -preset slow -crf 18 -pix_fmt yuv420p10le \
       -x265-params "profile=main10" \
       -c:a flac -compression_level 8 archive.mkv
```

## Troubleshooting

### Error: `Could not find tag for codec opus in stream #1, codec not currently supported in container`

Cause: Opus audio in MP4 isn't universally supported by ffmpeg's MP4 muxer.
Solution: Use MKV/WebM, or re-encode audio to AAC: `-c:a aac -b:a 128k`.

### Error: `[libx264 @ ...] height not divisible by 2`

Cause: libx264 with yuv420p requires even dimensions.
Solution: Add `-vf "scale=trunc(iw/2)*2:trunc(ih/2)*2"` or an explicit even target.

### Output plays but browsers won't start until fully downloaded

Cause: moov atom at end of MP4.
Solution: Add `-movflags +faststart`. (MP4/MOV only.)

### Output has green / purple tint on iOS

Cause: `yuv444p` or `yuv422p` pixel format.
Solution: Add `-pix_fmt yuv420p`.

### HEVC MP4 won't play on Apple devices

Cause: tag is `hev1` instead of `hvc1`.
Solution: Re-mux with `ffmpeg -i in.mp4 -c copy -tag:v hvc1 out.mp4`.

### "Unknown encoder 'libfdk_aac'"

Cause: build doesn't include non-free fdk.
Solution: Swap `libfdk_aac` → `aac` (native encoder is fine for ≥128 kbps stereo).

## Reference docs

- Deep per-encoder options (presets, tunes, profiles, levels, AV1/VP9 tile options,
  Opus application modes, pixel-format & color cheat sheet) → `references/codecs.md`.
Files in this package (3)
  • SKILL.md 11 KB
  • references/codecs.md 15 KB
  • scripts/transcode.py 6 KB

Versions

The database has no other skills named ffmpeg-transcode.

Database snapshot: 13.11.2026 · package version 62a1f9749e2c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ffmpeg
    Transcode, convert, edit, and process audio and video with FFmpeg. Use when a user asks to convert video formats (webm to mp4, mkv to mp4), extract audio from video, compress video files, trim or cut clips, concatenate videos, add subtitles, create thumbnails, apply filters,…
  • 100ffmpeg-processing
    Professional video and audio processing - transcode, edit, stream, and analyze media files. Use when transcoding, editing, streaming, or analysing video and audio files.
  • 100web-video
    Encode a video for the web with a bundled ffmpeg script: AV1, HEVC, and H.264 MP4s plus a JPEG poster for ordinary video, or VP9 WebM and HEVC with alpha plus a PNG poster for transparent video, picked from the source automatically. Use when the user wants to optimize, compress,…
  • 100ffmpeg
    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).
  • 100processing-video
    Audio and video processing with ffmpeg. Use when: user asks to convert, trim, merge, compress, or transcode video or audio files; extract audio from video; create GIFs or animated WebP from video; add subtitles or watermarks to video; change video resolution, framerate, or…
  • 100video-compression
    Compress video files to a much smaller size without visible quality loss, using HEVC and ffmpeg (or macOS avconvert), with verification and the original left untouched. Use when the user asks to compress, shrink, reduce, or resize a video, make a video smaller, fit it under a…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.