FFmpeg filter_complex Explained: Multi-Input Processing a...

Originally published at ffmpeg-micro.com

FFmpeg's -vf flag handles simple, single-stream operations just fine. Scale a video, crop it, add a watermark. But the moment you need two inputs, or want to route one stream through multiple processing paths, -vf breaks down. That's where filter_complex comes in.

filter_complex is FFmpeg's system for building multi-input, multi-output processing graphs. It's also where most developers hit a wall, because the syntax looks like someone spilled regex into a shell command. This guide breaks down how it actually works, with patterns you can copy and modify.

What filter_complex Does That -vf Can't

The -vf flag (and its audio counterpart -af) operates on a single input stream. One video in, one video out. It's a pipeline:

ffmpeg -i input.mp4 -vf "scale=1280:720" output.mp4

filter_complex removes that single-stream constraint. It lets you:

Combine multiple input files (overlay, concat, blend)
Split one input into multiple processing paths
Chain filters across different streams with explicit routing
Produce multiple output files from one command

The syntax is different because it has to be. When you have three inputs and two outputs, you need labels to say which stream goes where.

The Label System

Labels are how filter_complex routes streams. Every input gets an automatic label based on its position and stream type:

[0:v] is the video stream from the first input
[0:a] is the audio stream from the first input
[1:v] is the video stream from the second input

You can also create your own labels for intermediate results. Anything in square brackets before a filter is an input label. Anything after a filter (also in square brackets) is an output label:

-filter_complex "[0:v]scale=1280:720[scaled]"

This takes the video from input 0, scales it to 1280x720, and labels the result [scaled]. You then use -map "[scaled]" to route that labeled stream to an output file.

Labels must be unique within a filtergraph. If you use [out] once, you can't use it again.

Pattern 1: Chain Multiple Filters on One Input

The simplest filter_complex pattern. You want to apply several operations in sequence without running FFmpeg multiple times.

ffmpeg -i input.mp4 \
  -filter_complex "[0:v]scale=1280:720,crop=640:360:320:180[out]" \
  -map "[out]" output.mp4

Filters chained with commas run left to right on the same stream. This scales to 1280x720 first, then crops a 640x360 region from the center.

You could do this with -vf "scale=1280:720,crop=640:360:320:180" and get the same result. The filter_complex version only becomes necessary when you need labels for routing, which leads to the next two patterns.

A more practical chain adds text overlay after scaling:

ffmpeg -i input.mp4 \
  -filter_complex "[0:v]scale=1920:1080,drawtext=text='Demo':fontsize=48:x=10:y=10:fontcolor=white[out]" \
  -map "[out]" output.mp4

Pattern 2: Combine Multiple Inputs

This is the most common reason developers reach for filter_complex. You have two or more files and need to merge them into one output.

Overlay (picture-in-picture):

ffmpeg -i main.mp4 -i webcam.mp4 \
  -filter_complex "[1:v]scale=160:90[pip]; [0:v][pip]overlay=W-w-10:H-h-10[out]" \
  -map "[out]" -map "0:a" output.mp4

Notice the semicolon. In filter_complex, semicolons separate independent filter chains. The first chain scales the second input down. The second chain overlays the scaled result onto the first input.

W and H are the width and height of the background video. w and h are the overlay's dimensions. So W-w-10:H-h-10 puts the overlay 10 pixels from the bottom-right corner.

The -map "0:a" at the end grabs audio from the first input, since filter_complex doesn't automatically pass through audio.

Concatenation (join videos end to end):

ffmpeg -i part1.mp4 -i part2.mp4 -i part3.mp4 \
  -filter_complex "[0:v][0:a][1:v][1:a][2:v][2:a]concat=n=3:v=1:a=1[outv][outa]" \
  -map "[outv]" -map "[outa]" output.mp4

The concat filter takes all input streams in order. n=3 tells it there are 3 segments. v=1:a=1 means each segment has one video and one audio stream.

