How to Name Streams in FFmpeg Filtergraphs

In FFmpeg, complex filtergraphs use brackets to label and link audio and video streams between different filters. This article explains how to define, reference, and use these bracketed labels (such as [v] or [out]) to route multiple inputs to specific outputs, allowing you to build clean and efficient media processing pipelines.

Understanding Bracket Labels (Stream Pads)

In FFmpeg’s -filter_complex, brackets define “link labels” (also called pads). They act as variable names for video and audio streams.

The basic syntax for a filter in a filtergraph is: [input_stream_label] filter_name = arguments [output_stream_label]

Step-by-Step Usage

1. Labeling Default Input Streams

By default, FFmpeg inputs are referenced by index numbers (e.g., 0:v for the first input’s video, 1:a for the second input’s audio). You pass these into your first filter using brackets:

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

In this example, the video from the first input ([0:v]) is scaled, and the resulting stream is named [scaled_video].

2. Linking Multiple Filters Together

To apply multiple filters in sequence, use the output label of one filter as the input label of the next. Separate the filter chains with a semicolon (;):

-filter_complex "[0:v] scale=1280:720 [scaled]; [scaled] transpose=1 [rotated]"

Here, [scaled] acts as the bridge connecting the scale filter to the transpose filter. The final output is named [rotated].

3. Combining Multiple Streams

For filters that require multiple inputs, like overlay or amix, place the input labels side-by-side:

-filter_complex "[0:v][1:v] overlay=10:10 [out_video]"

This takes the video from the first input [0:v] and overlays the video from the second input [1:v] on top of it, outputting a single stream named [out_video].

4. Mapping the Final Stream to the Output File

Once you have finished processing your streams, you must tell FFmpeg to write the final labeled stream to your output file using the -map option:

ffmpeg -i input1.mp4 -i input2.mp4 -filter_complex "[0:v][1:v] overlay=10:10 [out_video]" -map "[out_video]" output.mp4