Filter Syntax — -vf, -af, -filter_complex

~12 min · filtergraph, syntax, vf

Level 0Viewer

0 XP0/73 lessons0/15 achievements

0/100 XP to next level100 XP to go0% complete

Three flag flavors, one language

-vf "…" — single video filtergraph applied to the default video stream. Shorthand for the common case.
-af "…" — same idea for audio.
-filter_complex "…" — the real deal. Multi-input, multi-output, named labels. Use this when you need anything beyond 'filter the one video stream'.

The grammar

A filtergraph is a list of filter instances joined by commas (sequential) or semicolons (parallel chains). Each filter has parameters as filter=k1=v1:k2=v2. Label inputs/outputs with [name] brackets.

[0:v]scale=1280:-2[scaled]; [scaled]drawtext=text='Hi':x=10:y=10[outv]

Read: take input 0's video, scale to 1280 wide, label that [scaled]; take [scaled], draw text on it, label the result [outv].

Code

From simple to complex·bash

# Simple — single filter on default video
ffmpeg -i in.mp4 -vf scale=1280:-2 -c:a copy out.mp4

# Chain with comma
ffmpeg -i in.mp4 -vf "scale=1280:-2,format=yuv420p" -c:a copy out.mp4

# Multi-stream with -filter_complex
ffmpeg -i in.mp4 -i logo.png \
  -filter_complex "[1:v]scale=200:-2[lg]; [0:v][lg]overlay=W-w-20:20[outv]" \
  -map "[outv]" -map 0:a -c:a copy out_with_logo.mp4

Named inputs and -map·bash

# Two videos, side by side
ffmpeg -i left.mp4 -i right.mp4 \
  -filter_complex "[0:v][1:v]hstack[outv]; [0:a][1:a]amix[outa]" \
  -map "[outv]" -map "[outa]" \
  -c:v libx264 -crf 20 -preset slow \
  side_by_side.mp4

External links

Exercise

Take a video and a logo PNG. Write three commands: (a) scale the video using -vf, (b) scale and add a logo using -filter_complex, (c) stack two copies of the video side by side. Verify all three outputs play and check the filtergraphs for correctness using ffmpeg -h filter=overlay.