FFmpeg — Reference & Command Toolkit

FFmpeg is a universal media converter: it reads any number of inputs (files, pipes, network streams, capture devices), filters and transcodes them, and writes any number of outputs. This skill is a practitioner's toolkit for constructing correct command lines fast and knowing which option, codec, or filter to reach for.

The full official source text ships with this skill at reference/FFmpeg-Complete-Documentation.md (~1.9 MB). This skill extracts the structure; grep that file or the chapter files for exhaustive option lists.

How to Use This Skill

• No arguments — load the core mental model + the cheatsheet of common commands.
• A task — "trim without re-encoding", "burn subtitles", "capture screen" → I map it to a pattern in patterns.md / cheatsheet.md.
• A topic — "filters", "codecs", "hls", "protocols" → I read the matching chapters/ file before answering.
• A name — a specific filter/encoder (e.g. scale, libx264) → grep the chapter for exact options.

Core Mental Model (read this first)

1. Command anatomy — order matters.

ffmpeg [global_opts] {[input_opts] -i INPUT}... {[output_opts] OUTPUT}...

Options apply to the next file specified. Put input options (e.g. -ss, -f, -r, -framerate) before the -i they modify; output options before the output URL. Global options (e.g. -y, -loglevel) go first. Anything not parsed as an option is treated as an output URL.

2. Indices & stream specifiers. Inputs/streams are 0-based. -map 0:v:0 = first video stream of input 0. Stream specifier forms: :v :a :s (type), :0 (index), :v:0, :m:language:eng (metadata), :p:1 (program). Used by -map, -c:, -b:, -metadata:, etc.

3. The fundamental choice: stream copy vs transcode.

• -c copy → remux/cut with no re-encode (instant, lossless, but cuts land on keyframes only).
• omit / -c:v libx264 -c:a aac → re-encode (slow, lossy, frame-accurate, enables filters).
• You cannot apply filters to a copied stream.

4. Quality knobs (re-encoding).

• CRF (constant quality, 1-pass): -crf 23 for x264/x265 (lower = better, ~18–28 sane). Preferred default.
• Bitrate (target size): -b:v 4M; add -maxrate/-bufsize for caps; 2-pass for streaming targets.
• Preset: -preset slow trades CPU for compression (x264/x265: ultrafast…placebo).

5. Filtering.

• -vf / -af = simple linear filtergraph (one input→one output, single stream).
• -filter_complex = multi-input/multi-output graphs; reference pads with [label]. Required for overlay, concat of differing streams, mixing, split.
• Graph syntax: filter=arg=val:arg2=val2, next. Chains separated by ,; parallel chains by ;.

6. -ss placement. Before -i = fast input seek (keyframe-snapped, very fast). After -i (output opt) = slow decode-then-discard but exact. With -c copy, cuts snap to keyframes regardless.

7. Diagnose with ffprobe. ffprobe -v error -show_streams -show_format in.mp4. Add -of json/-of csv for machine output. ffplay for quick visual check (ffplay -vf ... in).

Chapter Index

Topic Index

• trim / cut / seek → ch01, ch03, patterns
• stream copy / remux → ch02, ch04, cheatsheet
• map / stream selection → ch02
• CRF / bitrate / 2-pass / preset → ch04
• x264 / x265 / hevc / NVENC / QSV / VAAPI → ch04, ch06
• aac / mp3 / opus / audio bitrate → ch04
• scale / crop / pad / fps / pix_fmt / format → ch06
• overlay / concat / split / xfade / hstack → ch06, patterns
• drawtext / subtitles / burn-in → ch06, patterns
• amix / amerge / pan / volume / loudnorm → ch06
• HLS / DASH / segment / live streaming → ch05, ch07, patterns
• rtmp / srt / udp / tee / piping → ch07, patterns
• screen capture / webcam / record → ch08, patterns
• images ↔ video / thumbnails / gif → ch05, ch06, patterns
• ffprobe / inspect / metadata → ch01, ch03

Supporting Files

• cheatsheet.md — copy-paste commands for the 90% cases
• patterns.md — task recipes with the why and trade-offs
• glossary.md — terms, options, and acronyms

Scope & Limits

Distilled from the official docs; for the exhaustive per-filter / per-encoder option list, grep the chapter files or the bundled reference/FFmpeg-Complete-Documentation.md. Option availability depends on how the local FFmpeg build was compiled (ffmpeg -encoders, -filters, -protocols, -buildconf to verify). Hardware-accel paths depend on drivers/OS.