[ ] FFmpeg Filters Documentation

FFmpeg Filters Documentation

Description

This document describes filters, sources, and sinks provided by the libavfilter library.

Filtering Introduction

Filtering in FFmpeg is enabled through the libavfilter library.

In libavfilter, a filter can have multiple inputs and multiple outputs. To illustrate the sorts of things that are possible, we consider the following filtergraph:

                [main]
input --> split ---------------------> overlay --> output
            |                             ^
            |[tmp]                  [flip]|
            +-----> crop --> vflip -------+

This filtergraph splits the input stream into two streams, then sends one stream through the crop filter and the vflip filter before merging it back with the other stream by overlaying it on top. You can use the following command to achieve this:

ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT

The result will be that the top half of the video is mirrored onto the bottom half of the output video.

Filters in the same linear chain are separated by commas, and distinct linear chains of filters are separated by semicolons. In our example, crop, vflip are in one linear chain, split and overlay are separately in another. The points where the linear chains join are labeled by names enclosed in square brackets. In the example, the split filter generates two outputs that are associated with the labels [main] and [tmp].

The stream sent to the second output of split, labeled as [tmp], is processed through the crop filter, which crops away the lower half part of the video, and then vertically flipped. The overlay filter takes in input the first unchanged output of the split filter (which was labeled as [main]), and overlays on its lower half the output generated by the crop, vflip filter chain.

Some filters take in input a list of parameters: they are specified after the filter name and an equal sign, and are separated from each other by a colon.

There exist so-called source filters that do not have an audio/video input, and sink filters that will not have audio/video output.

graph2dot

The graph2dot program included in the FFmpeg tools directory can be used to parse a filtergraph description and issue a corresponding textual representation in the dot language.

Invoke the command:

graph2dot -h

to see how to use graph2dot.

You can then pass the dot description to the dot program (from the graphviz suite of programs) and obtain a graphical representation of the filtergraph.

For example, the sequence of commands:

echo GRAPH_DESCRIPTION | \\
tools/graph2dot -o graph.tmp && \\
dot -Tpng graph.tmp -o graph.png && \\
display graph.png

can be used to create and display an image representing the graph described by the GRAPH_DESCRIPTION string. Note that this string must be a complete self-contained graph, with its inputs and outputs explicitly defined. For example, if your command line is of the form:

ffmpeg -i infile -vf scale=640:360 outfile

your GRAPH_DESCRIPTION string will need to be of the form:

nullsrc,scale=640:360,nullsink

you may also need to set the nullsrc parameters and add a format filter in order to simulate a specific input file.

Filtergraph Description

A filtergraph is a directed graph of connected filters. It can contain cycles, and there can be multiple links between a pair of filters. Each link has one input pad on one side connecting it to one filter from which it takes its input, and one output pad on the other side connecting it to one filter accepting its output.

Each filter in a filtergraph is an instance of a filter class registered in the application, which defines the features and the number of input and output pads of the filter.

A filter with no input pads is called a "source," and a filter with no output pads is called a "sink."

Filtergraph Syntax

A filtergraph has a textual representation, which is recognized by the -filter/-vf/-af and -filter_complex options in ffmpeg and -vf/-af in ffplay, and by the avfilter_graph_parse_ptr() function defined in libavfilter/avfilter.h.

A filterchain consists of a sequence of connected filters, each one connected to the previous one in the sequence. A filterchain is represented by a list of ","-separated filter descriptions.

A filtergraph consists of a sequence of filterchains. A sequence of filterchains is represented by a list of ";"-separated filterchain descriptions.

A filter is represented by a string of the form: [in_link_1]...[in_link_N]filter_name@id=arguments[out_link_1]...[out_link_M]

filter_name is the name of the filter class of which the described filter is an instance of, and has to be the name of one of the filter classes registered in the program optionally followed by "@id". The name of the filter class is optionally followed by a string "=arguments".

Arguments is a string that contains the parameters used to initialize the filter instance. It may have one of two forms:

A ':'-separated list of key=value pairs.
A ':'-separated list of value. In this case, the keys are assumed to be the option names in the order they are declared.

A ':'-separated list of mixed direct value and long key=value pairs. The direct value must precede the key=value pairs, and follow the same constraints order of the previous point. The following key=value pairs can be set in any preferred order.

If the option value itself is a list of items (e.g. the format filter takes a list of pixel formats), the items in the list are usually separated by '|'.

The list of arguments can be quoted using the character "'" as the initial and ending mark, and the character '\' for escaping the characters within the quoted text; otherwise, the argument string is considered terminated when the next special character (belonging to the set '[]=;,') is encountered.

A special syntax implemented in the ffmpeg CLI tool allows loading option values from files. This is done by prepending a slash '/' to the option name, then the supplied value is interpreted as a path from which the actual value is loaded.

The name and arguments of the filter are optionally preceded and followed by a list of link labels. A link label allows one to name a link and associate it with a filter output or input pad. The preceding labels in_link_1 ... in_link_N, are associated with the filter input pads, the following labels out_link_1 ... out_link_M, are associated with the output pads.

When two link labels with the same name are found in the filtergraph, a link between the corresponding input and output pad is created.

If an output pad is not labeled, it is linked by default to the first unlabeled input pad of the next filter in the filterchain. For example, in the filterchain:

nullsrc, split[L1], [L2]overlay, nullsink

the split filter instance has two output pads, and the overlay filter instance has two input pads. The first output pad of split is labeled "L1", the first input pad of overlay is labeled "L2", and the second output pad of split is linked to the second input pad of overlay, which are both unlabeled.

In a filter description, if the input label of the first filter is not specified, "in" is assumed; if the output label of the last filter is not specified, "out" is assumed.

In a complete filterchain, all the unlabeled filter input and output pads must be connected. A filtergraph is considered valid if all the filter input and output pads of all the filterchains are connected.

Leading and trailing whitespaces (space, tabs, or line feeds) separating tokens in the filtergraph specification are ignored. This means that the filtergraph can be expressed using empty lines and spaces to improve readability.

For example, the filtergraph:

testsrc, split[L1], hflip[L2];[L1][L2] hstack

can be represented as:

testsrc,
split [L1], hflip [L2];

[L1][L2] hstack

Libavfilter will automatically insert scale filters where format conversion is required. It is possible to specify swscale flags for those automatically inserted scalers by prepending sws_flags=flags; to the filtergraph description.

Here is a BNF description of the filtergraph syntax:

NAME             ::= sequence of alphanumeric characters and '_'
FILTER_NAME      ::= NAME[\"@\"NAME]
LINKLABEL        ::= \"[\" NAME \"]\"
LINKLABELS       ::= LINKLABEL [LINKLABELS]
FILTER_ARGUMENTS ::= sequence of chars (possibly quoted)
FILTER           ::= [LINKLABELS] FILTER_NAME [\"=\" FILTER_ARGUMENTS] [LINKLABELS]
FILTERCHAIN      ::= FILTER [,FILTERCHAIN]
FILTERGRAPH      ::= [sws_flags=flags;] FILTERCHAIN [;FILTERGRAPH]

For more information, visit FFmpeg Filters Documentation.

Suggested labels

{'label-name': 'filtering', 'label-description': 'Describes the process of applying filters to manipulate audio or video streams in FFmpeg.', 'confidence': 65.37}

irthomasthomas / undecidability