+@chapter Filtering Introduction
+@c man begin FILTERING INTRODUCTION
+
+Filtering in FFmpeg is enabled through the libavfilter library.
+
+Libavfilter is the filtering API of FFmpeg. It is the substitute of
+the now deprecated 'vhooks' and started as a Google Summer of Code
+project.
+
+Audio filtering integration into the main FFmpeg repository is a work in
+progress, so audio API and ABI should not be considered stable yet.
+
+In libavfilter, it is possible for filters to have multiple inputs and
+multiple outputs.
+To illustrate the sorts of things that are possible, we can
+use a complex filter graph. For example, the following one:
+
+@example
+input --> split --> fifo -----------------------> overlay --> output
+ | ^
+ | |
+ +------> fifo --> crop --> vflip --------+
+@end example
+
+splits the stream in two streams, 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:
+
+@example
+ffmpeg -i input -vf "[in] split [T1], fifo, [T2] overlay=0:H/2 [out]; [T1] fifo, crop=iw:ih/2:0:ih/2, vflip [T2]" output
+@end example
+
+The result will be that in output the top half of the video is mirrored
+onto the bottom half.
+
+Filters are loaded using the @var{-vf} or @var{-af} option passed to
+@command{ffmpeg} or to @command{ffplay}. Filters in the same linear
+chain are separated by commas. In our example, @var{split, fifo,
+overlay} are in one linear chain, and @var{fifo, crop, vflip} are in
+another. The points where the linear chains join are labeled by names
+enclosed in square brackets. In our example, that is @var{[T1]} and
+@var{[T2]}. The special labels @var{[in]} and @var{[out]} are the points
+where video is input and output.
+
+Some filters take in input a list of parameters: they are specified
+after the filter name and an equal sign, and are separated each other
+by a semicolon.
+
+There exist so-called @var{source filters} that do not have an
+audio/video input, and @var{sink filters} that will not have audio/video
+output.
+
+@c man end FILTERING INTRODUCTION
+
+@chapter graph2dot
+@c man begin GRAPH2DOT
+
+The @file{graph2dot} program included in the FFmpeg @file{tools}
+directory can be used to parse a filter graph description and issue a
+corresponding textual representation in the dot language.
+
+Invoke the command:
+@example
+graph2dot -h
+@end example
+
+to see how to use @file{graph2dot}.
+
+You can then pass the dot description to the @file{dot} program (from
+the graphviz suite of programs) and obtain a graphical representation
+of the filter graph.
+
+For example the sequence of commands:
+@example
+echo @var{GRAPH_DESCRIPTION} | \
+tools/graph2dot -o graph.tmp && \
+dot -Tpng graph.tmp -o graph.png && \
+display graph.png
+@end example
+
+can be used to create and display an image representing the graph
+described by the @var{GRAPH_DESCRIPTION} string.
+
+@c man end GRAPH2DOT
+
@chapter Filtergraph description
@c man begin FILTERGRAPH DESCRIPTION
Convert the input audio to one of the specified formats. The framework will
negotiate the most appropriate format to minimize conversions.
-The filter accepts three lists of formats, separated by ":", in the form:
-"@var{sample_formats}:@var{channel_layouts}:@var{packing_formats}".
+The filter accepts the following named parameters:
+@table @option
-Elements in each list are separated by "," which has to be escaped in the
-filtergraph specification.
+@item sample_fmts
+A comma-separated list of requested sample formats.
-The special parameter "all", in place of a list of elements, signifies all
-supported formats.
+@item sample_rates
+A comma-separated list of requested sample rates.
-Some examples follow:
-@example
-aformat=u8\\,s16:mono:packed
+@item channel_layouts
+A comma-separated list of requested channel layouts.
+
+@end table
+
+If a parameter is omitted, all values are allowed.
-aformat=s16:mono\\,stereo:all
+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
@end example
@section amerge
-Merge two audio streams into a single multi-channel stream.
+Merge two or more audio streams into a single multi-channel stream.
-This filter does not need any argument.
+The filter accepts the following named options:
+
+@table @option
+
+@item inputs
+Set the number of inputs. Default is 2.
+
+@end table
If the channel layouts of the inputs are disjoint, and therefore compatible,
the channel layout of the output will be set accordingly and the channels
in the default order: a1, a2, b1, b2, and the channel layout will be
arbitrarily set to 4.0, which may or may not be the expected value.
-Both inputs must have the same sample rate, format and packing.
+All inputs must have the same sample rate, and format.
If inputs do not have the same duration, the output will stop with the
shortest.
amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
@end example
-If you need to do multiple merges (for instance multiple mono audio streams in
-a single video media), you can do:
+Example: multiple merges:
@example
ffmpeg -f lavfi -i "
amovie=input.mkv:si=0 [a0];
amovie=input.mkv:si=3 [a3];
amovie=input.mkv:si=4 [a4];
amovie=input.mkv:si=5 [a5];
-[a0][a1] amerge [x0];
-[x0][a2] amerge [x1];
-[x1][a3] amerge [x2];
-[x2][a4] amerge [x3];
-[x3][a5] amerge" -c:a pcm_s16le output.mkv
+[a0][a1][a2][a3][a4][a5] amerge=inputs=6" -c:a pcm_s16le output.mkv
@end example
+@section amix
+
+Mixes multiple audio inputs into a single output.
+
+For example
+@example
+ffmpeg -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.
aresample=44100
@end example
+@section asetnsamples
+
+Set the number of samples per each output audio frame.
+
+The last output packet may contain a different number of samples, as
+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 ":".
+
+@table @option
+
+@item nb_out_samples, n
+Set the number of frames per each output audio frame. The number is
+intended as the number of samples @emph{per each channel}.
+Default value is 1024.
+
+@item pad, p
+If set to 1, the filter will pad the last audio frame with zeroes, so
+that the last frame will contain the same number of samples as the
+previous ones. Default value is 1.
+@end table
+
+For example, to set the number of per-frame samples to 1234 and
+disable padding for the last frame, use:
+@example
+asetnsamples=n=1234:p=0
+@end example
+
@section ashowinfo
Show a line containing various information for each input audio frame.
@item rate
sample rate for the audio frame
-@item planar
-if the packing format is planar, 0 if packed
-
@item checksum
Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame
@section asplit
-Pass on the input audio to two outputs. Both outputs are identical to
-the input audio.
+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
-[in] asplit[out0], showaudio[out1]
+[in] asplit [out0][out1]
@end example
-will create two separate outputs from the same input, one cropped and
-one padded.
+will create two separate outputs from the same input.
+
+To create 3 or more outputs, you need to specify the number of
+outputs, like in:
+@example
+[in] asplit=3 [out0][out1][out2]
+@end example
+
+@example
+ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
+@end example
+will create 5 copies of the input audio.
+
@section astreamsync
[a2] [b2] amerge
@end example
+@section atempo
+
+Adjust audio tempo.
+
+The filter accepts exactly one parameter, the audio tempo. If not
+specified then the filter will assume nominal 1.0 tempo. Tempo must
+be in the [0.5, 2.0] range.
+
+For example, to slow down audio to 80% tempo:
+@example
+atempo=0.8
+@end example
+
+For example, to speed up audio to 125% tempo:
+@example
+atempo=1.25
+@end example
+
@section earwax
Make audio easier to listen to on headphones.
@end example
@end itemize
+@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.
+
+@item min_delta
+Minimum difference between timestamps and audio data (in seconds) to trigger
+adding/dropping samples.
+
+@item max_comp
+Maximum compensation in samples per second.
+
+@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
+ffmpeg -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
+ffmpeg -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
+ffmpeg -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
+ffmpeg -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
+ffmpeg -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
+ffmpeg -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.
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}:@var{packing}
+@var{sample_rate}:@var{sample_fmt}:@var{channel_layout}
@table @option
@file{libavutil/audioconvert.c} or its corresponding integer representation
from the AV_CH_LAYOUT_* macros in @file{libavutil/audioconvert.h}
-@item packing
-Either "packed" or "planar", or their integer representation: 0 or 1
-respectively.
-
@end table
For example:
@example
-abuffer=44100:s16:stereo:planar
+abuffer=44100:s16p:stereo
@end example
will instruct the source to accept planar 16bit signed stereo at 44100Hz.
-Since the sample format with name "s16" corresponds to the number
-1 and the "stereo" channel layout corresponds to the value 0x3, this is
+Since the sample format with name "s16p" corresponds to the number
+6 and the "stereo" channel layout corresponds to the value 0x3, this is
equivalent to:
@example
-abuffer=44100:1:0x3:1
+abuffer=44100:6:0x3
@end example
@section aevalsrc
It accepts the syntax: @var{exprs}[::@var{options}].
@var{exprs} is a list of expressions separated by ":", one for each
-separate channel. The output channel layout depends on the number of
-provided expressions, up to 8 channels are supported.
+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 ":".
@table @option
+@item channel_layout, c
+Set the channel layout. The number of channels in the specified layout
+must be equal to the number of specified expressions.
+
@item duration, d
Set the minimum duration of the sourced audio. See the function
@code{av_parse_time()} for the accepted format.
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"
+@end example
+
@item
Generate white noise:
@example
anullsrc=r=48000:cl=mono
@end example
+@section abuffer
+Buffer audio frames, and make them available to the filter chain.
+
+This source is not intended to be part of user-supplied graph descriptions but
+for insertion by calling programs through the interface defined in
+@file{libavfilter/buffersrc.h}.
+
+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
+Audio sample rate.
+
+@item sample_fmt
+Name of the sample format, as returned by @code{av_get_sample_fmt_name()}.
+
+@item channel_layout
+Channel layout of the audio data, in the form that can be accepted by
+@code{av_get_channel_layout()}.
+@end table
+
+All the parameters need to be explicitly defined.
+
@c man end AUDIO SOURCES
@chapter Audio Sinks
mainly useful as a template and to be employed in analysis / debugging
tools.
+@section abuffersink
+This sink is intended for programmatic use. Frames that arrive on this sink can
+be retrieved by the calling program using the interface defined in
+@file{libavfilter/buffersink.h}.
+
+This filter accepts no parameters.
+
@c man end AUDIO SINKS
@chapter Video Filters
format=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
effect parameter is not specified the default value is set.
Some examples follow:
+
+@itemize
+@item
+Apply the distort0r effect, set the first two double parameters:
@example
-# apply the distort0r effect, set the first two double parameters
frei0r=distort0r:0.5:0.01
+@end example
-# apply the colordistance effect, takes a color as first parameter
+@item
+Apply the colordistance effect, takes a color as first parameter:
+@example
frei0r=colordistance:0.2/0.3/0.4
frei0r=colordistance:violet
frei0r=colordistance:0x112233
+@end example
-# apply the perspective effect, specify the top left and top right
-# image positions
+@item
+Apply the perspective effect, specify the top left and top right image
+positions:
+@example
frei0r=perspective:0.2/0.2:0.8/0.2
@end example
+@end itemize
For more information see:
-@url{http://piksel.org/frei0r}
+@url{http://frei0r.dyne.org}
@section gradfun
# 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]
+
+# play an original video and a filtered version (here with the deshake filter)
+# side by side
+ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
+
+# the previous example is the same as:
+ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
@end example
You can chain together more overlays but the efficiency of such
@item pos
the position in the file of the filtered frame, -1 if the information
is not available (e.g. for synthetic video)
+
+@item scene
+value between 0 and 1 to indicate a new scene; a low value reflects a low
+probability for the current frame to introduce a new scene, while a higher
+value means the current frame is more likely to be one (see the example below)
+
@end table
The default value of the select expression is "1".
select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
@end example
+Complete example to create a mosaic of the first scenes:
+
+@example
+ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
+@end example
+
+Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
+choice.
+
@section setdar, setsar
The @code{setdar} filter sets the Display Aspect Ratio for the filter
setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
@end example
-@section settb
+@section settb, asettb
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.
The expression can contain the constants "AVTB" (the
-default timebase), and "intb" (the input timebase).
+default timebase), "intb" (the input timebase) and "sr" (the sample rate,
+audio only).
The default value for the input is "intb".
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}:@var{scale_params}
-
-All the parameters but @var{scale_params} need to be explicitly
-defined.
-
-Follows the list of the accepted parameters.
+It accepts a list of options in the form of @var{key}=@var{value} pairs
+separated by ":". A descroption of the accepted options follows.
@table @option
-@item width, height
-Specify the width and height of the buffered video frames.
+@item video_size
+Specify the size (width and height) of the buffered video frames.
-@item pix_fmt_string
+@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
name.
-@item timebase_num, timebase_den
-Specify numerator and denomitor of the timebase assumed by the
-timestamps of the buffered frames.
+@item time_base
+Specify the timebase assumed by the timestamps of the buffered frames.
+
+@item time_base
+Specify the frame rate expected for the video stream.
-@item sample_aspect_ratio.num, sample_aspect_ratio.den
-Specify numerator and denominator of the sample aspect ratio assumed
-by the video frames.
+@item pixel_aspect
+Specify the sample aspect ratio assumed by the video frames.
-@item scale_params
+@item sws_param
Specify the optional parameters to be used for the scale filter which
is automatically inserted when an input change is detected in the
input size or format.
For example:
@example
-buffer=320:240:yuv410p:1:24:1:1
+buffer=size=320x240:pix_fmt=yuv410p:time_base=1/24:pixel_aspect=1/1
@end example
will instruct the source to accept video frames with size 320x240 and
(check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),
this example corresponds to:
@example
-buffer=320:240:6:1:24:1:1
+buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
@end example
+Alternatively, the options can be specified as a flat string, but this
+syntax is deprecated:
+
+@var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den}[:@var{sws_param}]
+
@section cellauto
Create a pattern generated by an elementary cellular automaton.
Provide an uniformly colored input.
-It accepts the following parameters:
-@var{color}:@var{frame_size}:@var{frame_rate}
+This source accepts list of options in the form of
+@var{key}=@var{value} pairs separated by ":".
+
+Alternatively, it accepts a string in the form
+@var{color}:@var{size}:@var{rate}, but this syntax is
+deprecated.
Follows the description of the accepted parameters.
@table @option
-@item color
+@item color, c
Specify the color of the source. It can be the name of a color (case
insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
alpha specifier. The default value is "black".
-@item frame_size
+@item size, s
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 rate, r
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
to the pad with identifier "in".
@example
-"color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
+"color=c=red@@0.2:s=qcif:r=10 [color]; [in][color] overlay [out]"
@end example
@section movie
information regarding frei0r and how to set the parameters read the
section @ref{frei0r} in the description of the video filters.
-Some examples follow:
+For example, to generate a frei0r partik0l source with size 200x200
+and frame rate 10 which is overlayed on the overlay filter main input:
@example
-# generate a frei0r partik0l source with size 200x200 and frame rate 10
-# which is overlayed on the overlay filter main input
frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
@end example
tools.
@c man end VIDEO SINKS
+
+@chapter Transmedia Filters
+@c man begin TRANSMEDIA FILTERS
+
+Below is a description of the currently available transmedia filters.
+
+@section showwaves
+
+Convert input audio to a video output, representing the samples waves.
+
+The filter accepts the following named parameters:
+@table @option
+
+@item n
+Set the number of samples which are printed on the same column. A
+larger value will decrease the frame rate. Must be a positive
+integer. This option can be set only if the value for @var{rate}
+is not explicitly specified.
+
+@item rate, r
+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
+
+Some examples follow.
+@itemize
+@item
+Output the input file audio and the corresponding video representation
+at the same time:
+@example
+amovie=a.mp3,asplit[out0],showwaves[out1]
+@end example
+
+@item
+Create a synthetic signal and show it with showwaves, forcing a
+framerate of 30 frames per second:
+@example
+aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
+@end example
+@end itemize
+
+@c man end TRANSMEDIA FILTERS
projects / ffmpeg / blobdiff