"=@var{arguments}".
@var{arguments} is a string which contains the parameters used to
-initialize the filter instance, and are described in the filter
-descriptions below.
+initialize the filter instance. It may have one of the two allowed forms:
+@itemize
+
+@item
+A ':'-separated list of @var{key=value} pairs.
+
+@item
+A ':'-separated list of @var{value}. In this case, the keys are assumed to be
+the option names in the order they are declared. E.g. the @code{fade} filter
+declares three options in this order -- @option{type}, @option{start_frame} and
+@option{nb_frames}. Then the parameter list @var{in:0:30} means that the value
+@var{in} is assigned to the option @option{type}, @var{0} to
+@option{start_frame} and @var{30} to @option{nb_frames}.
+
+@end itemize
+
+If the option value itself is a list of items (e.g. the @code{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 initial
and ending mark, and the character '\' for escaping the characters
@var{LINKLABEL} ::= "[" @var{NAME} "]"
@var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
@var{FILTER_ARGUMENTS} ::= sequence of chars (eventually quoted)
-@var{FILTER} ::= [@var{LINKNAMES}] @var{NAME} ["=" @var{ARGUMENTS}] [@var{LINKNAMES}]
+@var{FILTER} ::= [@var{LINKLABELS}] @var{NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]
@var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]
@var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
@end example
@table @option
@item sample_fmts
-A comma-separated list of requested sample formats.
+A '|'-separated list of requested sample formats.
@item sample_rates
-A comma-separated list of requested sample rates.
+A '|'-separated list of requested sample rates.
@item channel_layouts
-A comma-separated list of requested channel layouts.
+A '|'-separated list of requested channel layouts.
@end table
For example to force the output to either unsigned 8-bit or signed 16-bit stereo:
@example
-aformat=sample_fmts\=u8\,s16:channel_layouts\=stereo
+aformat=sample_fmts=u8|s16:channel_layouts=stereo
+@end example
+
+@section amix
+
+Mixes multiple audio inputs into a single output.
+
+For example
+@example
+avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
@end example
+will mix 3 input audio streams to a single output with the same duration as the
+first input and a dropout transition time of 3 seconds.
+
+The filter accepts the following named parameters:
+@table @option
+
+@item inputs
+Number of inputs. If unspecified, it defaults to 2.
+
+@item duration
+How to determine the end-of-stream.
+@table @option
+
+@item longest
+Duration of longest input. (default)
+
+@item shortest
+Duration of shortest input.
+
+@item first
+Duration of first input.
+
+@end table
+
+@item dropout_transition
+Transition time, in seconds, for volume renormalization when an input
+stream ends. The default value is 2 seconds.
+
+@end table
@section anull
Pass the audio source unchanged to the output.
+@section ashowinfo
+
+Show a line containing various information for each input audio frame.
+The input audio is not modified.
+
+The shown line contains a sequence of key/value pairs of the form
+@var{key}:@var{value}.
+
+A description of each shown parameter follows:
+
+@table @option
+@item n
+sequential number of the input frame, starting from 0
+
+@item pts
+Presentation timestamp of the input frame, in time base units; the time base
+depends on the filter input pad, and is usually 1/@var{sample_rate}.
+
+@item pts_time
+presentation timestamp of the input frame in seconds
+
+@item fmt
+sample format
+
+@item chlayout
+channel layout
+
+@item rate
+sample rate for the audio frame
+
+@item nb_samples
+number of samples (per channel) in the frame
+
+@item checksum
+Adler-32 checksum (printed in hexadecimal) of the audio data. For planar audio
+the data is treated as if all the planes were concatenated.
+
+@item plane_checksums
+A list of Adler-32 checksums for each data plane.
+@end table
+
+@section asplit
+
+Split input audio into several identical outputs.
+
+The filter accepts a single parameter which specifies the number of outputs. If
+unspecified, it defaults to 2.
+
+For example
+@example
+avconv -i INPUT -filter_complex asplit=5 OUTPUT
+@end example
+will create 5 copies of the input audio.
+
+@section asyncts
+Synchronize audio data with timestamps by squeezing/stretching it and/or
+dropping samples/adding silence when needed.
+
+The filter accepts the following named parameters:
+@table @option
+
+@item compensate
+Enable stretching/squeezing the data to make it match the timestamps. Disabled
+by default. When disabled, time gaps are covered with silence.
+
+@item min_delta
+Minimum difference between timestamps and audio data (in seconds) to trigger
+adding/dropping samples. Default value is 0.1. If you get non-perfect sync with
+this filter, try setting this parameter to 0.
+
+@item max_comp
+Maximum compensation in samples per second. Relevant only with compensate=1.
+Default value 500.
+
+@item first_pts
+Assume the first pts should be this value. The time base is 1 / sample rate.
+This allows for padding/trimming at the start of stream. By default, no
+assumption is made about the first frame's expected pts, so no padding or
+trimming is done. For example, this could be set to 0 to pad the beginning with
+silence if an audio stream starts after the video stream or to trim any samples
+with a negative pts due to encoder delay.
+
+@end table
+
+@section channelsplit
+Split each channel in input audio stream into a separate output stream.
+
+This filter accepts the following named parameters:
+@table @option
+@item channel_layout
+Channel layout of the input stream. Default is "stereo".
+@end table
+
+For example, assuming a stereo input MP3 file
+@example
+avconv -i in.mp3 -filter_complex channelsplit out.mkv
+@end example
+will create an output Matroska file with two audio streams, one containing only
+the left channel and the other the right channel.
+
+To split a 5.1 WAV file into per-channel files
+@example
+avconv -i in.wav -filter_complex
+'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
+-map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
+front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
+side_right.wav
+@end example
+
+@section channelmap
+Remap input channels to new locations.
+
+This filter accepts the following named parameters:
+@table @option
+@item channel_layout
+Channel layout of the output stream.
+
+@item map
+Map channels from input to output. The argument is a comma-separated list of
+mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
+@var{in_channel} form. @var{in_channel} can be either the name of the input
+channel (e.g. FL for front left) or its index in the input channel layout.
+@var{out_channel} is the name of the output channel or its index in the output
+channel layout. If @var{out_channel} is not given then it is implicitly an
+index, starting with zero and increasing by one for each mapping.
+@end table
+
+If no mapping is present, the filter will implicitly map input channels to
+output channels preserving index.
+
+For example, assuming a 5.1+downmix input MOV file
+@example
+avconv -i in.mov -filter 'channelmap=map=DL-FL\,DR-FR' out.wav
+@end example
+will create an output WAV file tagged as stereo from the downmix channels of
+the input.
+
+To fix a 5.1 WAV improperly encoded in AAC's native channel order
+@example
+avconv -i in.wav -filter 'channelmap=1\,2\,0\,5\,3\,4:channel_layout=5.1' out.wav
+@end example
+
+@section join
+Join multiple input streams into one multi-channel stream.
+
+The filter accepts the following named parameters:
+@table @option
+
+@item inputs
+Number of input streams. Defaults to 2.
+
+@item channel_layout
+Desired output channel layout. Defaults to stereo.
+
+@item map
+Map channels from inputs to output. The argument is a comma-separated list of
+mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
+form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
+can be either the name of the input channel (e.g. FL for front left) or its
+index in the specified input stream. @var{out_channel} is the name of the output
+channel.
+@end table
+
+The filter will attempt to guess the mappings when those are not specified
+explicitly. It does so by first trying to find an unused matching input channel
+and if that fails it picks the first unused input channel.
+
+E.g. to join 3 inputs (with properly set channel layouts)
+@example
+avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
+@end example
+
+To build a 5.1 output from 6 single-channel streams:
+@example
+avconv -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
+'join=inputs=6:channel_layout=5.1:map=0.0-FL\,1.0-FR\,2.0-FC\,3.0-SL\,4.0-SR\,5.0-LFE'
+out
+@end example
+
@section resample
Convert the audio sample format, sample rate and channel layout. This filter is
not meant to be used directly, it is inserted automatically by libavfilter
whenever conversion is needed. Use the @var{aformat} filter to force a specific
conversion.
+@section volume
+
+Adjust the input audio volume.
+
+The filter accepts the following named parameters:
+@table @option
+
+@item volume
+Expresses how the audio volume will be increased or decreased.
+
+Output values are clipped to the maximum value.
+
+The output audio volume is given by the relation:
+@example
+@var{output_volume} = @var{volume} * @var{input_volume}
+@end example
+
+Default value for @var{volume} is 1.0.
+
+@item precision
+Mathematical precision.
+
+This determines which input sample formats will be allowed, which affects the
+precision of the volume scaling.
+
+@table @option
+@item fixed
+8-bit fixed-point; limits input sample format to U8, S16, and S32.
+@item float
+32-bit floating-point; limits input sample format to FLT. (default)
+@item double
+64-bit floating-point; limits input sample format to DBL.
+@end table
+@end table
+
+@subsection Examples
+
+@itemize
+@item
+Halve the input audio volume:
+@example
+volume=volume=0.5
+volume=volume=1/2
+volume=volume=-6.0206dB
+@end example
+
+@item
+Increase input audio power by 6 decibels using fixed-point precision:
+@example
+volume=volume=6dB:precision=fixed
+@end example
+@end itemize
+
@c man end AUDIO FILTERS
@chapter Audio Sources
of @var{channel_layout} is 3, which corresponds to CH_LAYOUT_STEREO.
Check the channel_layout_map definition in
-@file{libavcodec/audioconvert.c} for the mapping between strings and
+@file{libavutil/channel_layout.c} for the mapping between strings and
channel layout values.
Follow some examples:
In order to display the output lines, you need to set the loglevel at
least to the AV_LOG_INFO value.
-The filter accepts the syntax:
-@example
-blackframe[=@var{amount}:[@var{threshold}]]
-@end example
+The filter accepts the following options:
-@var{amount} is the percentage of the pixels that have to be below the
-threshold, and defaults to 98.
+@table @option
+
+@item amount
+The percentage of the pixels that have to be below the threshold, defaults to
+98.
+
+@item threshold
+Threshold below which a pixel value is considered black, defaults to 32.
-@var{threshold} is the threshold below which a pixel value is
-considered black, and defaults to 32.
+@end table
@section boxblur
Apply boxblur algorithm to the input video.
-This filter accepts the parameters:
-@var{luma_power}:@var{luma_radius}:@var{chroma_radius}:@var{chroma_power}:@var{alpha_radius}:@var{alpha_power}
+This filter accepts the following options:
+
+@table @option
+
+@item luma_radius
+@item luma_power
+@item chroma_radius
+@item chroma_power
+@item alpha_radius
+@item alpha_power
+
+@end table
Chroma and alpha parameters are optional, if not specified they default
to the corresponding values set for @var{luma_radius} and
Apply a boxblur filter with luma, chroma, and alpha radius
set to 2:
@example
-boxblur=2:1
+boxblur=luma_radius=2:luma_power=1
@end example
@item
@item
Set luma and chroma radius to a fraction of the video dimension
@example
-boxblur=min(h\,w)/10:1:min(cw\,ch)/10:1
+boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
@end example
@end itemize
@section crop
-Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}.
+Crop the input video to given dimensions.
+
+This filter accepts the following options:
+
+@table @option
+
+@item out_w
+Width of the output video.
+
+@item out_h
+Height of the output video.
+
+@item x
+Horizontal position, in the input video, of the left edge of the output video.
+
+@item y
+Vertical position, in the input video, of the top edge of the output video.
+
+@end table
The parameters are expressions containing the following constants:
@item n
the number of input frame, starting from 0
-@item pos
-the position in the file of the input frame, NAN if unknown
-
@item t
timestamp expressed in seconds, NAN if the input timestamp is unknown
Follow some examples:
@example
# crop the central input area with size 100x100
-crop=100:100
+crop=out_w=100:out_h=100
# crop the central input area with size 2/3 of the input video
-"crop=2/3*in_w:2/3*in_h"
+"crop=out_w=2/3*in_w:out_h=2/3*in_h"
# crop the input video central square
-crop=in_h
+crop=out_w=in_h
# delimit the rectangle with the top-left corner placed at position
# 100:100 and the right-bottom corner corresponding to the right-bottom
# corner of the input image.
-crop=in_w-100:in_h-100:100:100
+crop=out_w=in_w-100:out_h=in_h-100:x=100:y=100
# crop 10 pixels from the left and right borders, and 20 pixels from
# the top and bottom borders
-"crop=in_w-2*10:in_h-2*20"
+"crop=out_w=in_w-2*10:out_h=in_h-2*20"
# keep only the bottom right quarter of the input image
-"crop=in_w/2:in_h/2:in_w/2:in_h/2"
+"crop=out_w=in_w/2:out_h=in_h/2:x=in_w/2:y=in_h/2"
# crop height for getting Greek harmony
-"crop=in_w:1/PHI*in_w"
+"crop=out_w=in_w:out_h=1/PHI*in_w"
# trembling effect
"crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(n/10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(n/7)"
# erratic camera effect depending on timestamp
-"crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)"
+"crop=out_w=in_w/2:out_h=in_h/2:x=(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):y=(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)"
# set x depending on the value of y
"crop=in_w/2:in_h/2:y:10+10*sin(n/10)"
parameters through the logging system. The detected dimensions
correspond to the non-black area of the input video.
-It accepts the syntax:
-@example
-cropdetect[=@var{limit}[:@var{round}[:@var{reset}]]]
-@end example
+This filter accepts the following options:
@table @option
Libavfilter will try to pick one that is supported for the input to
the next filter.
-The filter accepts a list of pixel format names, separated by ":",
-for example "yuv420p:monow:rgb24".
+This filter accepts the following parameters:
+@table @option
+
+@item pix_fmts
+A '|'-separated list of pixel format names, for example
+"pix_fmts=yuv420p|monow|rgb24".
+
+@end table
Some examples follow:
@example
# convert the input video to the format "yuv420p"
-format=yuv420p
+format=pix_fmts=yuv420p
# convert the input video to any of the formats in the list
-format=yuv420p:yuv444p:yuv410p
+format=pix_fmts=yuv420p|yuv444p|yuv410p
@end example
+@section fps
+
+Convert the video to specified constant framerate by duplicating or dropping
+frames as necessary.
+
+This filter accepts the following named parameters:
+@table @option
+
+@item fps
+Desired output framerate.
+
+@end table
+
@anchor{frei0r}
@section frei0r
@var{strength} is the maximum amount by which the filter will change
any one pixel. Also the threshold for detecting nearly flat
-regions. Acceptable values range from .51 to 255, default value is
+regions. Acceptable values range from .51 to 64, default value is
1.2, out-of-range values will be clipped to the valid range.
@var{radius} is the neighborhood to fit the gradient to. A larger
The @var{lut} filter requires either YUV or RGB pixel formats in
input, and accepts the options:
@table @option
-@var{c0} (first pixel component)
-@var{c1} (second pixel component)
-@var{c2} (third pixel component)
-@var{c3} (fourth pixel component, corresponds to the alpha component)
+@item @var{c0} (first pixel component)
+@item @var{c1} (second pixel component)
+@item @var{c2} (third pixel component)
+@item @var{c3} (fourth pixel component, corresponds to the alpha component)
@end table
The exact component associated to each option depends on the format in
The @var{lutrgb} filter requires RGB pixel formats in input, and
accepts the options:
@table @option
-@var{r} (red component)
-@var{g} (green component)
-@var{b} (blue component)
-@var{a} (alpha component)
+@item @var{r} (red component)
+@item @var{g} (green component)
+@item @var{b} (blue component)
+@item @var{a} (alpha component)
@end table
The @var{lutyuv} filter requires YUV pixel formats in input, and
accepts the options:
@table @option
-@var{y} (Y/luminance component)
-@var{u} (U/Cb component)
-@var{v} (V/Cr component)
-@var{a} (alpha component)
+@item @var{y} (Y/luminance component)
+@item @var{u} (U/Cb component)
+@item @var{v} (V/Cr component)
+@item @var{a} (alpha component)
@end table
The expressions can contain the following constants and functions:
This filter accepts an integer in input, if non-zero it negates the
alpha component (if available). The default value in input is 0.
+@section noformat
+
Force libavfilter not to use any of the specified pixel formats for the
input to the next filter.
-The filter accepts a list of pixel format names, separated by ":",
-for example "yuv420p:monow:rgb24".
+This filter accepts the following parameters:
+@table @option
+
+@item pix_fmts
+A '|'-separated list of pixel format names, for example
+"pix_fmts=yuv420p|monow|rgb24".
+
+@end table
Some examples follow:
@example
# force libavfilter to use a format different from "yuv420p" for the
# input to the vflip filter
-noformat=yuv420p,vflip
+noformat=pix_fmts=yuv420p,vflip
# convert the input video to any of the formats not contained in the list
-noformat=yuv420p:yuv444p:yuv410p
+noformat=yuv420p|yuv444p|yuv410p
@end example
@section null
@item key
1 if the filtered frame is a key-frame, 0 otherwise
-@item pos
-the position in the file of the filtered frame, -1 if the information
-is not available (e.g. for synthetic video)
@end table
The default value of the select expression is "1".
be changed by later filters in the filterchain, e.g. in case of
scaling or if another "setdar" or a "setsar" filter is applied.
-The filter accepts a parameter string which represents the wanted
-display aspect ratio.
-The parameter can be a floating point number string, or an expression
-of the form @var{num}:@var{den}, where @var{num} and @var{den} are the
-numerator and denominator of the aspect ratio.
-If the parameter is not specified, it is assumed the value "0:1".
+This filter accepts the following options:
+
+@table @option
+
+@item dar
+Output display aspect ratio, as a rational or a decimal number.
+
+@end table
For example to change the display aspect ratio to 16:9, specify:
@example
-setdar=16:9
+setdar=dar=16/9
# the above is equivalent to
-setdar=1.77777
+setdar=dar=1.77777
@end example
See also the @ref{setsar} filter documentation.
@item INTERLACED
tell if the current frame is interlaced
-@item POS
-original position in the file of the frame, or undefined if undefined
-for the current frame
-
@item PREV_INPTS
previous input PTS
@item PREV_OUTPTS
previous output PTS
+@item RTCTIME
+wallclock (RTC) time in microseconds
+
+@item RTCSTART
+wallclock (RTC) time at the start of the movie in microseconds
+
@end table
Some examples follow:
# fixed rate 25 fps with some jitter
setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
+
+# generate timestamps from a "live source" and rebase onto the current timebase
+setpts='(RTCTIME - RTCSTART) / (TB * 1000000)"
@end example
@anchor{setsar}
changed by later filters in the filterchain, e.g. if another "setsar"
or a "setdar" filter is applied.
-The filter accepts a parameter string which represents the wanted
-sample aspect ratio.
-The parameter can be a floating point number string, or an expression
-of the form @var{num}:@var{den}, where @var{num} and @var{den} are the
-numerator and denominator of the aspect ratio.
-If the parameter is not specified, it is assumed the value "0:1".
+This filter accepts the following options:
+
+@table @option
+
+@item sar
+Output sample aspect ratio, as a rational or decimal number.
+
+@end table
For example to change the sample aspect ratio to 10:11, specify:
@example
-setsar=10:11
+setsar=sar=10/11
@end example
@section settb
"[@var{c0} @var{c1} @var{c2} @var{c3}]"
@end table
-@section slicify
-
-Pass the images of input video on to next video filter as multiple
-slices.
-
-@example
-./avconv -i in.avi -vf "slicify=32" out.avi
-@end example
-
-The filter accepts the slice height as parameter. If the parameter is
-not specified it will use the default value of 16.
-
-Adding this in the beginning of filter chains should make filtering
-faster due to better use of the memory cache.
-
@section split
Split input video into several identical outputs.
This source is mainly intended for a programmatic use, in particular
through the interface defined in @file{libavfilter/vsrc_buffer.h}.
-It accepts the following parameters:
-@var{width}:@var{height}:@var{pix_fmt_string}:@var{timebase_num}:@var{timebase_den}:@var{sample_aspect_ratio_num}:@var{sample_aspect_ratio.den}
+This filter accepts the following parameters:
-All the parameters need to be explicitly defined.
+@table @option
-Follows the list of the accepted parameters.
+@item width
+Input video width.
-@table @option
+@item height
+Input video height.
-@item width, height
-Specify the width and height of the buffered video frames.
+@item pix_fmt
+Name of the input video pixel format.
-@item pix_fmt_string
-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
-name.
+@item time_base
+The time base used for input timestamps.
-@item timebase_num, timebase_den
-Specify numerator and denomitor of the timebase assumed by the
-timestamps of the buffered frames.
+@item sar
+Sample (pixel) aspect ratio of the input video.
-@item sample_aspect_ratio.num, sample_aspect_ratio.den
-Specify numerator and denominator of the sample aspect ratio assumed
-by the video frames.
@end table
For example:
@example
-buffer=320:240:yuv410p:1:24: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
with format "yuv410p", assuming 1/24 as the timestamps timebase and
square pixels (1:1 sample aspect ratio).
-Since the pixel format with name "yuv410p" corresponds to the number 6
-(check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),
-this example corresponds to:
-@example
-buffer=320:240:6:1:24
-@end example
@section color
Read a video stream from a movie container.
+Note that this source is a hack that bypasses the standard input path. It can be
+useful in applications that do not support arbitrary filter graphs, but its use
+is discouraged in those that do. Specifically in @command{avconv} this filter
+should never be used, the @option{-filter_complex} option fully replaces it.
+
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),