recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex}
options in @command{ffmpeg} and @option{-vf} in @command{ffplay}, and by the
@code{avfilter_graph_parse()}/@code{avfilter_graph_parse2()} function defined in
-@file{libavfilter/avfiltergraph.h}.
+@file{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
"=@var{arguments}".
@var{arguments} is a string which contains the parameters used to
-initialize the filter instance. It may have one of the two allowed forms:
+initialize the filter instance. It may have one of the following forms:
@itemize
@item
@var{in} is assigned to the option @option{type}, @var{0} to
@option{start_frame} and @var{30} to @option{nb_frames}.
+@item
+A ':'-separated list of mixed direct @var{value} and long @var{key=value}
+pairs. The direct @var{value} must precede the @var{key=value} pairs, and
+follow the same constraints order of the previous point. The following
+@var{key=value} pairs can be set in any preferred order.
+
@end itemize
If the option value itself is a list of items (e.g. the @code{format} filter
Convert the input audio format to the specified formats.
+@emph{This filter is deprecated. Use @ref{aformat} instead.}
+
The filter accepts a string of the form:
"@var{sample_format}:@var{channel_layout}".
Determine how steep is the filter's shelf transition.
@end table
+@section telecine
+
+Apply telecine process to the video.
+
+This filter accepts the following options:
+
+@table @option
+@item first_field
+@table @samp
+@item top, t
+top field first
+@item bottom, b
+bottom field first
+The default value is @code{top}.
+@end table
+
+@item pattern
+A string of numbers representing the pulldown pattern you wish to apply.
+The default value is @code{23}.
+@end table
+
+@example
+Some typical patterns:
+
+NTSC output (30i):
+27.5p: 32222
+24p: 23 (classic)
+24p: 2332 (preferred)
+20p: 33
+18p: 334
+16p: 3444
+
+PAL output (25i):
+27.5p: 12222
+24p: 222222222223 ("Euro pulldown")
+16.67p: 33
+16p: 33333334
+@end example
+
@section treble
Boost or cut treble (upper) frequencies of the audio using a two-pole
Merge two or more audio streams into a single multi-channel stream.
-The filter accepts the following named options:
+The filter accepts the following options:
@table @option
@end example
@item
-Multiple merges:
+Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
@example
-ffmpeg -f lavfi -i "
-amovie=input.mkv:si=0 [a0];
-amovie=input.mkv:si=1 [a1];
-amovie=input.mkv:si=2 [a2];
-amovie=input.mkv:si=3 [a3];
-amovie=input.mkv:si=4 [a4];
-amovie=input.mkv:si=5 [a5];
-[a0][a1][a2][a3][a4][a5] amerge=inputs=6" -c:a pcm_s16le output.mkv
+ffmpeg -i input.mkv -filter_complex "[0:1][0:2][0:3][0:4][0:5][0:6] amerge=inputs=6" -c:a pcm_s16le output.mkv
@end example
@end itemize
the filter will flush all the remaining samples when the input audio
signal its end.
-The filter accepts parameters as a list of @var{key}=@var{value} pairs,
-separated by ":".
+The filter accepts the following options:
@table @option
Forward two audio streams and control the order the buffers are forwarded.
-The argument to the filter is an expression deciding which stream should be
+The filter accepts the following options:
+
+@table @option
+@item expr, e
+Set the expression deciding which stream should be
forwarded next: if the result is negative, the first stream is forwarded; if
the result is positive or zero, the second stream is forwarded. It can use
the following variables:
The default value is @code{t1-t2}, which means to always forward the stream
that has a smaller timestamp.
+@end table
+
+@subsection Examples
-Example: stress-test @code{amerge} by randomly sending buffers on the wrong
+Stress-test @code{amerge} by randomly sending buffers on the wrong
input, while avoiding too much of a desynchronization:
@example
amovie=file.ogg [a] ; amovie=file.mp3 [b] ;
Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
tolerance in @file{silence.mp3}:
@example
-ffmpeg -f lavfi -i amovie=silence.mp3,silencedetect=noise=0.0001 -f null -
+ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
@end example
@end itemize
This source is mainly intended for a programmatic use, in particular
through the interface defined in @file{libavfilter/asrc_abuffer.h}.
-It accepts the following mandatory parameters:
-@var{sample_rate}:@var{sample_fmt}:@var{channel_layout}
+It accepts the following named parameters:
@table @option
+@item time_base
+Timebase which will be used for timestamps of submitted frames. It must be
+either a floating-point number or in @var{numerator}/@var{denominator} form.
+
@item sample_rate
The sample rate of the incoming audio buffers.
@subsection Examples
@example
-abuffer=44100:s16p:stereo
+abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
@end example
will instruct the source to accept planar 16bit signed stereo at 44100Hz.
6 and the "stereo" channel layout corresponds to the value 0x3, this is
equivalent to:
@example
-abuffer=44100:6:0x3
+abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
@end example
@section aevalsrc
channel), which are evaluated and used to generate a corresponding
audio signal.
-It accepts the syntax: @var{exprs}[::@var{options}].
-@var{exprs} is a list of expressions separated by ":", one for each
-separate channel. In case the @var{channel_layout} is not
-specified, the selected channel layout depends on the number of
-provided expressions.
-
-@var{options} is an optional sequence of @var{key}=@var{value} pairs,
-separated by ":".
-
-The description of the accepted options follows.
+This source accepts the following options:
@table @option
+@item exprs
+Set the '|'-separated expressions list for each separate channel. In case the
+@option{channel_layout} option is not specified, the selected channel layout
+depends on the number of provided expressions.
@item channel_layout, c
Set the channel layout. The number of channels in the specified layout
Generate a sin signal with frequency of 440 Hz, set sample rate to
8000 Hz:
@example
-aevalsrc="sin(440*2*PI*t)::s=8000"
+aevalsrc="sin(440*2*PI*t):s=8000"
@end example
@item
Generate a two channels signal, specify the channel layout (Front
Center + Back Center) explicitly:
@example
-aevalsrc="sin(420*2*PI*t):cos(430*2*PI*t)::c=FC|BC"
+aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
@end example
@item
@item
Generate 2.5 Hz binaural beats on a 360 Hz carrier:
@example
-aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) : 0.1*sin(2*PI*(360+2.5/2)*t)"
+aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
@end example
@end itemize
the source for filters which ignore the input data (for example the sox
synth filter).
-It accepts an optional sequence of @var{key}=@var{value} pairs,
-separated by ":".
-
-The description of the accepted options follows.
+This source accepts the following options:
@table @option
-@item sample_rate, s
-Specify the sample rate, and defaults to 44100.
-
@item channel_layout, cl
Specify the channel layout, and can be either an integer or a string
@file{libavutil/channel_layout.c} for the mapping between strings and
channel layout values.
+@item sample_rate, r
+Specify the sample rate, and defaults to 44100.
+
@item nb_samples, n
Set the number of samples per requested frames.
Note that the flite library is not thread-safe.
-The source accepts parameters as a list of @var{key}=@var{value} pairs,
-separated by ":".
-
-The description of the accepted parameters follows.
+The filter accepts the following options:
@table @option
The audio signal is bit-exact.
-It accepts a list of options in the form of @var{key}=@var{value} pairs
-separated by ":". If the option name is omitted, the first option is the
-frequency and the second option is the beep factor.
-
-The supported options are:
+The filter accepts the following options:
@table @option
In order to display the output lines, you need to set the loglevel at
least to the AV_LOG_INFO value.
-This filter accepts a list of options in the form of
-@var{key}=@var{value} pairs separated by ":". A description of the
-accepted options follows.
+The filter accepts the following options:
@table @option
@item black_min_duration, d
@table @option
@item preset
-Select one of the available color presets. This option can not be used in
-addition to the @option{r}, @option{g}, @option{b} parameters.
+Select one of the available color presets. This option can be used in addition
+to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
+options takes priority on the preset values.
Available presets are:
@table @samp
@item none
filter helps remove camera shake from hand-holding a camera, bumping a
tripod, moving on a vehicle, etc.
-The filter accepts parameters as a list of @var{key}=@var{value}
-pairs, separated by ":". If the key of the first options is omitted,
-the arguments are interpreted according to the syntax
-@var{x}:@var{y}:@var{w}:@var{h}:@var{rx}:@var{ry}:@var{edge}:@var{blocksize}:@var{contrast}:@var{search}:@var{filename}:@var{opencl}.
-
-A description of the accepted parameters follows.
+The filter accepts the following options:
@table @option
-@item x, y, w, h
+@item x
+@item y
+@item w
+@item h
Specify a rectangular area where to limit the search for motion
vectors.
If desired the search for motion vectors can be limited to a
Default - search the whole frame.
-@item rx, ry
+@item rx
+@item ry
Specify the maximum extent of movement in x and y directions in the
range 0-64 pixels. Default 16.
arithmetic to avoid wasting CPU time. The output frames are marked as
non-interlaced.
-This filter accepts the following named options:
+The filter accepts the following options:
+
@table @option
@item type
Specify whether to extract the top (if the value is @code{0} or
Modify the hue and/or the saturation of the input.
-This filter accepts the following optional named options:
+This filter accepts the following options:
@table @option
@item h
-Specify the hue angle as a number of degrees. It accepts a float
-number or an expression, and defaults to 0.0.
-
-@item H
-Specify the hue angle as a number of radians. It accepts a float
-number or an expression, and defaults to 0.0.
+Specify the hue angle as a number of degrees. It accepts an expression,
+and defaults to "0".
@item s
Specify the saturation in the [-10,10] range. It accepts a float number and
-defaults to 1.0.
+defaults to "1".
+
+@item H
+Specify the hue angle as a number of radians. It accepts a float
+number or an expression, and defaults to "0".
@end table
-The @var{h}, @var{H} and @var{s} parameters are expressions containing the
-following constants:
+@option{h} and @option{H} are mutually exclusive, and can't be
+specified at the same time.
+
+The @option{h}, @option{H} and @option{s} option values are
+expressions containing the following constants:
@table @option
@item n
time base of the input video
@end table
-The options can also be set using the syntax: @var{hue}:@var{saturation}
-
-In this case @var{hue} is expressed in degrees.
-
@subsection Examples
@itemize
hue=H=PI/2:s=1
@end example
-@item
-Same command without named options, hue must be expressed in degrees:
-@example
-hue=90:1
-@end example
-
-@item
-Note that "h:s" syntax does not support expressions for the values of
-h and s, so the following example will issue an error:
-@example
-hue=PI/2:1
-@end example
-
@item
Rotate hue and make the saturation swing between 0
and 2 over a period of 1 second:
This filter supports the following command:
@table @option
-@item reinit
+@item s
+@item h
+@item H
Modify the hue and/or the saturation of the input video.
-The command accepts the same named options and syntax than when calling the
-filter from the command-line.
+The command accepts the same options and syntax of the corresponding
+options.
-If a parameter is omitted, it is kept at its current value.
+If the specified expression is not valid, it is kept at its current
+value.
@end table
@section idet
pixels comprise the logo. It works by filling in the pixels that
comprise the logo with neighboring pixels.
-This filter requires one argument which specifies the filter bitmap
-file, which can be any image format supported by libavformat. The
-width and height of the image file must match those of the video
-stream being processed.
+The filters accept the following options:
+
+@table @option
+@item filename, f
+Set the filter bitmap file, which can be any image format supported by
+libavformat. The width and height of the image file must match those of the
+video stream being processed.
+@end table
Pixels in the provided bitmap image with a value of zero are not
considered part of the logo, non-zero pixels are considered part of
filter may be changed by later filters in the filterchain, e.g. if
another "setsar" or a "setdar" filter is applied.
-The @code{setdar} and @code{setsar} filters accept a string in the
-form @var{num}:@var{den} expressing an aspect ratio, or the following
-named options, expressed as a sequence of @var{key}=@var{value} pairs,
-separated by ":".
+The filters accept the following options:
@table @option
-@item max
-Set the maximum integer value to use for expressing numerator and
-denominator when reducing the expressed aspect ratio to a rational.
-Default value is @code{100}.
-
-@item r, ratio, dar, sar:
+@item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
Set the aspect ratio used by the filter.
The parameter can be a floating point number string, an expression, or
the parameter is not specified, it is assumed the value "0".
In case the form "@var{num}:@var{den}" the @code{:} character should
be escaped.
+
+@item max
+Set the maximum integer value to use for expressing numerator and
+denominator when reducing the expressed aspect ratio to a rational.
+Default value is @code{100}.
+
@end table
-If the keys are omitted in the named options list, the specifed values
-are assumed to be @var{ratio} and @var{max} in that order.
+@subsection Examples
-For example to change the display aspect ratio to 16:9, specify:
+@itemize
+
+@item
+To change the display aspect ratio to 16:9, specify one of the following:
@example
-setdar='16:9'
-# the above is equivalent to
-setdar=1.77777
+setdar=dar=1.77777
setdar=dar=16/9
setdar=dar=1.77777
@end example
+@item
To change the sample aspect ratio to 10:11, specify:
@example
-setsar='10:11'
-# the above is equivalent to
-setsar='sar=10/11'
+setsar=sar=10/11
@end example
+@item
To set a display aspect ratio of 16:9, and specify a maximum integer value of
1000 in the aspect ratio reduction, use the command:
@example
-setdar=ratio='16:9':max=1000
+setdar=ratio=16/9:max=1000
@end example
+@end itemize
+
@anchor{setfield}
@section setfield
corresponding property, which affects how the frame is treated by
following filters (e.g. @code{fieldorder} or @code{yadif}).
-This filter accepts a single option @option{mode}, which can be
-specified either by setting @code{mode=VALUE} or setting the value
-alone. Available values are:
+The filter accepts the following options:
+
+@table @option
+
+@item mode
+Available values are:
@table @samp
@item auto
@item prog
Mark the frame as progressive.
@end table
+@end table
@section showinfo
Blur the input video without impacting the outlines.
-A description of the accepted options follows.
+The filter accepts the following options:
@table @option
@item luma_radius, lr
Tile several successive frames together.
-It accepts a list of options in the form of @var{key}=@var{value} pairs
-separated by ":". A description of the accepted options follows.
+The filter accepts the following options:
@table @option
Set the grid size (i.e. the number of lines and columns) in the form
"@var{w}x@var{h}".
+@item nb_frames
+Set the maximum number of frames to render in the given area. It must be less
+than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
+the area will be used.
+
@item margin
Set the outer border margin in pixels.
more advanced padding options (such as having different values for the edges),
refer to the pad video filter.
-@item nb_frames
-Set the maximum number of frames to render in the given area. It must be less
-than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
-the area will be used.
-
@end table
-Alternatively, the options can be specified as a flat string:
-
-@var{layout}[:@var{nb_frames}[:@var{margin}[:@var{padding}]]]
+@subsection Examples
-For example, produce 8x8 PNG tiles of all keyframes (@option{-skip_frame
-nokey}) in a movie:
+@itemize
+@item
+Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
@example
ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
@end example
duplicating each output frame to accomodate the originally detected frame
rate.
-Another example to display @code{5} pictures in an area of @code{3x2} frames,
+@item
+Display @code{5} pictures in an area of @code{3x2} frames,
with @code{7} pixels between them, and @code{2} pixels of initial margin, using
mixed flat and named options:
@example
tile=3x2:nb_frames=5:padding=7:margin=2
@end example
+@end itemize
@section tinterlace
Frames are counted starting from 1, so the first input frame is
considered odd.
-This filter accepts options in the form of @var{key}=@var{value} pairs
-separated by ":".
-Alternatively, the @var{mode} option can be specified as a value alone,
-optionally followed by a ":" and further ":" separated @var{key}=@var{value}
-pairs.
-
-A description of the accepted options follows.
+The filter accepts the following options:
@table @option
@item video_size
Specify the size (width and height) of the buffered video frames.
+@item width
+Input video width.
+
+@item height
+Input video height.
+
@item pix_fmt
A string representing the pixel format of the buffered video frames.
It may be a number corresponding to a pixel format, or a pixel format
@item time_base
Specify the timebase assumed by the timestamps of the buffered frames.
-@item time_base
+@item frame_rate
Specify the frame rate expected for the video stream.
-@item pixel_aspect
+@item pixel_aspect, sar
Specify the sample aspect ratio assumed by the video frames.
@item sws_param
For example:
@example
-buffer=size=320x240:pix_fmt=yuv410p:time_base=1/24:pixel_aspect=1/1
+buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
@end example
will instruct the source to accept video frames with size 320x240 and
color pattern, a scrolling gradient and a timestamp. This is mainly
intended for testing purposes.
-These sources accept an optional sequence of @var{key}=@var{value} pairs,
-separated by ":". The description of the accepted options follows.
+The sources accept the following options:
@table @option
@table @option
-@item expr
+@item expr, e
An expression, which is evaluated for each input frame. If the expression is
evaluated to a non-zero value, the frame is selected and passed to the output,
otherwise it is discarded.
[leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
# desaturate the image in the interval 15-20
-15.0-20.0 [enter] hue reinit s=0,
+15.0-20.0 [enter] hue s 0,
[enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
- [leave] hue reinit s=1,
+ [leave] hue s 1,
[leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
# apply an exponential saturation fade-out effect, starting from time 25
-25 [enter] hue s=exp(t-25)
+25 [enter] hue s exp(25-t)
@end example
A filtergraph allowing to read and process the above command list
@table @option
-@item expr
+@item expr, tb
The expression which is evaluated into the output timebase.
@end table
segments must have the same number of streams of each type, and that will
also be the number of streams at output.
-The filter accepts the following named parameters:
+The filter accepts the following options:
+
@table @option
@item n
Convert input audio to a video output, representing the samples waves.
-The filter accepts the following named parameters:
+The filter accepts the following options:
+
@table @option
+@item size, s
+Specify the video size for the output. Default value is "600x240".
+
@item mode
Set display mode.
Set the (approximate) output frame rate. This is done by setting the
option @var{n}. Default value is "25".
-@item size, s
-Specify the video size for the output. Default value is "600x240".
@end table
@subsection Examples
Read audio and/or video stream(s) from a movie container.
-It accepts the syntax: @var{movie_name}[:@var{options}] where
-@var{movie_name} is the name of the resource to read (not necessarily
-a file but also a device or a stream accessed through some protocol),
-and @var{options} is an optional sequence of @var{key}=@var{value}
-pairs, separated by ":".
-
-The description of the accepted options follows.
+This filter accepts the following options:
@table @option
+@item filename
+The name of the resource to read (not necessarily a file but also a device or a
+stream accessed through some protocol).
@item format_name, f
Specifies the format assumed for the movie to read, and can be either
projects / ffmpeg / blobdiff