How to Label FFmpeg Filter Inputs and Outputs

This article explains how to assign and use custom labels for stream inputs and outputs within FFmpeg’s filtergraph. By using square bracket notation, you can identify, route, and manipulate multiple video and audio streams in complex processing pipelines. This guide provides the syntax and practical examples needed to master stream routing in FFmpeg.

In FFmpeg, custom labels are called “link labels” or “pads.” They are defined using square brackets (e.g., [my_label]). These labels act as variables for video and audio streams, allowing you to pass the output of one filter as the input to another.

To assign a label, place it directly before or after a filter in your -filter_complex string: * Input Label: Placed before the filter name to specify which stream the filter should process. * Output Label: Placed after the filter name to name the resulting stream.

Basic Syntax

The basic structure of a labeled filter is as follows:

[input_label]filter_name=arguments[output_label]

If a filter takes multiple inputs or generates multiple outputs, you simply stack the labels:

[input1][input2]overlay=x=10:y=10[watermarked_output]

Step-by-Step Examples

1. Labeling Default Input Streams

By default, FFmpeg assigns labels to your input files based on their index. The video stream of the first input file (-i video.mp4) is automatically labeled [0:v], and the video of the second input is [1:v].

2. Splitting and Labeling Streams

If you want to apply different filters to the same input, you must first split the stream and assign custom labels to the split outputs:

ffmpeg -i input.mp4 -filter_complex "[0:v]split=2[stream1][stream2]" -map "[stream1]" out1.mp4 -map "[stream2]" out2.mp4

In this command: * [0:v] is the input to the split filter. * [stream1] and [stream2] are the custom labels assigned to the two identical outputs.

3. Combining Streams with Custom Labels (Overlay Example)

When overlaying an image logo onto a video, you can use custom labels to keep track of the processed streams before saving the final file:

ffmpeg -i video.mp4 -i logo.png -filter_complex "[1:v]scale=100:-1[scaled_logo]; [0:v][scaled_logo]overlay=W-w-10:10[final_video]" -map "[final_video]" output.mp4

Here is how the labels route the data: 1. [1:v] (the logo) is sent to the scale filter, and the scaled output is labeled [scaled_logo]. 2. [0:v] (the main video) and [scaled_logo] are sent as inputs to the overlay filter. 3. The result of the overlay is labeled [final_video]. 4. -map "[final_video]" tells FFmpeg to write this specific labeled stream to the output file output.mp4.

Rules for Custom Labels