Pattern 3: Split One Input Into Multiple Outputs

Sometimes you need to produce several versions of the same source video in one pass. The split filter duplicates a stream:

ffmpeg -i input.mp4 \
  -filter_complex "[0:v]split=2[a][b]; [a]scale=320:180[small]; [b]scale=1280:720[big]" \
  -map "[small]" small.mp4 \
  -map "[big]" big.mp4

split=2 creates two copies of the input stream, labeled [a] and [b]. Each copy goes through its own scale filter. Each labeled output maps to a different output file.

This is significantly faster than running FFmpeg twice because you only decode the source once.

Running filter_complex Operations via the FFmpeg Micro API

Writing filter_complex commands by hand is where self-hosted FFmpeg gets painful. The syntax is fiddly, errors are cryptic ("Output pad 'default' of filter..." means you forgot a label), and every typo requires re-reading the docs.

FFmpeg Micro's API handles the most common filter_complex patterns without you writing filtergraph syntax. For operations like overlay, concatenation, and multi-step processing, use the options array:

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {"url": "https://example.com/main.mp4"},
      {"url": "https://example.com/overlay.png"}
    ],
    "outputFormat": "mp4",
    "options": [
      {"option": "-c:v", "argument": "libx264"},
      {"option": "-crf", "argument": "23"}
    ]
  }'

The API accepts multiple inputs via the inputs array and lets you pass raw FFmpeg options when you need fine-grained control. For operations that don't need custom filtergraphs (most transcoding, format conversion, quality adjustment), the preset field is even simpler:

{
  "inputs": [{"url": "https://example.com/video.mp4"}],
  "outputFormat": "mp4",
  "preset": {"quality": "high", "resolution": "1080p"}
}

No filter_complex syntax. No stream labels. No debugging "pad already used" errors at 2 AM.

Common Pitfalls

"Output pad already used" error. You tried to use a labeled stream twice without splitting it first. Every label can only be consumed once. Use split to duplicate it.

Audio disappearing. filter_complex doesn't pass through unmapped streams. If your filtergraph only processes video, you need -map "0:a" to keep the audio track.

Semicolons vs. commas. Commas chain filters on the same stream. Semicolons separate independent chains. Mix them up and FFmpeg either errors out or produces garbage.

Forgetting -map. When using filter_complex, FFmpeg won't guess which outputs you want. You must explicitly -map every labeled output to a file. No map, no output.

Label naming. Labels can't contain special characters or spaces. Stick to alphanumeric names: [scaled], [pip], [out], [v1].

FAQ

When should I use filter_complex instead of -vf?

Use filter_complex whenever you have more than one input file, need to split a stream into multiple processing paths, or want multiple output files from one command. If you're doing simple single-input processing (scale, crop, rotate), -vf is simpler and does the same thing.

Can I mix video and audio filters in one filter_complex?

Yes. Video and audio filters run in the same filtergraph. Use video stream labels ([0:v]) and audio stream labels ([0:a]) to route each through their respective filters. Just remember that video filters can't process audio and vice versa.

What does the semicolon do in filter_complex?

Semicolons separate independent filter chains within the filtergraph. Each chain processes its own input and produces its own output. Commas chain filters sequentially on the same stream.

How many inputs can filter_complex handle?

There's no hard limit. FFmpeg can handle dozens of inputs in a single filter_complex command. The practical limit is usually memory and the complexity of your filtergraph. For batch operations with hundreds of files, you're better off running separate commands or using an API.

Does FFmpeg Micro support custom filter_complex commands?

FFmpeg Micro handles the most common multi-input operations (concatenation, overlay, multi-step processing) through its inputs array and options fields. For standard use cases, you don't need to write filtergraph syntax at all. For advanced scenarios requiring raw filter_complex strings, pass them through the options array.

Last verified: June 2026

推荐订阅源

DEV Community