FFmpeg Filter Complex Syntax Rules

Mastering the syntax of the FFmpeg -filter_complex option is essential for building complex audio and video processing pipelines. This article explains the precise rules for separating individual filters, joining them into filterchains, and connecting multiple chains using semicolons, commas, and link labels.

The Hierarchy of FFmpeg Filtering

An FFmpeg -filter_complex string is structured in a strict hierarchy:

1. Filters: The individual processing blocks (e.g., scale, overlay, split).
2. Filterchains: A sequence of filters applied one after another to a stream.
3. Filtergraph: The entire collection of filterchains that makes up the complex filter.

Rule 1: Use Commas to Separate Filters in a Chain

Within a single filterchain, individual filters are executed sequentially from left to right. To pass the output of one filter directly into the input of the next, separate them with a comma (,).

• Syntax: filter1,filter2,filter3
• Example: scale=1280:720,transpose=1

In this example, the video is first scaled to 1280x720, and the resulting scaled video is immediately rotated 90 degrees clockwise by the transpose filter.

Rule 2: Use Semicolons to Separate Filterchains

If you need to process multiple independent streams or create parallel paths, you must use separate filterchains. Filterchains are separated from one another using a semicolon (;).

• Syntax: chain1;chain2;chain3
• Example: [0:v]scale=640:360[lowres]; [0:v]scale=1920:1080[highres]

Here, the input video [0:v] is processed in two independent paths: one scales the video to low resolution, and the other scales it to high resolution. The semicolon keeps these operations isolated.

Rule 3: Use Square Brackets for Link Labels

Link labels, enclosed in square brackets ([...]), are used to route streams into and out of filters. They serve as the inputs and outputs of your filterchains.

• Input Labels: Placed before a filter or filterchain to define what input stream it receives.

• Output Labels: Placed after a filter or filterchain to name the resulting stream so it can be referenced later.

• Example: [0:v]scale=1280:720[scaled]; [1:v][scaled]overlay[out]

In this syntax: 1. [0:v] (the video from the first input file) is scaled and assigned the label [scaled]. 2. The semicolon ; ends the first chain. 3. The second chain takes [1:v] (the video from the second input file) and the newly created [scaled] stream, feeds them both into the overlay filter, and outputs the final result as [out].

Rule 4: Escape Special Characters When Necessary

If a filter argument contains characters that are part of the FFmpeg syntax (like commas, semicolons, or colons), you must enclose the argument in single quotes or escape the character with a backslash.

• Example with Colons: drawtext=text='Hello: World'
• Example with Escaping: drawtext=text=Hello\: World