ffmpeg-filters(1)
filters - FFmpeg filters
Description
. ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\}
. ds -- \|—\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
. if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2"
. if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \}
. \" fudge factors for nroff and troff
. ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #]
. ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ . ds #]
. \" simple accents for nroff and troff
. ds ' . ds ` . ds ^ . ds , . ds ~ ~ . ds /
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
. \" troff and (daisy-wheel) nroff accents
. \" corrections for vroff
. \" for low resolution devices (crt and lpr)
\{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE
ffmpeg-filters - FFmpeg filters
This document describes filters, sources, and sinks provided by the libavfilter library.
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 in 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 labelled by names enclosed in square brackets. In the example, the split filter generates two outputs that are associated to the labels [main] and [tmp].
The stream sent to the second output of split, labelled 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 labelled as [main]), and overlay on its lower half the output generated by the crop,vflip filterchain.
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.
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
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.
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 \*(L"source\*(R", and a filter with no output pads is called a \*(L"sink\*(R".
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 \f(CW\*(C`avfilter_graph_parse_ptr()\*(C' 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 \*(L",\*(R"-separated filter descriptions.
A filtergraph consists of a sequence of filterchains. A sequence of filterchains is represented by a list of \*(L";\*(R"-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\*(L". The name of the filter class is optionally followed by a string \*(R"=arguments".
arguments is a string which 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. E.g. the \f(CW\*(C`fade\*(C' filter declares three options in this order \*(-- type, start_frame and nb_frames. Then the parameter list in:0:30 means that the value in is assigned to the option type, 0 to start_frame and 30 to nb_frames.
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 \f(CW\*(C`format\*(C' 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 initial and ending mark, and the character \e 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.
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 to a filter output or input pad. The preceding labels in_link_1 ... in_link_N, are associated to the filter input pads, the following labels out_link_1 ... out_link_M, are associated to 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 labelled, it is linked by default to the first unlabelled 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 two input pads. The first output pad of split is labelled \*(L"L1\*(R", the first input pad of overlay is labelled \*(L"L2\*(R", and the second output pad of split is linked to the second input pad of overlay, which are both unlabelled.
In a filter description, if the input label of the first filter is not specified, \*(L"in\*(R" is assumed; if the output label of the last filter is not specified, \*(L"out\*(R" is assumed.
In a complete filterchain all the unlabelled 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.
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 \f(CW\*(C`sws_flags=\f(CIflags\f(CW;\*(C' to the filtergraph description.
Here is a BNF description of the filtergraph syntax:
Filtergraph description composition entails several levels of escaping. See the \*(L"Quoting and escaping\*(R" section in the ffmpeg-utils\|(1) manual for more information about the employed escaping procedure.
A first level escaping affects the content of each filter option value, which may contain the special character \f(CW\*(C`:\*(C' used to separate values, or one of the escaping characters \f(CW\*(C`\e\*(C'.
A second level escaping affects the whole filter description, which may contain the escaping characters \f(CW\*(C`\e\*(C' or the special characters \f(CW\*(C`[],;\*(C' used by the filtergraph description.
Finally, when you specify a filtergraph on a shell commandline, you need to perform a third level escaping for the shell special characters contained within it.
For example, consider the following string to be embedded in the drawtext filter description text value:
this is a string: may contain one, or more, special characters
This string contains the \f(CW\*(C`\*(C' special escaping character, and the \f(CW\*(C`:\*(C' special character, so it needs to be escaped in this way:
text=this is a \estring\e\e: may contain one, or more, special characters
A second level of escaping is required when embedding the filter description in a filtergraph description, in order to escape all the filtergraph special characters. Thus the example above becomes:
drawtext=text=this is a \e\e\estring\e\e\e\e\e: may contain one\e, or more\e, special characters
(note that in addition to the \f(CW\*(C`\e\*(C' escaping special characters, also \f(CW\*(C`,\*(C' needs to be escaped).
Finally an additional level of escaping is needed when writing the filtergraph description in a shell command, which depends on the escaping rules of the adopted shell. For example, assuming that \f(CW\*(C`\e\*(C' is special and needs to be escaped with another \f(CW\*(C`\e\*(C', the previous string will finally result in:
-vf "drawtext=text=this is a \e\e\e\e\e\estring\e\e\e\e\e\e\e\e\e\e: may contain one\e\e, or more\e\e, special characters"
Some filters support a generic enable option. For the filters supporting timeline editing, this option can be set to an expression which is evaluated before sending a frame to the filter. If the evaluation is non-zero, the filter will be enabled, otherwise the frame will be sent unchanged to the next filter in the filtergraph.
The expression accepts the following values:
timestamp expressed in seconds, NAN if the input timestamp is unknown
sequential number of the input frame, starting from 0
the position in the file of the input frame, NAN if unknown
width and height of the input frame if video
Additionally, these filters support an enable command that can be used to re-define the expression.
Like any other filtering option, the enable option follows the same rules.
For example, to enable a blur filter (smartblur) from 10 seconds to 3 minutes, and a curves filter starting at 3 seconds:
smartblur = enable=between(t,10,3*60), curves = enable=gte(t,3) : preset=cross_process
See \f(CW\*(C`ffmpeg -filters\*(C' to view which filters have timeline support.
Some options can be changed during the operation of the filter using
a command. These options are marked 'T' on the output of
ffmpeg -h filter=
Some filters with several inputs support a common set of options. These options can only be set by name, not with the short notation.
The action to take when EOF is encountered on the secondary input; it accepts one of the following values:
Repeat the last frame (the default).
End both streams.
Pass the main input through.
If set to 1, force the output to terminate when the shortest input terminates. Default value is 0.
If set to 1, force the filter to extend the last frame of secondary streams until the end of the primary stream. A value of 0 disables this behavior. Default value is 1.
When you configure your FFmpeg build, you can disable any of the existing filters using \f(CW\*(C`--disable-filters\*(C'. The configure output will show the audio filters included in your build.
Below is a description of the currently available audio filters.
A compressor is mainly used to reduce the dynamic range of a signal. Especially modern music is mostly compressed at a high ratio to improve the overall loudness. It's done to get the highest attention of a listener, \*(L"fatten\*(R" the sound and bring more \*(L"power\*(R" to the track. If a signal is compressed too much it may sound dull or \*(L"dead\*(R" afterwards or it may start to \*(L"pump\*(R" (which could be a powerful effect but can also destroy a track completely). The right compression is the key to reach a professional sound and is the high art of mixing and mastering. Because of its complex settings it may take a long time to get the right feeling for this kind of effect.
Compression is done by detecting the volume above a chosen level \f(CW\*(C`threshold\*(C' and dividing it by the factor set with \f(CW\*(C`ratio\*(C'. So if you set the threshold to -12dB and your signal reaches -6dB a ratio of 2:1 will result in a signal at -9dB. Because an exact manipulation of the signal would cause distortion of the waveform the reduction can be levelled over the time. This is done by setting \*(L"Attack\*(R" and \*(L"Release\*(R". \f(CW\*(C`attack\*(C' determines how long the signal has to rise above the threshold before any reduction will occur and \f(CW\*(C`release\*(C' sets the time the signal has to fall below the threshold to reduce the reduction again. Shorter signals than the chosen attack time will be left untouched. The overall reduction of the signal can be made up afterwards with the \f(CW\*(C`makeup\*(C' setting. So compressing the peaks of a signal about 6dB and raising the makeup to this level results in a signal twice as loud than the source. To gain a softer entry in the compression the \f(CW\*(C`knee\*(C' flattens the hard edge at the threshold in the range of the chosen decibels.
The filter accepts the following options:
Set input gain. Default is 1. Range is between 0.015625 and 64.