recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex}
options in @command{avconv} and @option{-vf} in @command{avplay}, 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
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
+Libavfilter will automatically insert @ref{scale} filters where format
conversion is required. It is possible to specify swscale flags
for those automatically inserted scalers by prepending
@code{sws_flags=@var{flags};}
Pass the audio source unchanged to the output.
+@section asetpts
+
+Change the PTS (presentation timestamp) of the input audio frames.
+
+This filter accepts the following options:
+
+@table @option
+
+@item expr
+The expression which is evaluated for each frame to construct its timestamp.
+
+@end table
+
+The expression is evaluated through the eval API and can contain the following
+constants:
+
+@table @option
+@item PTS
+the presentation timestamp in input
+
+@item PI
+Greek PI
+
+@item PHI
+golden ratio
+
+@item E
+Euler number
+
+@item N
+Number of the audio samples pass through the filter so far, starting at 0.
+
+@item S
+Number of the audio samples in the current frame.
+
+@item SR
+Audio sample rate.
+
+@item STARTPTS
+the PTS of the first 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:
+
+@example
+# start counting PTS from zero
+asetpts=expr=PTS-STARTPTS
+
+#generate timestamps by counting samples
+asetpts=expr=N/SR/TB
+
+# generate timestamps from a "live source" and rebase onto the current timebase
+asetpts='(RTCTIME - RTCSTART) / (TB * 1000000)"
+@end example
+
+
@section ashowinfo
Show a line containing various information for each input audio frame.
@end table
+@section atrim
+Trim the input so that the output contains one continuous subpart of the input.
+
+This filter accepts the following options:
+@table @option
+@item start
+Timestamp (in seconds) of the start of the kept section. I.e. the audio sample
+with the timestamp @var{start} will be the first sample in the output.
+
+@item end
+Timestamp (in seconds) of the first audio sample that will be dropped. I.e. the
+audio sample immediately preceding the one with the timestamp @var{end} will be
+the last sample in the output.
+
+@item start_pts
+Same as @var{start}, except this option sets the start timestamp in samples
+instead of seconds.
+
+@item end_pts
+Same as @var{end}, except this option sets the end timestamp in samples instead
+of seconds.
+
+@item duration
+Maximum duration of the output in seconds.
+
+@item start_sample
+Number of the first sample that should be passed to output.
+
+@item end_sample
+Number of the first sample that should be dropped.
+@end table
+
+Note that the first two sets of the start/end options and the @option{duration}
+option look at the frame timestamp, while the _sample options simply count the
+samples that pass through the filter. So start/end_pts and start/end_sample will
+give different results when the timestamps are wrong, inexact or do not start at
+zero. Also note that this filter does not modify the timestamps. If you wish
+that the output timestamps start at zero, insert the asetpts filter after the
+atrim filter.
+
+If multiple start or end options are set, this filter tries to be greedy and
+keep all samples that match at least one of the specified constraints. To keep
+only the part that matches all the constraints at once, chain multiple atrim
+filters.
+
+The defaults are such that all the input is kept. So it is possible to set e.g.
+just the end values to keep everything before the specified time.
+
+Examples:
+@itemize
+@item
+drop everything except the second minute of input
+@example
+avconv -i INPUT -af atrim=60:120
+@end example
+
+@item
+keep only the first 1000 samples
+@example
+avconv -i INPUT -af atrim=end_sample=1000
+@end example
+
+@end itemize
+
@section channelsplit
Split each channel in input audio stream into a separate output stream.
Channel layout of the output stream.
@item map
-Map channels from input to output. The argument is a comma-separated list of
+Map channels from input to output. The argument is a '|'-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.
For example, assuming a 5.1+downmix input MOV file
@example
-avconv -i in.mov -filter 'channelmap=map=DL-FL\,DR-FR' out.wav
+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
+avconv -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav
@end example
+@section compand
+Compress or expand audio dynamic range.
+
+A description of the accepted options follows.
+
+@table @option
+
+@item attacks
+@item decays
+Set list of times in seconds for each channel over which the instantaneous level
+of the input signal is averaged to determine its volume. @var{attacks} refers to
+increase of volume and @var{decays} refers to decrease of volume. For most
+situations, the attack time (response to the audio getting louder) should be
+shorter than the decay time because the human ear is more sensitive to sudden
+loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
+a typical value for decay is 0.8 seconds.
+
+@item points
+Set list of points for the transfer function, specified in dB relative to the
+maximum possible signal amplitude. Each key points list must be defined using
+the following syntax: @code{x0/y0|x1/y1|x2/y2|....}
+
+The input values must be in strictly increasing order but the transfer function
+does not have to be monotonically rising. The point @code{0/0} is assumed but
+may be overridden (by @code{0/out-dBn}). Typical values for the transfer
+function are @code{-70/-70|-60/-20}.
+
+@item soft-knee
+Set the curve radius in dB for all joints. Defaults to 0.01.
+
+@item gain
+Set additional gain in dB to be applied at all points on the transfer function.
+This allows easy adjustment of the overall gain. Defaults to 0.
+
+@item volume
+Set initial volume in dB to be assumed for each channel when filtering starts.
+This permits the user to supply a nominal level initially, so that, for
+example, a very large gain is not applied to initial signal levels before the
+companding has begun to operate. A typical value for audio which is initially
+quiet is -90 dB. Defaults to 0.
+
+@item delay
+Set delay in seconds. The input audio is analyzed immediately, but audio is
+delayed before being fed to the volume adjuster. Specifying a delay
+approximately equal to the attack/decay times allows the filter to effectively
+operate in predictive rather than reactive mode. Defaults to 0.
+
+@end table
+
+@subsection Examples
+
+@itemize
+@item
+Make music with both quiet and loud passages suitable for listening in a noisy
+environment:
+@example
+compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
+@end example
+
+@item
+Noise gate for when the noise is at a lower level than the signal:
+@example
+compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
+@end example
+
+@item
+Here is another noise gate, this time for when the noise is at a higher level
+than the signal (making it, in some ways, similar to squelch):
+@example
+compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
+@end example
+@end itemize
+
@section join
Join multiple input streams into one multi-channel stream.
Desired output channel layout. Defaults to stereo.
@item map
-Map channels from inputs to output. The argument is a comma-separated list of
+Map channels from inputs to output. The argument is a '|'-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
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'
+'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
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
pixels. Just set a rectangle covering the logo and watch it disappear
(and sometimes something even uglier appear - your mileage may vary).
-The filter accepts parameters as a string of the form
-"@var{x}:@var{y}:@var{w}:@var{h}:@var{band}", or as a list of
-@var{key}=@var{value} pairs, separated by ":".
-
-The description of the accepted parameters follows.
-
+This filter accepts the following options:
@table @option
@item x, y
Set a rectangle covering the area with top left corner coordinates 0,0
and size 100x77, setting a band of size 10:
@example
-delogo=0:0:100:77:10
-@end example
-
-@item
-As the previous example, but use named options:
-@example
delogo=x=0:y=0:w=100:h=77:band=10
@end example
Draw a colored box on the input image.
-It accepts the syntax:
-@example
-drawbox=@var{x}:@var{y}:@var{width}:@var{height}:@var{color}
-@end example
+This filter accepts the following options:
@table @option
drawbox
# draw a box with color red and an opacity of 50%
-drawbox=10:20:200:60:red@@0.5"
+drawbox=x=10:y=20:width=200:height=60:color=red@@0.5"
@end example
@section drawtext
The filter also recognizes strftime() sequences in the provided text
and expands them accordingly. Check the documentation of strftime().
-The filter accepts parameters as a list of @var{key}=@var{value} pairs,
-separated by ":".
-
The description of the accepted parameters follows.
@table @option
Apply fade-in/out effect to input video.
-It accepts the parameters:
-@var{type}:@var{start_frame}:@var{nb_frames}
+This filter accepts the following options:
+
+@table @option
-@var{type} specifies if the effect type, can be either "in" for
-fade-in, or "out" for a fade-out effect.
+@item type
+The effect type -- can be either "in" for fade-in, or "out" for a fade-out
+effect.
-@var{start_frame} specifies the number of the start frame for starting
-to apply the fade effect.
+@item start_frame
+The number of the start frame for starting to apply the fade effect.
-@var{nb_frames} specifies the number of frames for which the fade
-effect has to last. At the end of the fade-in effect the output video
-will have the same intensity as the input video, at the end of the
-fade-out transition the output video will be completely black.
+@item nb_frames
+The number of frames for which the fade effect has to last. At the end of the
+fade-in effect the output video will have the same intensity as the input video,
+at the end of the fade-out transition the output video will be completely black.
+
+@end table
A few usage examples follow, usable too as test scenarios.
@example
# fade in first 30 frames of video
-fade=in:0:30
+fade=type=in:nb_frames=30
# fade out last 45 frames of a 200-frame video
-fade=out:155:45
+fade=type=out:start_frame=155:nb_frames=45
# fade in first 25 frames and fade out last 25 frames of a 1000-frame video
-fade=in:0:25, fade=out:975:25
+fade=type=in:start_frame=0:nb_frames=25, fade=type=out:start_frame=975:nb_frames=25
# make first 5 frames black, then fade in from frame 5-24
-fade=in:5:20
+fade=type=in:start_frame=5:nb_frames=20
@end example
@section fieldorder
Transform the field order of the input video.
-It accepts one parameter which specifies the required field order that
-the input interlaced video will be transformed to. The parameter can
-assume one of the following values:
+This filter accepts the following options:
@table @option
-@item 0 or bff
-output bottom field first
-@item 1 or tff
-output top field first
+
+@item order
+Output field order. Valid values are @var{tff} for top field first or @var{bff}
+for bottom field first.
@end table
Default value is "tff".
For example:
@example
-./avconv -i in.vob -vf "fieldorder=bff" out.dv
+./avconv -i in.vob -vf "fieldorder=order=bff" out.dv
@end example
@section fifo
format=pix_fmts=yuv420p|yuv444p|yuv410p
@end example
+@anchor{fps}
@section fps
Convert the video to specified constant framerate by duplicating or dropping
@item fps
Desired output framerate.
+@item start_time
+Assume the first PTS should be the given value, in seconds. 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 duplicates of
+the first frame if a video stream starts after the audio stream or to trim any
+frames with a negative PTS.
+
+@end table
+
+@section framepack
+
+Pack two different video streams into a stereoscopic video, setting proper
+metadata on supported codecs. The two views should have the same size and
+framerate and processing will stop when the shorter video ends. Please note
+that you may conveniently adjust view properties with the @ref{scale} and
+@ref{fps} filters.
+
+This filter accepts the following named parameters:
+@table @option
+
+@item format
+Desired packing format. Supported values are:
+
+@table @option
+
+@item sbs
+Views are next to each other (default).
+
+@item tab
+Views are on top of each other.
+
+@item lines
+Views are packed by line.
+
+@item columns
+Views are eacked by column.
+
+@item frameseq
+Views are temporally interleaved.
+
@end table
+@end table
+
+Some examples follow:
+
+@example
+# Convert left and right views into a frame sequential video.
+avconv -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
+
+# Convert views into a side-by-side video with the same output resolution as the input.
+avconv -i LEFT -i RIGHT -filter_complex [0:v]scale=w=iw/2[left],[1:v]scale=w=iw/2[right],[left][right]framepack=sbs OUTPUT
+@end example
+
@anchor{frei0r}
@section frei0r
To enable compilation of this filter you need to install the frei0r
header and configure Libav with --enable-frei0r.
-The filter supports the syntax:
-@example
-@var{filter_name}[@{:|=@}@var{param1}:@var{param2}:...:@var{paramN}]
-@end example
+This filter accepts the following options:
+
+@table @option
-@var{filter_name} is the name to the frei0r effect to load. If the
-environment variable @env{FREI0R_PATH} is defined, the frei0r effect
-is searched in each one of the directories specified by the colon
-separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r
-paths, which are in this order: @file{HOME/.frei0r-1/lib/},
-@file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}.
+@item filter_name
+The name to the frei0r effect to load. If the environment variable
+@env{FREI0R_PATH} is defined, the frei0r effect is searched in each one of the
+directories specified by the colon separated list in @env{FREIOR_PATH},
+otherwise in the standard frei0r paths, which are in this order:
+@file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
+@file{/usr/lib/frei0r-1/}.
-@var{param1}, @var{param2}, ... , @var{paramN} specify the parameters
-for the frei0r effect.
+@item filter_params
+A '|'-separated list of parameters to pass to the frei0r effect.
+
+@end table
A frei0r effect parameter can be a boolean (whose values are specified
with "y" and "n"), a double, a color (specified by the syntax
Some examples follow:
@example
# apply the distort0r effect, set the first two double parameters
-frei0r=distort0r:0.5:0.01
+frei0r=filter_name=distort0r:filter_params=0.5|0.01
# apply the colordistance effect, takes a color as first parameter
frei0r=colordistance:0.2/0.3/0.4
# apply the perspective effect, specify the top left and top right
# image positions
-frei0r=perspective:0.2/0.2:0.8/0.2
+frei0r=perspective:0.2/0.2|0.8/0.2
@end example
For more information see:
lossy compression, because compression tends to lose the dither and
bring back the bands.
-The filter takes two optional parameters, separated by ':':
-@var{strength}:@var{radius}
+This filter accepts the following options:
+
+@table @option
+
+@item strength
+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
+64, default value is 1.2, out-of-range values will be clipped to the valid
+range.
-@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 64, default value is
-1.2, out-of-range values will be clipped to the valid range.
+@item radius
+The neighborhood to fit the gradient to. A larger radius makes for smoother
+gradients, but also prevents the filter from modifying the pixels near detailed
+regions. Acceptable values are 8-32, default value is 16, out-of-range values
+will be clipped to the valid range.
-@var{radius} is the neighborhood to fit the gradient to. A larger
-radius makes for smoother gradients, but also prevents the filter from
-modifying the pixels near detailed regions. Acceptable values are
-8-32, default value is 16, out-of-range values will be clipped to the
-valid range.
+@end table
@example
# default parameters
-gradfun=1.2:16
+gradfun=strength=1.2:radius=16
# omitting radius
gradfun=1.2
still. It should enhance compressibility.
It accepts the following optional parameters:
-@var{luma_spatial}:@var{chroma_spatial}:@var{luma_tmp}:@var{chroma_tmp}
@table @option
@item luma_spatial
@var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}
@end table
+@section interlace
+
+Simple interlacing filter from progressive contents. This interleaves upper (or
+lower) lines from odd frames with lower (or upper) lines from even frames,
+halving the frame rate and preserving image height. A vertical lowpass filter
+is always applied in order to avoid twitter effects and reduce moiré patterns.
+
+@example
+ Original Original New Frame
+ Frame 'j' Frame 'j+1' (tff)
+ ========== =========== ==================
+ Line 0 --------------------> Frame 'j' Line 0
+ Line 1 Line 1 ----> Frame 'j+1' Line 1
+ Line 2 ---------------------> Frame 'j' Line 2
+ Line 3 Line 3 ----> Frame 'j+1' Line 3
+ ... ... ...
+New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
+@end example
+
+It accepts the following optional parameters:
+
+@table @option
+@item scan
+determines whether the interlaced frame is taken from the even (tff - default)
+or odd (bff) lines of the progressive frame.
+@end table
+
@section lut, lutrgb, lutyuv
Compute a look-up table for binding each pixel component input value
@var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
to an RGB input video.
-These filters accept in input a ":"-separated list of options, which
-specify the expressions used for computing the lookup table for the
-corresponding pixel component values.
-
-The @var{lut} filter requires either YUV or RGB pixel formats in
-input, and accepts the options:
+These filters accept the following options:
@table @option
@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
-input.
-
-The @var{lutrgb} filter requires RGB pixel formats in input, and
-accepts the options:
-@table @option
@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
@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
+Each of them specifies the expression to use for computing the lookup table for
+the corresponding pixel component values.
+
+The exact component associated to each of the @var{c*} options depends on the
+format in input.
+
+The @var{lut} filter requires either YUV or RGB pixel formats in input,
+@var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
+
The expressions can contain the following constants and functions:
@table @option
To enable this filter install libopencv library and headers and
configure Libav with --enable-libopencv.
-The filter takes the parameters: @var{filter_name}@{:=@}@var{filter_params}.
+This filter accepts the following parameters:
+
+@table @option
+
+@item filter_name
+The name of the libopencv filter to apply.
-@var{filter_name} is the name of the libopencv filter to apply.
+@item filter_params
+The parameters to pass to the libopencv filter. If not specified the default
+values are assumed.
-@var{filter_params} specifies the parameters to pass to the libopencv
-filter. If not specified the default values are assumed.
+@end table
Refer to the official libopencv documentation for more precise
information:
Dilate an image by using a specific structuring element.
This filter corresponds to the libopencv function @code{cvDilate}.
-It accepts the parameters: @var{struct_el}:@var{nb_iterations}.
+It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
@var{struct_el} represents a structuring element, and has the syntax:
@var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
ocv=dilate
# dilate using a structuring element with a 5x5 cross, iterate two times
-ocv=dilate=5x5+2x2/cross:2
+ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
# read the shape from the file diamond.shape, iterate two times
# the file diamond.shape may contain a pattern of characters like this:
# ***
# *
# the specified cols and rows are ignored (but not the anchor point coordinates)
-ocv=0x0+2x2/custom=diamond.shape:2
+ocv=dilate:0x0+2x2/custom=diamond.shape|2
@end example
@subsection erode
Smooth the input video.
The filter takes the following parameters:
-@var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
+@var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
@var{type} is the type of smooth filter to apply, and can be one of
the following values: "blur", "blur_no_scale", "median", "gaussian",
It takes two inputs and one output, the first input is the "main"
video on which the second input is overlayed.
-It accepts the parameters: @var{x}:@var{y}.
+This filter accepts the following parameters:
+
+@table @option
+
+@item x
+The horizontal position of the left edge of the overlaid video on the main video.
+
+@item y
+The vertical position of the top edge of the overlaid video on the main video.
+
+@end table
-@var{x} is the x coordinate of the overlayed video on the main video,
-@var{y} is the y coordinate. The parameters are expressions containing
-the following parameters:
+The parameters are expressions containing the following parameters:
@table @option
@item main_w, main_h
@item w, h
same as @var{overlay_w} and @var{overlay_h}
+
+@item eof_action
+The action to take when EOF is encountered on the secondary input, accepts one
+of the following values:
+
+@table @option
+@item repeat
+repeat the last frame (the default)
+@item endall
+end both streams
+@item pass
+pass through the main input
+@end table
+
@end table
Be aware that frames are taken from each input video in timestamp
@example
# draw the overlay at 10 pixels from the bottom right
# corner of the main video.
-overlay=main_w-overlay_w-10:main_h-overlay_h-10
+overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
# insert a transparent PNG logo in the bottom left corner of the input
-avconv -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
+avconv -i input -i logo -filter_complex 'overlay=x=10:y=main_h-overlay_h-10' output
# insert 2 different transparent PNG logos (second logo on bottom
# right corner):
avconv -i input -i logo1 -i logo2 -filter_complex
-'overlay=10:H-h-10,overlay=W-w-10:H-h-10' output
+'overlay=x=10:y=H-h-10,overlay=x=W-w-10:y=H-h-10' output
# add a transparent color layer on top of the main video,
# WxH specifies the size of the main input to the overlay filter
color=red@.3:WxH [over]; [in][over] overlay [out]
+
+# mask 10-20 seconds of a video by applying the delogo filter to a section
+avconv -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
+-vf '[in]split[split_main][split_delogo];[split_delogo]trim=start=360:end=371,delogo=0:0:640:480[delogoed];[split_main][delogoed]overlay=eof_action=pass[out]'
+masked.avi
@end example
You can chain together more overlays but the efficiency of such
Add paddings to the input image, and places the original input at the
given coordinates @var{x}, @var{y}.
-It accepts the following parameters:
-@var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
+This filter accepts the following parameters:
+
+@table @option
+@item width, height
+
+Specify the size of the output image with the paddings added. If the
+value for @var{width} or @var{height} is 0, the corresponding input size
+is used for the output.
+
+The @var{width} expression can reference the value set by the
+@var{height} expression, and vice versa.
+
+The default value of @var{width} and @var{height} is 0.
+
+@item x, y
+
+Specify the offsets where to place the input image in the padded area
+with respect to the top/left border of the output image.
+
+The @var{x} expression can reference the value set by the @var{y}
+expression, and vice versa.
+
+The default value of @var{x} and @var{y} is 0.
+
+@item color
+
+Specify the color of the padded area, it can be the name of a color
+(case insensitive match) or a 0xRRGGBB[AA] sequence.
+
+The default value of @var{color} is "black".
+
+@end table
The parameters @var{width}, @var{height}, @var{x}, and @var{y} are
expressions containing the following constants:
pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
@end table
-Follows the description of the accepted parameters.
-
-@table @option
-@item width, height
-
-Specify the size of the output image with the paddings added. If the
-value for @var{width} or @var{height} is 0, the corresponding input size
-is used for the output.
-
-The @var{width} expression can reference the value set by the
-@var{height} expression, and vice versa.
-
-The default value of @var{width} and @var{height} is 0.
-
-@item x, y
-
-Specify the offsets where to place the input image in the padded area
-with respect to the top/left border of the output image.
-
-The @var{x} expression can reference the value set by the @var{y}
-expression, and vice versa.
-
-The default value of @var{x} and @var{y} is 0.
-
-@item color
-
-Specify the color of the padded area, it can be the name of a color
-(case insensitive match) or a 0xRRGGBB[AA] sequence.
-
-The default value of @var{color} is "black".
-
-@end table
-
Some examples follow:
@example
# Add paddings with color "violet" to the input video. Output video
# size is 640x480, the top-left corner of the input video is placed at
# column 0, row 40.
-pad=640:480:0:40:violet
+pad=width=640:height=480:x=0:y=40:color=violet
# pad the input to get an output with dimensions increased bt 3/2,
# and put the input video at the center of the padded area
can be used to test the monowhite pixel format descriptor definition.
+@anchor{scale}
@section scale
-Scale the input video to @var{width}:@var{height} and/or convert the image format.
+Scale the input video and/or convert the image format.
-The parameters @var{width} and @var{height} are expressions containing
+This filter accepts the following options:
+
+@table @option
+
+@item w
+Output video width.
+
+@item h
+Output video height.
+
+@end table
+
+The parameters @var{w} and @var{h} are expressions containing
the following constants:
@table @option
@item ow, oh
same as @var{out_w} and @var{out_h}
-@item dar, a
-input display aspect ratio, same as @var{iw} / @var{ih}
+@item a
+same as @var{iw} / @var{ih}
@item sar
input sample aspect ratio
+@item dar
+input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
+
@item hsub, vsub
horizontal and vertical chroma subsample values. For example for the
pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
the next filter, the scale filter will convert the input to the
requested format.
-If the value for @var{width} or @var{height} is 0, the respective input
+If the value for @var{w} or @var{h} is 0, the respective input
size is used for the output.
-If the value for @var{width} or @var{height} is -1, the scale filter will
-use, for the respective output size, a value that maintains the aspect
-ratio of the input image.
+If the value for @var{w} or @var{h} is -1, the scale filter will use, for the
+respective output size, a value that maintains the aspect ratio of the input
+image.
-The default value of @var{width} and @var{height} is 0.
+The default value of @var{w} and @var{h} is 0.
Some examples follow:
@example
# scale the input video to a size of 200x100.
-scale=200:100
+scale=w=200:h=100
# scale the input to 2x
-scale=2*iw:2*ih
+scale=w=2*iw:h=2*ih
# the above is the same as
scale=2*in_w:2*in_h
# scale the input to half size
-scale=iw/2:ih/2
+scale=w=iw/2:h=ih/2
# increase the width, and set the height to the same size
scale=3/2*iw:ow
scale=ih*PHI:ih
# increase the height, and set the width to 3/2 of the height
-scale=3/2*oh:3/5*ih
+scale=w=3/2*oh:h=3/5*ih
# increase the size, but make the size a multiple of the chroma
scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
# increase the width to a maximum of 500 pixels, keep the same input aspect ratio
-scale='min(500\, iw*3/2):-1'
+scale=w='min(500\, iw*3/2):h=-1'
@end example
@section select
Select frames to pass in output.
-It accepts in input 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.
+This filter accepts the following options:
+
+@table @option
+
+@item expr
+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.
+
+@end table
The expression can contain the following constants:
select
# the above is the same as:
-select=1
+select=expr=1
# skip all frames:
-select=0
+select=expr=0
# select only I-frames
-select='eq(pict_type\,I)'
+select='expr=eq(pict_type\,I)'
# select one frame every 100
select='not(mod(n\,100))'
@table @option
@item dar
-Output display aspect ratio, as a rational or a decimal number.
+Output display aspect ratio.
+
+@end table
+
+The parameter @var{dar} is an expression containing
+the following constants:
+
+@table @option
+@item E, PI, PHI
+the corresponding mathematical approximated values for e
+(euler number), pi (greek PI), phi (golden ratio)
+
+@item w, h
+the input width and height
+
+@item a
+same as @var{w} / @var{h}
+
+@item sar
+input sample aspect ratio
+
+@item dar
+input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
+@item hsub, vsub
+horizontal and vertical chroma subsample values. For example for the
+pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
@end table
For example to change the display aspect ratio to 16:9, specify:
Change the PTS (presentation timestamp) of the input video frames.
-Accept in input an expression evaluated through the eval API, which
-can contain the following constants:
+This filter accepts the following options:
+
+@table @option
+
+@item expr
+The expression which is evaluated for each frame to construct its timestamp.
+
+@end table
+
+The expression is evaluated through the eval API and can contain the following
+constants:
@table @option
@item PTS
@item RTCSTART
wallclock (RTC) time at the start of the movie in microseconds
+@item TB
+timebase of the input timestamps
+
@end table
Some examples follow:
@example
# start counting PTS from zero
-setpts=PTS-STARTPTS
+setpts=expr=PTS-STARTPTS
# fast motion
-setpts=0.5*PTS
+setpts=expr=0.5*PTS
# slow motion
setpts=2.0*PTS
@table @option
@item sar
-Output sample aspect ratio, as a rational or decimal number.
+Output sample aspect ratio.
@end table
+The parameter @var{sar} is an expression containing
+the following constants:
+
+@table @option
+@item E, PI, PHI
+the corresponding mathematical approximated values for e
+(euler number), pi (greek PI), phi (golden ratio)
+
+@item w, h
+the input width and height
+
+@item a
+same as @var{w} / @var{h}
+
+@item sar
+input sample aspect ratio
+
+@item dar
+input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
+
+@item hsub, vsub
+horizontal and vertical chroma subsample values. For example for the
+pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
+@end table
+
For example to change the sample aspect ratio to 10:11, specify:
@example
setsar=sar=10/11
Set the timebase to use for the output frames timestamps.
It is mainly useful for testing timebase configuration.
-It accepts in input an arithmetic expression representing a rational.
+This filter accepts the following options:
+
+@table @option
+
+@item expr
+The expression which is evaluated into the output timebase.
+
+@end table
+
The expression can contain the constants "PI", "E", "PHI", "AVTB" (the
default timebase), and "intb" (the input timebase).
@example
# set the timebase to 1/25
-settb=1/25
+settb=expr=1/25
# set the timebase to 1/10
-settb=0.1
+settb=expr=0.1
#set the timebase to 1001/1000
settb=1+0.001
"[@var{c0} @var{c1} @var{c2} @var{c3}]"
@end table
+@section shuffleplanes
+
+Reorder and/or duplicate video planes.
+
+This filter accepts the following options:
+
+@table @option
+
+@item map0
+The index of the input plane to be used as the first output plane.
+
+@item map1
+The index of the input plane to be used as the second output plane.
+
+@item map2
+The index of the input plane to be used as the third output plane.
+
+@item map3
+The index of the input plane to be used as the fourth output plane.
+
+@end table
+
+The first plane has the index 0. The default is to keep the input unchanged.
+
+E.g.
+@example
+avconv -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
+@end example
+swaps the second and third planes of the input.
+
@section split
Split input video into several identical outputs.
Transpose rows with columns in the input video and optionally flip it.
-It accepts a parameter representing an integer, which can assume the
-values:
+This filter accepts the following options:
+
+@table @option
+
+@item dir
+The direction of the transpose.
+
+@end table
+
+The direction can assume the following values:
@table @samp
-@item 0
+@item cclock_flip
Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
@example
L.R L.l
l.r R.r
@end example
-@item 1
+@item clock
Rotate by 90 degrees clockwise, that is:
@example
L.R l.L
l.r r.R
@end example
-@item 2
+@item cclock
Rotate by 90 degrees counterclockwise, that is:
@example
L.R R.r
l.r L.l
@end example
-@item 3
+@item clock_flip
Rotate by 90 degrees clockwise and vertically flip, that is:
@example
L.R r.R
@end example
@end table
+@section trim
+Trim the input so that the output contains one continuous subpart of the input.
+
+This filter accepts the following options:
+@table @option
+@item start
+Timestamp (in seconds) of the start of the kept section. I.e. the frame with the
+timestamp @var{start} will be the first frame in the output.
+
+@item end
+Timestamp (in seconds) of the first frame that will be dropped. I.e. the frame
+immediately preceding the one with the timestamp @var{end} will be the last
+frame in the output.
+
+@item start_pts
+Same as @var{start}, except this option sets the start timestamp in timebase
+units instead of seconds.
+
+@item end_pts
+Same as @var{end}, except this option sets the end timestamp in timebase units
+instead of seconds.
+
+@item duration
+Maximum duration of the output in seconds.
+
+@item start_frame
+Number of the first frame that should be passed to output.
+
+@item end_frame
+Number of the first frame that should be dropped.
+@end table
+
+Note that the first two sets of the start/end options and the @option{duration}
+option look at the frame timestamp, while the _frame variants simply count the
+frames that pass through the filter. Also note that this filter does not modify
+the timestamps. If you wish that the output timestamps start at zero, insert a
+setpts filter after the trim filter.
+
+If multiple start or end options are set, this filter tries to be greedy and
+keep all the frames that match at least one of the specified constraints. To keep
+only the part that matches all the constraints at once, chain multiple trim
+filters.
+
+The defaults are such that all the input is kept. So it is possible to set e.g.
+just the end values to keep everything before the specified time.
+
+Examples:
+@itemize
+@item
+drop everything except the second minute of input
+@example
+avconv -i INPUT -vf trim=60:120
+@end example
+
+@item
+keep only the first second
+@example
+avconv -i INPUT -vf trim=duration=1
+@end example
+
+@end itemize
@section unsharp
Sharpen or blur the input video.
It accepts the following parameters:
-@var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
-
-Negative values for the amount will blur the input video, while positive
-values will sharpen. All parameters are optional and default to the
-equivalent of the string '5:5:1.0:5:5:0.0'.
@table @option
Set the chroma matrix vertical size. It can be an integer between 3
and 13, default value is 5.
-@item luma_amount
+@item chroma_amount
Set the chroma effect strength. It can be a float number between -2.0
and 5.0, default value is 0.0.
@end table
+Negative values for the amount will blur the input video, while positive
+values will sharpen. All parameters are optional and default to the
+equivalent of the string '5:5:1.0:5:5:0.0'.
+
@example
# Strong luma sharpen effect parameters
-unsharp=7:7:2.5
+unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
# Strong blur of both luma and chroma parameters
unsharp=7:7:-2:7:7:-2
Deinterlace the input video ("yadif" means "yet another deinterlacing
filter").
-It accepts the optional parameters: @var{mode}:@var{parity}:@var{auto}.
+This filter accepts the following options:
-@var{mode} specifies the interlacing mode to adopt, accepts one of the
-following values:
+@table @option
+
+@item mode
+The interlacing mode to adopt, accepts one of the following values:
@table @option
@item 0
Default value is 0.
-@var{parity} specifies the picture field parity assumed for the input
-interlaced video, accepts one of the following values:
+@item parity
+The picture field parity assumed for the input interlaced video, accepts one of
+the following values:
@table @option
@item 0
If interlacing is unknown or decoder does not export this information,
top field first will be assumed.
-@var{auto} specifies if deinterlacer should trust the interlaced flag
-and only deinterlace frames marked as interlaced
+@item auto
+Whether deinterlacer should trust the interlaced flag and only deinterlace
+frames marked as interlaced
@table @option
@item 0
Default value is 0.
+@end table
+
@c man end VIDEO FILTERS
@chapter Video Sources
Provide an uniformly colored input.
It accepts the following parameters:
-@var{color}:@var{frame_size}:@var{frame_rate}
-
-Follows the description of the accepted parameters.
@table @option
insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
alpha specifier. The default value is "black".
-@item frame_size
+@item size
Specify the size of the sourced video, it may be a string of the form
@var{width}x@var{height}, or the name of a size abbreviation. The
default value is "320x240".
-@item frame_rate
+@item framerate
Specify the frame rate of the sourced video, as the number of frames
generated per second. It has to be a string in the format
@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
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),
-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
the name of a container or an input device. If not specified the
To enable compilation of this filter you need to install the frei0r
header and configure Libav with --enable-frei0r.
-The source supports the syntax:
-@example
-@var{size}:@var{rate}:@var{src_name}[@{=|:@}@var{param1}:@var{param2}:...:@var{paramN}]
-@end example
+This source accepts the following options:
-@var{size} is the size of the video to generate, may be a string of the
-form @var{width}x@var{height} or a frame size abbreviation.
-@var{rate} is the rate of the video to generate, may be a string of
-the form @var{num}/@var{den} or a frame rate abbreviation.
-@var{src_name} is the name to the frei0r source to load. For more
-information regarding frei0r and how to set the parameters read the
-section @ref{frei0r} in the description of the video filters.
+@table @option
+
+@item size
+The size of the video to generate, may be a string of the form
+@var{width}x@var{height} or a frame size abbreviation.
+
+@item framerate
+Framerate of the generated video, may be a string of the form
+@var{num}/@var{den} or a frame rate abbreviation.
+
+@item filter_name
+The name to the frei0r source to load. For more information regarding frei0r and
+how to set the parameters read the section @ref{frei0r} in the description of
+the video filters.
+
+@item filter_params
+A '|'-separated list of parameters to pass to the frei0r source.
+
+@end table
Some examples follow:
@example
# generate a frei0r partik0l source with size 200x200 and framerate 10
# which is overlayed on the overlay filter main input
-frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
+frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
@end example
@section rgbtestsrc, testsrc
color pattern, a scrolling gradient and a timestamp. This is mainly
intended for testing purposes.
-Both 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
projects / ffmpeg / blobdiff