diff options
Diffstat (limited to 'doc/filters.texi')
-rw-r--r-- | doc/filters.texi | 9665 |
1 files changed, 8764 insertions, 901 deletions
diff --git a/doc/filters.texi b/doc/filters.texi index 28e3292..c5caa77 100644 --- a/doc/filters.texi +++ b/doc/filters.texi @@ -1,3 +1,100 @@ +@chapter Filtering Introduction +@c man begin FILTERING INTRODUCTION + +Filtering in FFmpeg is enabled through the libavfilter library. + +In libavfilter, a filter can have multiple inputs and multiple +outputs. +To illustrate the sorts of things that are possible, we consider the +following filtergraph. + +@example + [main] +input --> split ---------------------> overlay --> output + | ^ + |[tmp] [flip]| + +-----> crop --> vflip -------+ +@end example + +This filtergraph splits the input stream in two streams, then sends one +stream through the crop filter and the vflip filter, before merging it +back with the other stream by overlaying it on top. You can use the +following command to achieve this: + +@example +ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT +@end example + +The result will be that the top half of the video is mirrored +onto the bottom half of the output video. + +Filters in the same linear chain are separated by commas, and distinct +linear chains of filters are separated by semicolons. In our example, +@var{crop,vflip} are in one linear chain, @var{split} and +@var{overlay} are separately in another. The points where the linear +chains join are labelled by names enclosed in square brackets. In the +example, the split filter generates two outputs that are associated to +the labels @var{[main]} and @var{[tmp]}. + +The stream sent to the second output of @var{split}, labelled as +@var{[tmp]}, is processed through the @var{crop} filter, which crops +away the lower half part of the video, and then vertically flipped. The +@var{overlay} filter takes in input the first unchanged output of the +split filter (which was labelled as @var{[main]}), and overlay on its +lower half the output generated by the @var{crop,vflip} filterchain. + +Some filters take in input a list of parameters: they are specified +after the filter name and an equal sign, and are separated from each other +by a colon. + +There exist so-called @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 filtergraph 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 filtergraph. + +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. Note that this string must be +a complete self-contained graph, with its inputs and outputs explicitly defined. +For example if your command line is of the form: +@example +ffmpeg -i infile -vf scale=640:360 outfile +@end example +your @var{GRAPH_DESCRIPTION} string will need to be of the form: +@example +nullsrc,scale=640:360,nullsink +@end example +you may also need to set the @var{nullsrc} parameters and add a @var{format} +filter in order to simulate a specific input file. + +@c man end GRAPH2DOT + @chapter Filtergraph description @c man begin FILTERGRAPH DESCRIPTION @@ -19,7 +116,7 @@ output pads is called a "sink". A filtergraph has a textual representation, which is recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex} -options in @command{avconv} and @option{-vf} in @command{avplay}, and by the +options in @command{ffmpeg} and @option{-vf} in @command{ffplay}, and by the @code{avfilter_graph_parse()}/@code{avfilter_graph_parse2()} functions defined in @file{libavfilter/avfilter.h}. @@ -55,6 +152,12 @@ declares three options in this order -- @option{type}, @option{start_frame} and @var{in} is assigned to the option @option{type}, @var{0} to @option{start_frame} and @var{30} to @option{nb_frames}. +@item +A ':'-separated list of mixed direct @var{value} and long @var{key=value} +pairs. The direct @var{value} must precede the @var{key=value} pairs, and +follow the same constraints order of the previous point. The following +@var{key=value} pairs can be set in any preferred order. + @end itemize If the option value itself is a list of items (e.g. the @code{format} filter @@ -69,7 +172,7 @@ terminated when the next special character (belonging to the set The name and arguments of the filter are optionally preceded and followed by a list of link labels. -A link label allows to name a link and associate it to a filter output +A link label allows one to name a link and associate it to a filter output or input pad. The preceding labels @var{in_link_1} ... @var{in_link_N}, are associated to the filter input pads, the following labels @var{out_link_1} ... @var{out_link_M}, are @@ -112,21 +215,378 @@ Here is a BNF description of the filtergraph syntax: @var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}] @end example +@section Notes on filtergraph escaping + +Filtergraph description composition entails several levels of +escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping" +section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more +information about the employed escaping procedure. + +A first level escaping affects the content of each filter option +value, which may contain the special character @code{:} used to +separate values, or one of the escaping characters @code{\'}. + +A second level escaping affects the whole filter description, which +may contain the escaping characters @code{\'} or the special +characters @code{[],;} used by the filtergraph description. + +Finally, when you specify a filtergraph on a shell commandline, you +need to perform a third level escaping for the shell special +characters contained within it. + +For example, consider the following string to be embedded in +the @ref{drawtext} filter description @option{text} value: +@example +this is a 'string': may contain one, or more, special characters +@end example + +This string contains the @code{'} special escaping character, and the +@code{:} special character, so it needs to be escaped in this way: +@example +text=this is a \'string\'\: may contain one, or more, special characters +@end example + +A second level of escaping is required when embedding the filter +description in a filtergraph description, in order to escape all the +filtergraph special characters. Thus the example above becomes: +@example +drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters +@end example +(note that in addition to the @code{\'} escaping special characters, +also @code{,} needs to be escaped). + +Finally an additional level of escaping is needed when writing the +filtergraph description in a shell command, which depends on the +escaping rules of the adopted shell. For example, assuming that +@code{\} is special and needs to be escaped with another @code{\}, the +previous string will finally result in: +@example +-vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters" +@end example + +@chapter Timeline editing + +Some filters support a generic @option{enable} option. For the filters +supporting timeline editing, this option can be set to an expression which is +evaluated before sending a frame to the filter. If the evaluation is non-zero, +the filter will be enabled, otherwise the frame will be sent unchanged to the +next filter in the filtergraph. + +The expression accepts the following values: +@table @samp +@item t +timestamp expressed in seconds, NAN if the input timestamp is unknown + +@item n +sequential number of the input frame, starting from 0 + +@item pos +the position in the file of the input frame, NAN if unknown +@end table + +Additionally, these filters support an @option{enable} command that can be used +to re-define the expression. + +Like any other filtering option, the @option{enable} option follows the same +rules. + +For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3 +minutes, and a @ref{curves} filter starting at 3 seconds: +@example +smartblur = enable='between(t,10,3*60)', +curves = enable='gte(t,3)' : preset=cross_process +@end example + @c man end FILTERGRAPH DESCRIPTION @chapter Audio Filters @c man begin AUDIO FILTERS -When you configure your Libav build, you can disable any of the -existing filters using --disable-filters. +When you configure your FFmpeg build, you can disable any of the +existing filters using @code{--disable-filters}. The configure output will show the audio filters included in your build. Below is a description of the currently available audio filters. +@section aconvert + +Convert the input audio format to the specified formats. + +@emph{This filter is deprecated. Use @ref{aformat} instead.} + +The filter accepts a string of the form: +"@var{sample_format}:@var{channel_layout}". + +@var{sample_format} specifies the sample format, and can be a string or the +corresponding numeric value defined in @file{libavutil/samplefmt.h}. Use 'p' +suffix for a planar sample format. + +@var{channel_layout} specifies the channel layout, and can be a string +or the corresponding number value defined in @file{libavutil/channel_layout.h}. + +The special parameter "auto", signifies that the filter will +automatically select the output format depending on the output filter. + +@subsection Examples + +@itemize +@item +Convert input to float, planar, stereo: +@example +aconvert=fltp:stereo +@end example + +@item +Convert input to unsigned 8-bit, automatically select out channel layout: +@example +aconvert=u8:auto +@end example +@end itemize + +@section adelay + +Delay one or more audio channels. + +Samples in delayed channel are filled with silence. + +The filter accepts the following option: + +@table @option +@item delays +Set list of delays in milliseconds for each channel separated by '|'. +At least one delay greater than 0 should be provided. +Unused delays will be silently ignored. If number of given delays is +smaller than number of channels all remaining channels will not be delayed. +@end table + +@subsection Examples + +@itemize +@item +Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave +the second channel (and any other channels that may be present) unchanged. +@example +adelay=1500|0|500 +@end example +@end itemize + +@section aecho + +Apply echoing to the input audio. + +Echoes are reflected sound and can occur naturally amongst mountains +(and sometimes large buildings) when talking or shouting; digital echo +effects emulate this behaviour and are often used to help fill out the +sound of a single instrument or vocal. The time difference between the +original signal and the reflection is the @code{delay}, and the +loudness of the reflected signal is the @code{decay}. +Multiple echoes can have different delays and decays. + +A description of the accepted parameters follows. + +@table @option +@item in_gain +Set input gain of reflected signal. Default is @code{0.6}. + +@item out_gain +Set output gain of reflected signal. Default is @code{0.3}. + +@item delays +Set list of time intervals in milliseconds between original signal and reflections +separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}. +Default is @code{1000}. + +@item decays +Set list of loudnesses of reflected signals separated by '|'. +Allowed range for each @code{decay} is @code{(0 - 1.0]}. +Default is @code{0.5}. +@end table + +@subsection Examples + +@itemize +@item +Make it sound as if there are twice as many instruments as are actually playing: +@example +aecho=0.8:0.88:60:0.4 +@end example + +@item +If delay is very short, then it sound like a (metallic) robot playing music: +@example +aecho=0.8:0.88:6:0.4 +@end example + +@item +A longer delay will sound like an open air concert in the mountains: +@example +aecho=0.8:0.9:1000:0.3 +@end example + +@item +Same as above but with one more mountain: +@example +aecho=0.8:0.9:1000|1800:0.3|0.25 +@end example +@end itemize + +@section aeval + +Modify an audio signal according to the specified expressions. + +This filter accepts one or more expressions (one for each channel), +which are evaluated and used to modify a corresponding audio signal. + +It accepts the following parameters: + +@table @option +@item exprs +Set the '|'-separated expressions list for each separate channel. If +the number of input channels is greater than the number of +expressions, the last specified expression is used for the remaining +output channels. + +@item channel_layout, c +Set output channel layout. If not specified, the channel layout is +specified by the number of expressions. If set to @samp{same}, it will +use by default the same input channel layout. +@end table + +Each expression in @var{exprs} can contain the following constants and functions: + +@table @option +@item ch +channel number of the current expression + +@item n +number of the evaluated sample, starting from 0 + +@item s +sample rate + +@item t +time of the evaluated sample expressed in seconds + +@item nb_in_channels +@item nb_out_channels +input and output number of channels + +@item val(CH) +the value of input channel with number @var{CH} +@end table + +Note: this filter is slow. For faster processing you should use a +dedicated filter. + +@subsection Examples + +@itemize +@item +Half volume: +@example +aeval=val(ch)/2:c=same +@end example + +@item +Invert phase of the second channel: +@example +eval=val(0)|-val(1) +@end example +@end itemize + +@section afade + +Apply fade-in/out effect to input audio. + +A description of the accepted parameters follows. + +@table @option +@item type, t +Specify the effect type, can be either @code{in} for fade-in, or +@code{out} for a fade-out effect. Default is @code{in}. + +@item start_sample, ss +Specify the number of the start sample for starting to apply the fade +effect. Default is 0. + +@item nb_samples, ns +Specify the number of samples for which the fade effect has to last. At +the end of the fade-in effect the output audio will have the same +volume as the input audio, at the end of the fade-out transition +the output audio will be silence. Default is 44100. + +@item start_time, st +Specify time for starting to apply the fade effect. Default is 0. +The accepted syntax is: +@example +[-]HH[:MM[:SS[.m...]]] +[-]S+[.m...] +@end example +See also the function @code{av_parse_time()}. +If set this option is used instead of @var{start_sample} one. + +@item duration, d +Specify the duration for which the fade effect has to last. Default is 0. +The accepted syntax is: +@example +[-]HH[:MM[:SS[.m...]]] +[-]S+[.m...] +@end example +See also the function @code{av_parse_time()}. +At the end of the fade-in effect the output audio will have the same +volume as the input audio, at the end of the fade-out transition +the output audio will be silence. +If set this option is used instead of @var{nb_samples} one. + +@item curve +Set curve for fade transition. + +It accepts the following values: +@table @option +@item tri +select triangular, linear slope (default) +@item qsin +select quarter of sine wave +@item hsin +select half of sine wave +@item esin +select exponential sine wave +@item log +select logarithmic +@item par +select inverted parabola +@item qua +select quadratic +@item cub +select cubic +@item squ +select square root +@item cbr +select cubic root +@end table +@end table + +@subsection Examples + +@itemize +@item +Fade in first 15 seconds of audio: +@example +afade=t=in:ss=0:d=15 +@end example + +@item +Fade out last 25 seconds of a 900 seconds audio: +@example +afade=t=out:st=875:d=25 +@end example +@end itemize + +@anchor{aformat} @section aformat -Convert the input audio to one of the specified formats. The framework will +Set output format constraints for the input audio. The framework will negotiate the most appropriate format to minimize conversions. It accepts the following parameters: @@ -141,6 +601,8 @@ A '|'-separated list of requested sample rates. @item channel_layouts A '|'-separated list of requested channel layouts. +See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} +for the required syntax. @end table If a parameter is omitted, all values are allowed. @@ -150,13 +612,99 @@ Force the output to either unsigned 8-bit or signed 16-bit stereo aformat=sample_fmts=u8|s16:channel_layouts=stereo @end example +@section allpass + +Apply a two-pole all-pass filter with central frequency (in Hz) +@var{frequency}, and filter-width @var{width}. +An all-pass filter changes the audio's frequency to phase relationship +without changing its frequency to amplitude relationship. + +The filter accepts the following options: + +@table @option +@item frequency, f +Set frequency in Hz. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Specify the band-width of a filter in width_type units. +@end table + +@section amerge + +Merge two or more audio streams into a single multi-channel stream. + +The filter accepts the following 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 +will be reordered as necessary. If the channel layouts of the inputs are not +disjoint, the output will have all the channels of the first input then all +the channels of the second input, in that order, and the channel layout of +the output will be the default value corresponding to the total number of +channels. + +For example, if the first input is in 2.1 (FL+FR+LF) and the second input +is FC+BL+BR, then the output will be in 5.1, with the channels in the +following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the +first input, b1 is the first channel of the second input). + +On the other hand, if both input are in stereo, the output channels will be +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. + +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. + +@subsection Examples + +@itemize +@item +Merge two mono files into a stereo stream: +@example +amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge +@end example + +@item +Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}: +@example +ffmpeg -i input.mkv -filter_complex "[0:1][0:2][0:3][0:4][0:5][0:6] amerge=inputs=6" -c:a pcm_s16le output.mkv +@end example +@end itemize + @section amix Mixes multiple audio inputs into a single output. +Note that this filter only supports float samples (the @var{amerge} +and @var{pan} audio filters support many formats). If the @var{amix} +input has integer samples then @ref{aresample} will be automatically +inserted to perform the conversion to float samples. + For example @example -avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT +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. @@ -192,110 +740,119 @@ stream ends. The default value is 2 seconds. Pass the audio source unchanged to the output. -@section asetpts +@section apad -Change the PTS (presentation timestamp) of the input audio frames. +Pad the end of a audio stream with silence, this can be used together with +-shortest to extend audio streams to the same length as the video stream. -It accepts the following parameters: +@section aphaser +Add a phasing effect to the input audio. -@table @option +A phaser filter creates series of peaks and troughs in the frequency spectrum. +The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect. -@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: +A description of the accepted parameters follows. @table @option -@item PTS -the presentation timestamp in input +@item in_gain +Set input gain. Default is 0.4. -@item E, PI, PHI -These are approximated values for the mathematical constants e -(Euler's number), pi (Greek pi), and phi (the golden ratio). +@item out_gain +Set output gain. Default is 0.74 -@item N -The number of audio samples passed through the filter so far, starting at 0. +@item delay +Set delay in milliseconds. Default is 3.0. -@item S -The number of audio samples in the current frame. +@item decay +Set decay. Default is 0.4. -@item SR -The audio sample rate. +@item speed +Set modulation speed in Hz. Default is 0.5. -@item STARTPTS -The PTS of the first frame. +@item type +Set modulation type. Default is triangular. -@item PREV_INPTS -The previous input PTS. +It accepts the following values: +@table @samp +@item triangular, t +@item sinusoidal, s +@end table +@end table -@item PREV_OUTPTS -The previous output PTS. +@anchor{aresample} +@section aresample -@item RTCTIME -The wallclock (RTC) time in microseconds. +Resample the input audio to the specified parameters, using the +libswresample library. If none are specified then the filter will +automatically convert between its input and output. -@item RTCSTART -The wallclock (RTC) time at the start of the movie in microseconds. +This filter is also able to stretch/squeeze the audio data to make it match +the timestamps or to inject silence / cut out audio to make it match the +timestamps, do a combination of both or do neither. -@end table +The filter accepts the syntax +[@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate} +expresses a sample rate and @var{resampler_options} is a list of +@var{key}=@var{value} pairs, separated by ":". See the +ffmpeg-resampler manual for the complete list of supported options. -Some examples: +@subsection Examples +@itemize +@item +Resample the input audio to 44100Hz: @example -# Start counting PTS from zero -asetpts=expr=PTS-STARTPTS - -# Generate timestamps by counting samples -asetpts=expr=N/SR/TB +aresample=44100 +@end example -# Generate timestamps from a "live source" and rebase onto the current timebase -asetpts='(RTCTIME - RTCSTART) / (TB * 1000000)" +@item +Stretch/squeeze samples to the given timestamps, with a maximum of 1000 +samples per second compensation: +@example +aresample=async=1000 @end example +@end itemize -@section asettb +@section asetnsamples -Set the timebase to use for the output frames timestamps. -It is mainly useful for testing timebase configuration. +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. -This filter accepts the following parameters: +The filter accepts the following options: @table @option -@item expr -The expression which is evaluated into the output timebase. +@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 -The expression can contain the constants @var{PI}, @var{E}, @var{PHI}, @var{AVTB} (the -default timebase), @var{intb} (the input timebase), and @var{sr} (the sample rate, -audio only). - -The default value for the input is @var{intb}. - -Some examples: - +For example, to set the number of per-frame samples to 1234 and +disable padding for the last frame, use: @example -# Set the timebase to 1/25: -settb=1/25 - -# Set the timebase to 1/10: -settb=0.1 +asetnsamples=n=1234:p=0 +@end example -# Set the timebase to 1001/1000: -settb=1+0.001 +@section asetrate -# Set the timebase to 2*intb: -settb=2*intb +Set the sample rate without altering the PCM data. +This will result in a change of speed and pitch. -# Set the default timebase value: -settb=AVTB +The filter accepts the following options: -# Set the timebase to twice the sample rate: -asettb=sr*2 -@end example +@table @option +@item sample_rate, r +Set the output sample rate. Default is 44100 Hz. +@end table @section ashowinfo @@ -318,6 +875,10 @@ depends on the filter input pad, and is usually 1/@var{sample_rate}. @item pts_time The presentation timestamp of the input frame in seconds. +@item pos +position of the frame in the input stream, -1 if this information in +unavailable and/or meaningless (for example in case of synthetic audio) + @item fmt The sample format. @@ -338,23 +899,94 @@ audio, the data is treated as if all the planes were concatenated. A list of Adler-32 checksums for each data plane. @end table -@section asplit +@section astats -Split input audio into several identical outputs. +Display time domain statistical information about the audio channels. +Statistics are calculated and displayed for each audio channel and, +where applicable, an overall figure is also given. -It accepts a single parameter, which specifies the number of outputs. If -unspecified, it defaults to 2. +It accepts the following option: +@table @option +@item length +Short window length in seconds, used for peak and trough RMS measurement. +Default is @code{0.05} (50 miliseconds). Allowed range is @code{[0.1 - 10]}. +@end table + +A description of each shown parameter follows: + +@table @option +@item DC offset +Mean amplitude displacement from zero. -For example, +@item Min level +Minimal sample level. + +@item Max level +Maximal sample level. + +@item Peak level dB +@item RMS level dB +Standard peak and RMS level measured in dBFS. + +@item RMS peak dB +@item RMS trough dB +Peak and trough values for RMS level measured over a short window. + +@item Crest factor +Standard ratio of peak to RMS level (note: not in dB). + +@item Flat factor +Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels +(i.e. either @var{Min level} or @var{Max level}). + +@item Peak count +Number of occasions (not the number of samples) that the signal attained either +@var{Min level} or @var{Max level}. +@end table + +@section astreamsync + +Forward two audio streams and control the order the buffers are forwarded. + +The filter accepts the following options: + +@table @option +@item expr, e +Set the expression deciding which stream should be +forwarded next: if the result is negative, the first stream is forwarded; if +the result is positive or zero, the second stream is forwarded. It can use +the following variables: + +@table @var +@item b1 b2 +number of buffers forwarded so far on each stream +@item s1 s2 +number of samples forwarded so far on each stream +@item t1 t2 +current timestamp of each stream +@end table + +The default value is @code{t1-t2}, which means to always forward the stream +that has a smaller timestamp. +@end table + +@subsection Examples + +Stress-test @code{amerge} by randomly sending buffers on the wrong +input, while avoiding too much of a desynchronization: @example -avconv -i INPUT -filter_complex asplit=5 OUTPUT +amovie=file.ogg [a] ; amovie=file.mp3 [b] ; +[a] [b] astreamsync=(2*random(1))-1+tanh(5*(t1-t2)) [a2] [b2] ; +[a2] [b2] amerge @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. +This filter is not built by default, please use @ref{aresample} to do squeezing/stretching. + It accepts the following parameters: @table @option @@ -381,7 +1013,32 @@ with a negative PTS due to encoder delay. @end table +@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. + +@subsection Examples + +@itemize +@item +Slow down audio to 80% tempo: +@example +atempo=0.8 +@end example + +@item +To speed up audio to 125% tempo: +@example +atempo=1.25 +@end example +@end itemize + @section atrim + Trim the input so that the output contains one continuous subpart of the input. It accepts the following parameters: @@ -391,7 +1048,7 @@ Timestamp (in seconds) of the start of the section to keep. 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 +Specify time 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. @@ -413,6 +1070,10 @@ The number of the first sample that should be output. The number of the first sample that should be dropped. @end table +@option{start}, @option{end}, @option{duration} are expressed as time +duration specifications, check the "Time duration" section in the +ffmpeg-utils manual. + 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 @@ -434,17 +1095,122 @@ Examples: @item Drop everything except the second minute of input: @example -avconv -i INPUT -af atrim=60:120 +ffmpeg -i INPUT -af atrim=60:120 @end example @item Keep only the first 1000 samples: @example -avconv -i INPUT -af atrim=end_sample=1000 +ffmpeg -i INPUT -af atrim=end_sample=1000 @end example @end itemize +@section bandpass + +Apply a two-pole Butterworth band-pass filter with central +frequency @var{frequency}, and (3dB-point) band-width width. +The @var{csg} option selects a constant skirt gain (peak gain = Q) +instead of the default: constant 0dB peak gain. +The filter roll off at 6dB per octave (20dB per decade). + +The filter accepts the following options: + +@table @option +@item frequency, f +Set the filter's central frequency. Default is @code{3000}. + +@item csg +Constant skirt gain if set to 1. Defaults to 0. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Specify the band-width of a filter in width_type units. +@end table + +@section bandreject + +Apply a two-pole Butterworth band-reject filter with central +frequency @var{frequency}, and (3dB-point) band-width @var{width}. +The filter roll off at 6dB per octave (20dB per decade). + +The filter accepts the following options: + +@table @option +@item frequency, f +Set the filter's central frequency. Default is @code{3000}. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Specify the band-width of a filter in width_type units. +@end table + +@section bass + +Boost or cut the bass (lower) frequencies of the audio using a two-pole +shelving filter with a response similar to that of a standard +hi-fi's tone-controls. This is also known as shelving equalisation (EQ). + +The filter accepts the following options: + +@table @option +@item gain, g +Give the gain at 0 Hz. Its useful range is about -20 +(for a large cut) to +20 (for a large boost). +Beware of clipping when using a positive gain. + +@item frequency, f +Set the filter's central frequency and so can be used +to extend or reduce the frequency range to be boosted or cut. +The default value is @code{100} Hz. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Determine how steep is the filter's shelf transition. +@end table + +@section biquad + +Apply a biquad IIR filter with the given coefficients. +Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2} +are the numerator and denominator coefficients respectively. + @section bs2b Bauer stereo to binaural transformation, which improves headphone listening of stereo audio records. @@ -475,32 +1241,8 @@ Feed level (in Hz). @end table -@section channelsplit -Split each channel from an input audio stream into a separate output stream. - -It accepts the following parameters: -@table @option -@item channel_layout -The channel layout of the input stream. The 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. - -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. It accepts the following parameters: @@ -523,14 +1265,40 @@ output channels, preserving indices. For example, assuming a 5.1+downmix input MOV file, @example -avconv -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav +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 -avconv -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav +ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav +@end example + +@section channelsplit + +Split each channel from an input audio stream into a separate output stream. + +It accepts the following parameters: +@table @option +@item channel_layout +The channel layout of the input stream. The 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. + +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 compand @@ -553,7 +1321,8 @@ a typical value for decay is 0.8 seconds. @item points A 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 following syntax: @code{x0/y0|x1/y1|x2/y2|....} or +@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 @@ -607,7 +1376,141 @@ compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1 @end example @end itemize +@section earwax + +Make audio easier to listen to on headphones. + +This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio +so that when listened to on headphones the stereo image is moved from +inside your head (standard for headphones) to outside and in front of +the listener (standard for speakers). + +Ported from SoX. + +@section equalizer + +Apply a two-pole peaking equalisation (EQ) filter. With this +filter, the signal-level at and around a selected frequency can +be increased or decreased, whilst (unlike bandpass and bandreject +filters) that at all other frequencies is unchanged. + +In order to produce complex equalisation curves, this filter can +be given several times, each with a different central frequency. + +The filter accepts the following options: + +@table @option +@item frequency, f +Set the filter's central frequency in Hz. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Specify the band-width of a filter in width_type units. + +@item gain, g +Set the required gain or attenuation in dB. +Beware of clipping when using a positive gain. +@end table + +@subsection Examples +@itemize +@item +Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz: +@example +equalizer=f=1000:width_type=h:width=200:g=-10 +@end example + +@item +Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2: +@example +equalizer=f=1000:width_type=q:width=1:g=2,equalizer=f=100:width_type=q:width=2:g=-5 +@end example +@end itemize + +@section flanger +Apply a flanging effect to the audio. + +The filter accepts the following options: + +@table @option +@item delay +Set base delay in milliseconds. Range from 0 to 30. Default value is 0. + +@item depth +Set added swep delay in milliseconds. Range from 0 to 10. Default value is 2. + +@item regen +Set percentage regeneneration (delayed signal feedback). Range from -95 to 95. +Default value is 0. + +@item width +Set percentage of delayed signal mixed with original. Range from 0 to 100. +Default valu is 71. + +@item speed +Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5. + +@item shape +Set swept wave shape, can be @var{triangular} or @var{sinusoidal}. +Default value is @var{sinusoidal}. + +@item phase +Set swept wave percentage-shift for multi channel. Range from 0 to 100. +Default value is 25. + +@item interp +Set delay-line interpolation, @var{linear} or @var{quadratic}. +Default is @var{linear}. +@end table + +@section highpass + +Apply a high-pass filter with 3dB point frequency. +The filter can be either single-pole, or double-pole (the default). +The filter roll off at 6dB per pole per octave (20dB per pole per decade). + +The filter accepts the following options: + +@table @option +@item frequency, f +Set frequency in Hz. Default is 3000. + +@item poles, p +Set number of poles. Default is 2. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Specify the band-width of a filter in width_type units. +Applies only to double-pole filter. +The default is 0.707q and gives a Butterworth response. +@end table + @section join + Join multiple input streams into one multi-channel stream. It accepts the following parameters: @@ -634,21 +1537,335 @@ and if that fails it picks the first unused input channel. Join 3 inputs (with properly set channel layouts): @example -avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT +ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT @end example 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 +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 ladspa + +Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin. + +To enable compilation of this filter you need to configure FFmpeg with +@code{--enable-ladspa}. + +@table @option +@item file, f +Specifies the name of LADSPA plugin library to load. If the environment +variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in +each one of the directories specified by the colon separated list in +@env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in +this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/}, +@file{/usr/lib/ladspa/}. + +@item plugin, p +Specifies the plugin within the library. Some libraries contain only +one plugin, but others contain many of them. If this is not set filter +will list all available plugins within the specified library. + +@item controls, c +Set the '|' separated list of controls which are zero or more floating point +values that determine the behavior of the loaded plugin (for example delay, +threshold or gain). +Controls need to be defined using the following syntax: +c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where +@var{valuei} is the value set on the @var{i}-th control. +If @option{controls} is set to @code{help}, all available controls and +their valid ranges are printed. + +@item sample_rate, s +Specify the sample rate, default to 44100. Only used if plugin have +zero inputs. + +@item nb_samples, n +Set the number of samples per channel per each output frame, default +is 1024. Only used if plugin have zero inputs. + +@item duration, d +Set the minimum duration of the sourced audio. See the function +@code{av_parse_time()} for the accepted format, also check the "Time duration" +section in the ffmpeg-utils manual. +Note that the resulting duration may be greater than the specified duration, +as the generated audio is always cut at the end of a complete frame. +If not specified, or the expressed duration is negative, the audio is +supposed to be generated forever. +Only used if plugin have zero inputs. + +@end table + +@subsection Examples + +@itemize +@item +List all available plugins within amp (LADSPA example plugin) library: +@example +ladspa=file=amp +@end example + +@item +List all available controls and their valid ranges for @code{vcf_notch} +plugin from @code{VCF} library: +@example +ladspa=f=vcf:p=vcf_notch:c=help +@end example + +@item +Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT) +plugin library: +@example +ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12 +@end example + +@item +Add reverberation to the audio using TAP-plugins +(Tom's Audio Processing plugins): +@example +ladspa=file=tap_reverb:tap_reverb +@end example + +@item +Generate white noise, with 0.2 amplitude: +@example +ladspa=file=cmt:noise_source_white:c=c0=.2 +@end example + +@item +Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the +@code{C* Audio Plugin Suite} (CAPS) library: +@example +ladspa=file=caps:Click:c=c1=20' +@end example + +@item +Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect: +@example +ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2 +@end example +@end itemize + +@subsection Commands + +This filter supports the following commands: +@table @option +@item cN +Modify the @var{N}-th control value. + +If the specified value is not valid, it is ignored and prior one is kept. +@end table + +@section lowpass + +Apply a low-pass filter with 3dB point frequency. +The filter can be either single-pole or double-pole (the default). +The filter roll off at 6dB per pole per octave (20dB per pole per decade). + +The filter accepts the following options: + +@table @option +@item frequency, f +Set frequency in Hz. Default is 500. + +@item poles, p +Set number of poles. Default is 2. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Specify the band-width of a filter in width_type units. +Applies only to double-pole filter. +The default is 0.707q and gives a Butterworth response. +@end table + +@section pan + +Mix channels with specific gain levels. The filter accepts the output +channel layout followed by a set of channels definitions. + +This filter is also designed to remap efficiently the channels of an audio +stream. + +The filter accepts parameters of the form: +"@var{l}:@var{outdef}:@var{outdef}:..." + +@table @option +@item l +output channel layout or number of channels + +@item outdef +output channel specification, of the form: +"@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]" + +@item out_name +output channel to define, either a channel name (FL, FR, etc.) or a channel +number (c0, c1, etc.) + +@item gain +multiplicative coefficient for the channel, 1 leaving the volume unchanged + +@item in_name +input channel to use, see out_name for details; it is not possible to mix +named and numbered input channels +@end table + +If the `=' in a channel specification is replaced by `<', then the gains for +that specification will be renormalized so that the total is 1, thus +avoiding clipping noise. + +@subsection Mixing examples + +For example, if you want to down-mix from stereo to mono, but with a bigger +factor for the left channel: +@example +pan=1:c0=0.9*c0+0.1*c1 +@end example + +A customized down-mix to stereo that works automatically for 3-, 4-, 5- and +7-channels surround: +@example +pan=stereo: FL < FL + 0.5*FC + 0.6*BL + 0.6*SL : FR < FR + 0.5*FC + 0.6*BR + 0.6*SR +@end example + +Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system +that should be preferred (see "-ac" option) unless you have very specific +needs. + +@subsection Remapping examples + +The channel remapping will be effective if, and only if: + +@itemize +@item gain coefficients are zeroes or ones, +@item only one input per channel output, +@end itemize + +If all these conditions are satisfied, the filter will notify the user ("Pure +channel mapping detected"), and use an optimized and lossless method to do the +remapping. + +For example, if you have a 5.1 source and want a stereo audio stream by +dropping the extra channels: +@example +pan="stereo: c0=FL : c1=FR" +@end example + +Given the same source, you can also switch front left and front right channels +and keep the input channel layout: +@example +pan="5.1: c0=c1 : c1=c0 : c2=c2 : c3=c3 : c4=c4 : c5=c5" +@end example + +If the input is a stereo audio stream, you can mute the front left channel (and +still keep the stereo channel layout) with: +@example +pan="stereo:c1=c1" +@end example + +Still with a stereo audio stream input, you can copy the right channel in both +front left and right: +@example +pan="stereo: c0=FR : c1=FR" +@end example + +@section replaygain + +ReplayGain scanner filter. This filter takes an audio stream as an input and +outputs it unchanged. +At end of filtering it displays @code{track_gain} and @code{track_peak}. + @section resample + Convert the audio sample format, sample rate and channel layout. It 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. +not meant to be used directly. + +@section silencedetect + +Detect silence in an audio stream. + +This filter logs a message when it detects that the input audio volume is less +or equal to a noise tolerance value for a duration greater or equal to the +minimum detected noise duration. + +The printed times and duration are expressed in seconds. + +The filter accepts the following options: + +@table @option +@item duration, d +Set silence duration until notification (default is 2 seconds). + +@item noise, n +Set noise tolerance. Can be specified in dB (in case "dB" is appended to the +specified value) or amplitude ratio. Default is -60dB, or 0.001. +@end table + +@subsection Examples + +@itemize +@item +Detect 5 seconds of silence with -50dB noise tolerance: +@example +silencedetect=n=-50dB:d=5 +@end example + +@item +Complete example with @command{ffmpeg} to detect silence with 0.0001 noise +tolerance in @file{silence.mp3}: +@example +ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null - +@end example +@end itemize + +@section treble + +Boost or cut treble (upper) frequencies of the audio using a two-pole +shelving filter with a response similar to that of a standard +hi-fi's tone-controls. This is also known as shelving equalisation (EQ). + +The filter accepts the following options: + +@table @option +@item gain, g +Give the gain at whichever is the lower of ~22 kHz and the +Nyquist frequency. Its useful range is about -20 (for a large cut) +to +20 (for a large boost). Beware of clipping when using a positive gain. + +@item frequency, f +Set the filter's central frequency and so can be used +to extend or reduce the frequency range to be boosted or cut. +The default value is @code{3000} Hz. + +@item width_type +Set method to specify band-width of filter. +@table @option +@item h +Hz +@item q +Q-Factor +@item o +octave +@item s +slope +@end table + +@item width, w +Determine how steep is the filter's shelf transition. +@end table @section volume @@ -658,7 +1875,7 @@ It accepts the following parameters: @table @option @item volume -This expresses how the audio volume will be increased or decreased. +Set audio volume expression. Output values are clipped to the maximum value. @@ -667,7 +1884,7 @@ The output audio volume is given by the relation: @var{output_volume} = @var{volume} * @var{input_volume} @end example -The default value for @var{volume} is 1.0. +The default value for @var{volume} is "1.0". @item precision This parameter represents the mathematical precision. @@ -706,6 +1923,65 @@ Pre-amplification gain in dB to apply to the selected replaygain gain. Default value for @var{replaygain_preamp} is 0.0. +@item eval +Set when the volume expression is evaluated. + +It accepts the following values: +@table @samp +@item once +only evaluate expression once during the filter initialization, or +when the @samp{volume} command is sent + +@item frame +evaluate expression for each incoming frame +@end table + +Default value is @samp{once}. +@end table + +The volume expression can contain the following parameters. + +@table @option +@item n +frame number (starting at zero) +@item nb_channels +number of channels +@item nb_consumed_samples +number of samples consumed by the filter +@item nb_samples +number of samples in the current frame +@item pos +original frame position in the file +@item pts +frame PTS +@item sample_rate +sample rate +@item startpts +PTS at start of stream +@item startt +time at start of stream +@item t +frame time +@item tb +timestamp timebase +@item volume +last set volume value +@end table + +Note that when @option{eval} is set to @samp{once} only the +@var{sample_rate} and @var{tb} variables are available, all other +variables will evaluate to NAN. + +@subsection Commands + +This filter supports the following commands: +@table @option +@item volume +Modify the volume expression. +The command accepts the same syntax of the corresponding option. + +If the specified expression is not valid, it is kept at its current +value. @item replaygain_noclip Prevent clipping by limiting the gain applied. @@ -724,53 +2000,80 @@ volume=volume=1/2 volume=volume=-6.0206dB @end example +In all the above example the named key for @option{volume} can be +omitted, for example like in: +@example +volume=0.5 +@end example + @item Increase input audio power by 6 decibels using fixed-point precision: @example volume=volume=6dB:precision=fixed @end example + +@item +Fade volume after time 10 with an annihilation period of 5 seconds: +@example +volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame +@end example @end itemize -@c man end AUDIO FILTERS +@section volumedetect -@chapter Audio Sources -@c man begin AUDIO SOURCES +Detect the volume of the input video. -Below is a description of the currently available audio sources. +The filter has no parameters. The input is not modified. Statistics about +the volume will be printed in the log when the input stream end is reached. -@section anullsrc +In particular it will show the mean volume (root mean square), maximum +volume (on a per-sample basis), and the beginning of a histogram of the +registered volume values (from the maximum value to a cumulated 1/1000 of +the samples). -The null audio source; it never returns audio frames. It is mainly useful as a -template and for use in analysis / debugging tools. +All volumes are in decibels relative to the maximum PCM value. -It accepts, as an optional parameter, a string of the form -@var{sample_rate}:@var{channel_layout}. +@subsection Examples -@var{sample_rate} specifies the sample rate, and defaults to 44100. +Here is an excerpt of the output: +@example +[Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB +[Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB +[Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6 +[Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62 +[Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286 +[Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042 +[Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551 +[Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609 +[Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409 +@end example + +It means that: +@itemize +@item +The mean square energy is approximately -27 dB, or 10^-2.7. +@item +The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB. +@item +There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc. +@end itemize -@var{channel_layout} specifies the channel layout, and can be either an -integer or a string representing a channel layout. The default value -of @var{channel_layout} is 3, which corresponds to CH_LAYOUT_STEREO. +In other words, raising the volume by +4 dB does not cause any clipping, +raising it by +5 dB causes clipping for 6 samples, etc. -Check the channel_layout_map definition in -@file{libavutil/channel_layout.c} for the mapping between strings and -channel layout values. +@c man end AUDIO FILTERS -Some examples: -@example -# Set the sample rate to 48000 Hz and the channel layout to CH_LAYOUT_MONO -anullsrc=48000:4 +@chapter Audio Sources +@c man begin AUDIO SOURCES -# The same as above -anullsrc=48000:mono -@end example +Below is a description of the currently available audio sources. @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; it -is for insertion by calling programs, through the interface defined in -@file{libavfilter/buffersrc.h}. +This source is mainly intended for a programmatic use, in particular +through the interface defined in @file{libavfilter/asrc_abuffer.h}. It accepts the following parameters: @table @option @@ -780,18 +2083,294 @@ The timebase which will be used for timestamps of submitted frames. It must be either a floating-point number or in @var{numerator}/@var{denominator} form. @item sample_rate -The audio sample rate. +The sample rate of the incoming audio buffers. @item sample_fmt -The name of the sample format, as returned by @code{av_get_sample_fmt_name()}. +The sample format of the incoming audio buffers. +Either a sample format name or its corresponging integer representation from +the enum AVSampleFormat in @file{libavutil/samplefmt.h} @item channel_layout -The channel layout of the audio data, in the form that can be accepted by -@code{av_get_channel_layout()}. +The channel layout of the incoming audio buffers. +Either a channel layout name from channel_layout_map in +@file{libavutil/channel_layout.c} or its corresponding integer representation +from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h} + +@item channels +The number of channels of the incoming audio buffers. +If both @var{channels} and @var{channel_layout} are specified, then they +must be consistent. + +@end table + +@subsection Examples + +@example +abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo +@end example + +will instruct the source to accept planar 16bit signed stereo at 44100Hz. +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=sample_rate=44100:sample_fmt=6:channel_layout=0x3 +@end example + +@section aevalsrc + +Generate an audio signal specified by an expression. + +This source accepts in input one or more expressions (one for each +channel), which are evaluated and used to generate a corresponding +audio signal. + +This source accepts the following options: + +@table @option +@item exprs +Set the '|'-separated expressions list for each separate channel. In case the +@option{channel_layout} option is not specified, the selected channel layout +depends on the number of provided expressions. Otherwise the last +specified expression is applied to the remaining output channels. + +@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. +Note that the resulting duration may be greater than the specified +duration, as the generated audio is always cut at the end of a +complete frame. + +If not specified, or the expressed duration is negative, the audio is +supposed to be generated forever. + +@item nb_samples, n +Set the number of samples per channel per each output frame, +default to 1024. + +@item sample_rate, s +Specify the sample rate, default to 44100. +@end table + +Each expression in @var{exprs} can contain the following constants: + +@table @option +@item n +number of the evaluated sample, starting from 0 + +@item t +time of the evaluated sample expressed in seconds, starting from 0 + +@item s +sample rate + +@end table + +@subsection Examples + +@itemize +@item +Generate silence: +@example +aevalsrc=0 +@end example + +@item +Generate a sin signal with frequency of 440 Hz, set sample rate to +8000 Hz: +@example +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 +aevalsrc="-2+random(0)" +@end example + +@item +Generate an amplitude modulated signal: +@example +aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)" +@end example + +@item +Generate 2.5 Hz binaural beats on a 360 Hz carrier: +@example +aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)" +@end example + +@end itemize + +@section anullsrc + +The null audio source, return unprocessed audio frames. It is mainly useful +as a template and to be employed in analysis / debugging tools, or as +the source for filters which ignore the input data (for example the sox +synth filter). + +This source accepts the following options: + +@table @option + +@item channel_layout, cl + +Specifies the channel layout, and can be either an integer or a string +representing a channel layout. The default value of @var{channel_layout} +is "stereo". + +Check the channel_layout_map definition in +@file{libavutil/channel_layout.c} for the mapping between strings and +channel layout values. + +@item sample_rate, r +Specifies the sample rate, and defaults to 44100. + +@item nb_samples, n +Set the number of samples per requested frames. + @end table +@subsection Examples + +@itemize +@item +Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. +@example +anullsrc=r=48000:cl=4 +@end example + +@item +Do the same operation with a more obvious syntax: +@example +anullsrc=r=48000:cl=mono +@end example +@end itemize + All the parameters need to be explicitly defined. +@section flite + +Synthesize a voice utterance using the libflite library. + +To enable compilation of this filter you need to configure FFmpeg with +@code{--enable-libflite}. + +Note that the flite library is not thread-safe. + +The filter accepts the following options: + +@table @option + +@item list_voices +If set to 1, list the names of the available voices and exit +immediately. Default value is 0. + +@item nb_samples, n +Set the maximum number of samples per frame. Default value is 512. + +@item textfile +Set the filename containing the text to speak. + +@item text +Set the text to speak. + +@item voice, v +Set the voice to use for the speech synthesis. Default value is +@code{kal}. See also the @var{list_voices} option. +@end table + +@subsection Examples + +@itemize +@item +Read from file @file{speech.txt}, and synthetize the text using the +standard flite voice: +@example +flite=textfile=speech.txt +@end example + +@item +Read the specified text selecting the @code{slt} voice: +@example +flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt +@end example + +@item +Input text to ffmpeg: +@example +ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt +@end example + +@item +Make @file{ffplay} speak the specified text, using @code{flite} and +the @code{lavfi} device: +@example +ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.' +@end example +@end itemize + +For more information about libflite, check: +@url{http://www.speech.cs.cmu.edu/flite/} + +@section sine + +Generate an audio signal made of a sine wave with amplitude 1/8. + +The audio signal is bit-exact. + +The filter accepts the following options: + +@table @option + +@item frequency, f +Set the carrier frequency. Default is 440 Hz. + +@item beep_factor, b +Enable a periodic beep every second with frequency @var{beep_factor} times +the carrier frequency. Default is 0, meaning the beep is disabled. + +@item sample_rate, r +Specify the sample rate, default is 44100. + +@item duration, d +Specify the duration of the generated audio stream. + +@item samples_per_frame +Set the number of samples per output frame, default is 1024. +@end table + +@subsection Examples + +@itemize + +@item +Generate a simple 440 Hz sine wave: +@example +sine +@end example + +@item +Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds: +@example +sine=220:4:d=5 +sine=f=220:b=4:d=5 +sine=frequency=220:beep_factor=4:duration=5 +@end example + +@end itemize + @c man end AUDIO SOURCES @chapter Audio Sinks @@ -799,31 +2378,135 @@ All the parameters need to be explicitly defined. Below is a description of the currently available audio sinks. +@section abuffersink + +Buffer audio frames, and make them available to the end of filter chain. + +This sink is mainly intended for programmatic use, in particular +through the interface defined in @file{libavfilter/buffersink.h} +or the options system. + +It accepts a pointer to an AVABufferSinkContext structure, which +defines the incoming buffers' formats, to be passed as the opaque +parameter to @code{avfilter_init_filter} for initialization. @section anullsink Null audio sink; do absolutely nothing with the input audio. It is mainly useful as a template and for use 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}. - -It does not accept any parameters. - @c man end AUDIO SINKS @chapter Video Filters @c man begin VIDEO FILTERS -When you configure your Libav build, you can disable any of the -existing filters using --disable-filters. +When you configure your FFmpeg build, you can disable any of the +existing filters using @code{--disable-filters}. The configure output will show the video filters included in your build. Below is a description of the currently available video filters. +@section alphaextract + +Extract the alpha component from the input as a grayscale video. This +is especially useful with the @var{alphamerge} filter. + +@section alphamerge + +Add or replace the alpha component of the primary input with the +grayscale value of a second input. This is intended for use with +@var{alphaextract} to allow the transmission or storage of frame +sequences that have alpha in a format that doesn't support an alpha +channel. + +For example, to reconstruct full frames from a normal YUV-encoded video +and a separate video created with @var{alphaextract}, you might use: +@example +movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out] +@end example + +Since this filter is designed for reconstruction, it operates on frame +sequences without considering timestamps, and terminates when either +input reaches end of stream. This will cause problems if your encoding +pipeline drops frames. If you're trying to apply an image as an +overlay to a video stream, consider the @var{overlay} filter instead. + +@section ass + +Same as the @ref{subtitles} filter, except that it doesn't require libavcodec +and libavformat to work. On the other hand, it is limited to ASS (Advanced +Substation Alpha) subtitles files. + +@section bbox + +Compute the bounding box for the non-black pixels in the input frame +luminance plane. + +This filter computes the bounding box containing all the pixels with a +luminance value greater than the minimum allowed value. +The parameters describing the bounding box are printed on the filter +log. + +The filter accepts the following option: + +@table @option +@item min_val +Set the minimal luminance value. Default is @code{16}. +@end table + +@section blackdetect + +Detect video intervals that are (almost) completely black. Can be +useful to detect chapter transitions, commercials, or invalid +recordings. Output lines contains the time for the start, end and +duration of the detected black interval expressed in seconds. + +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 following options: + +@table @option +@item black_min_duration, d +Set the minimum detected black duration expressed in seconds. It must +be a non-negative floating point number. + +Default value is 2.0. + +@item picture_black_ratio_th, pic_th +Set the threshold for considering a picture "black". +Express the minimum value for the ratio: +@example +@var{nb_black_pixels} / @var{nb_pixels} +@end example + +for which a picture is considered black. +Default value is 0.98. + +@item pixel_black_th, pix_th +Set the threshold for considering a pixel "black". + +The threshold expresses the maximum pixel luminance value for which a +pixel is considered "black". The provided value is scaled according to +the following equation: +@example +@var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size} +@end example + +@var{luminance_range_size} and @var{luminance_minimum_value} depend on +the input video format, the range is [0-255] for YUV full-range +formats and [16-235] for YUV non full-range formats. + +Default value is 0.10. +@end table + +The following example sets the maximum pixel threshold to the minimum +value, and detects only black intervals of 2 or more seconds: +@example +blackdetect=d=2:pix_th=0.00 +@end example + @section blackframe Detect frames that are (almost) completely black. Can be useful to @@ -840,13 +2523,150 @@ It accepts the following parameters: @item amount The percentage of the pixels that have to be below the threshold; it defaults to -98. +@code{98}. -@item threshold -The threshold below which a pixel value is considered black; it defaults to 32. +@item threshold, thresh +The threshold below which a pixel value is considered black; it defaults to +@code{32}. @end table +@section blend + +Blend two video frames into each other. + +It takes two input streams and outputs one stream, the first input is the +"top" layer and second input is "bottom" layer. +Output terminates when shortest input terminates. + +A description of the accepted options follows. + +@table @option +@item c0_mode +@item c1_mode +@item c2_mode +@item c3_mode +@item all_mode +Set blend mode for specific pixel component or all pixel components in case +of @var{all_mode}. Default value is @code{normal}. + +Available values for component modes are: +@table @samp +@item addition +@item and +@item average +@item burn +@item darken +@item difference +@item divide +@item dodge +@item exclusion +@item hardlight +@item lighten +@item multiply +@item negation +@item normal +@item or +@item overlay +@item phoenix +@item pinlight +@item reflect +@item screen +@item softlight +@item subtract +@item vividlight +@item xor +@end table + +@item c0_opacity +@item c1_opacity +@item c2_opacity +@item c3_opacity +@item all_opacity +Set blend opacity for specific pixel component or all pixel components in case +of @var{all_opacity}. Only used in combination with pixel component blend modes. + +@item c0_expr +@item c1_expr +@item c2_expr +@item c3_expr +@item all_expr +Set blend expression for specific pixel component or all pixel components in case +of @var{all_expr}. Note that related mode options will be ignored if those are set. + +The expressions can use the following variables: + +@table @option +@item N +The sequential number of the filtered frame, starting from @code{0}. + +@item X +@item Y +the coordinates of the current sample + +@item W +@item H +the width and height of currently filtered plane + +@item SW +@item SH +Width and height scale depending on the currently filtered plane. It is the +ratio between the corresponding luma plane number of pixels and the current +plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and +@code{0.5,0.5} for chroma planes. + +@item T +Time of the current frame, expressed in seconds. + +@item TOP, A +Value of pixel component at current location for first video frame (top layer). + +@item BOTTOM, B +Value of pixel component at current location for second video frame (bottom layer). +@end table + +@item shortest +Force termination when the shortest input terminates. Default is @code{0}. +@item repeatlast +Continue applying the last bottom frame after the end of the stream. A value of +@code{0} disable the filter after the last frame of the bottom layer is reached. +Default is @code{1}. +@end table + +@subsection Examples + +@itemize +@item +Apply transition from bottom layer to top layer in first 10 seconds: +@example +blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))' +@end example + +@item +Apply 1x1 checkerboard effect: +@example +blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)' +@end example + +@item +Apply uncover left effect: +@example +blend=all_expr='if(gte(N*SW+X,W),A,B)' +@end example + +@item +Apply uncover down effect: +@example +blend=all_expr='if(gte(Y-N*SH,0),A,B)' +@end example + +@item +Apply uncover up-left effect: +@example +blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)' +@end example +@end itemize + @section boxblur Apply a boxblur algorithm to the input video. @@ -855,58 +2675,77 @@ It accepts the following parameters: @table @option -@item luma_radius -@item luma_power -@item chroma_radius -@item chroma_power -@item alpha_radius -@item alpha_power +@item luma_radius, lr +@item luma_power, lp +@item chroma_radius, cr +@item chroma_power, cp +@item alpha_radius, ar +@item alpha_power, ap @end table -The chroma and alpha parameters are optional. If not specified, they default -to the corresponding values set for @var{luma_radius} and -@var{luma_power}. +A description of the accepted options follows. -@var{luma_radius}, @var{chroma_radius}, and @var{alpha_radius} represent -the radius in pixels of the box used for blurring the corresponding -input plane. They are expressions, and can contain the following -constants: @table @option -@item w, h +@item luma_radius, lr +@item chroma_radius, cr +@item alpha_radius, ar +Set an expression for the box radius in pixels used for blurring the +corresponding input plane. + +The radius value must be a non-negative number, and must not be +greater than the value of the expression @code{min(w,h)/2} for the +luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma +planes. + +Default value for @option{luma_radius} is "2". If not specified, +@option{chroma_radius} and @option{alpha_radius} default to the +corresponding value set for @option{luma_radius}. + +The expressions can contain the following constants: +@table @option +@item w +@item h The input width and height in pixels. -@item cw, ch +@item cw +@item ch The input chroma image width and height in pixels. -@item hsub, vsub +@item hsub +@item vsub The horizontal and vertical chroma subsample values. For example, for the pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1. @end table -The radius must be a non-negative number, and must not be greater than -the value of the expression @code{min(w,h)/2} for the luma and alpha planes, -and of @code{min(cw,ch)/2} for the chroma planes. +@item luma_power, lp +@item chroma_power, cp +@item alpha_power, ap +Specify how many times the boxblur filter is applied to the +corresponding plane. -@var{luma_power}, @var{chroma_power}, and @var{alpha_power} represent -how many times the boxblur filter is applied to the corresponding -plane. +Default value for @option{luma_power} is 2. If not specified, +@option{chroma_power} and @option{alpha_power} default to the +corresponding value set for @option{luma_power}. -Some examples: +A value of 0 will disable the effect. +@end table -@itemize +@subsection Examples +@itemize @item Apply a boxblur filter with the luma, chroma, and alpha radii set to 2: @example boxblur=luma_radius=2:luma_power=1 +boxblur=2:1 @end example @item Set the luma radius to 2, and alpha and chroma radius to 0: @example -boxblur=2:1:0:0:0:0 +boxblur=2:1:cr=0:ar=0 @end example @item @@ -914,9 +2753,141 @@ Set the luma and chroma radii to a fraction of the video dimension: @example boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1 @end example +@end itemize + +@section colorbalance +Modify intensity of primary colors (red, green and blue) of input frames. + +The filter allows an input frame to be adjusted in the shadows, midtones or highlights +regions for the red-cyan, green-magenta or blue-yellow balance. + +A positive adjustment value shifts the balance towards the primary color, a negative +value towards the complementary color. + +The filter accepts the following options: + +@table @option +@item rs +@item gs +@item bs +Adjust red, green and blue shadows (darkest pixels). + +@item rm +@item gm +@item bm +Adjust red, green and blue midtones (medium pixels). + +@item rh +@item gh +@item bh +Adjust red, green and blue highlights (brightest pixels). + +Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}. +@end table + +@subsection Examples + +@itemize +@item +Add red color cast to shadows: +@example +colorbalance=rs=.3 +@end example +@end itemize + +@section colorchannelmixer + +Adjust video input frames by re-mixing color channels. + +This filter modifies a color channel by adding the values associated to +the other channels of the same pixels. For example if the value to +modify is red, the output value will be: +@example +@var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra} +@end example + +The filter accepts the following options: + +@table @option +@item rr +@item rg +@item rb +@item ra +Adjust contribution of input red, green, blue and alpha channels for output red channel. +Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}. + +@item gr +@item gg +@item gb +@item ga +Adjust contribution of input red, green, blue and alpha channels for output green channel. +Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}. + +@item br +@item bg +@item bb +@item ba +Adjust contribution of input red, green, blue and alpha channels for output blue channel. +Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}. + +@item ar +@item ag +@item ab +@item aa +Adjust contribution of input red, green, blue and alpha channels for output alpha channel. +Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}. + +Allowed ranges for options are @code{[-2.0, 2.0]}. +@end table +@subsection Examples + +@itemize +@item +Convert source to grayscale: +@example +colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3 +@end example +@item +Simulate sepia tones: +@example +colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131 +@end example @end itemize +@section colormatrix + +Convert color matrix. + +The filter accepts the following options: + +@table @option +@item src +@item dst +Specify the source and destination color matrix. Both values must be +specified. + +The accepted values are: +@table @samp +@item bt709 +BT.709 + +@item bt601 +BT.601 + +@item smpte240m +SMPTE-240M + +@item fcc +FCC +@end table +@end table + +For example to convert from BT.601 to SMPTE-240M, use the command: +@example +colormatrix=bt601:smpte240m +@end example + @section copy Copy the input source unchanged to the output. This is mainly useful for @@ -929,60 +2900,82 @@ Crop the input video to given dimensions. It accepts the following parameters: @table @option +@item w, out_w +The width of the output video. It defaults to @code{iw}. +This expression is evaluated only once during the filter +configuration. -@item out_w -The width of the output video. - -@item out_h -The height of the output video. +@item h, out_h +The height of the output video. It defaults to @code{ih}. +This expression is evaluated only once during the filter +configuration. @item x The horizontal position, in the input video, of the left edge of the output -video. +video. It defaults to @code{(in_w-out_w)/2}. +This expression is evaluated per-frame. @item y The vertical position, in the input video, of the top edge of the output video. +It defaults to @code{(in_h-out_h)/2}. +This expression is evaluated per-frame. +@item keep_aspect +If set to 1 will force the output display aspect ratio +to be the same of the input, by changing the output sample aspect +ratio. It defaults to 0. @end table -The parameters are expressions containing the following constants: +The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are +expressions containing the following constants: @table @option -@item E, PI, PHI -These are approximated values for the mathematical constants e -(Euler's number), pi (Greek pi), and phi (the golden ratio). - -@item x, y +@item x +@item y The computed values for @var{x} and @var{y}. They are evaluated for each new frame. -@item in_w, in_h +@item in_w +@item in_h The input width and height. -@item iw, ih +@item iw +@item ih These are the same as @var{in_w} and @var{in_h}. -@item out_w, out_h +@item out_w +@item out_h The output (cropped) width and height. -@item ow, oh +@item ow +@item oh These are the same as @var{out_w} and @var{out_h}. +@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 +@item vsub +horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. + @item n The number of the input frame, starting from 0. +@item pos +the position in the file of the input frame, NAN if unknown + @item t The timestamp expressed in seconds. It's NAN if the input timestamp is unknown. @end table -The @var{out_w} and @var{out_h} parameters specify the expressions for -the width and height of the output (cropped) video. They are only -evaluated during the configuration of the filter. - -The default value of @var{out_w} is "in_w", and the default value of -@var{out_h} is "in_h". - The expression for @var{out_w} may depend on the value of @var{out_h}, and the expression for @var{out_h} may depend on @var{out_w}, but they cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are @@ -993,48 +2986,87 @@ position of the top-left corner of the output (non-cropped) area. They are evaluated for each frame. If the evaluated value is not valid, it is approximated to the nearest valid value. -The default value of @var{x} is "(in_w-out_w)/2", and the default -value for @var{y} is "(in_h-out_h)/2", which set the cropped area at -the center of the input image. - The expression for @var{x} may depend on @var{y}, and the expression for @var{y} may depend on @var{x}. -Some examples: +@subsection Examples + +@itemize +@item +Crop area with size 100x100 at position (12,34). +@example +crop=100:100:12:34 +@end example + +Using named options, the example above becomes: +@example +crop=w=100:h=100:x=12:y=34 +@end example + +@item +Crop the central input area with size 100x100: @example -# Crop the central input area with size 100x100 -crop=out_w=100:out_h=100 +crop=100:100 +@end example -# Crop the central input area with size 2/3 of the input video -"crop=out_w=2/3*in_w:out_h=2/3*in_h" +@item +Crop the central input area with size 2/3 of the input video: +@example +crop=2/3*in_w:2/3*in_h +@end example -# Crop the input video central square +@item +Crop the input video central square: +@example crop=out_w=in_h +crop=in_h +@end example -# 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=out_w=in_w-100:out_h=in_h-100:x=100:y=100 +@item +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. +@example +crop=in_w-100:in_h-100:100:100 +@end example -# Crop 10 pixels from the left and right borders, and 20 pixels from -# the top and bottom borders -"crop=out_w=in_w-2*10:out_h=in_h-2*20" +@item +Crop 10 pixels from the left and right borders, and 20 pixels from +the top and bottom borders +@example +crop=in_w-2*10:in_h-2*20 +@end example -# Keep only the bottom right quarter of the input image -"crop=out_w=in_w/2:out_h=in_h/2:x=in_w/2:y=in_h/2" +@item +Keep only the bottom right quarter of the input image: +@example +crop=in_w/2:in_h/2:in_w/2:in_h/2 +@end example -# Crop height for getting Greek harmony -"crop=out_w=in_w:out_h=1/PHI*in_w" +@item +Crop height for getting Greek harmony: +@example +crop=in_w:1/PHI*in_w +@end example -# 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)" +@item +Appply trembling effect: +@example +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) +@end example -# Erratic camera effect depending on timestamp -"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)" +@item +Apply erratic camera effect depending on timestamp: +@example +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)" +@end example -# Set x depending on the value of y -"crop=in_w/2:in_h/2:y:10+10*sin(n/10)" +@item +Set x depending on the value of y: +@example +crop=in_w/2:in_h/2:y:10+10*sin(n/10) @end example +@end itemize @section cropdetect @@ -1049,8 +3081,9 @@ It accepts the following parameters: @table @option @item limit -The threshold, an optional parameter between nothing (0) and -everything (255). It defaults to 24. +Set higher black value threshold, which can be optionally specified +from nothing (0) to everything (255). An intensity value greater +to the set value is considered non-black. It defaults to 24. @item round The value which the width/height should be divisible by. It defaults to @@ -1058,16 +3091,255 @@ The value which the width/height should be divisible by. It defaults to get only even dimensions (needed for 4:2:2 video). 16 is best when encoding to most video codecs. -@item reset -A counter that determines how many frames cropdetect will reset -the previously detected largest video area after. It will then start over -and detect the current optimal crop area. It defaults to 0. +@item reset_count, reset +Set the counter that determines after how many frames cropdetect will +reset the previously detected largest video area and start over to +detect the current optimal crop area. Default value is 0. This can be useful when channel logos distort the video area. 0 indicates 'never reset', and returns the largest area encountered during playback. @end table +@anchor{curves} +@section curves + +Apply color adjustments using curves. + +This filter is similar to the Adobe Photoshop and GIMP curves tools. Each +component (red, green and blue) has its values defined by @var{N} key points +tied from each other using a smooth curve. The x-axis represents the pixel +values from the input frame, and the y-axis the new pixel values to be set for +the output frame. + +By default, a component curve is defined by the two points @var{(0;0)} and +@var{(1;1)}. This creates a straight line where each original pixel value is +"adjusted" to its own value, which means no change to the image. + +The filter allows you to redefine these two points and add some more. A new +curve (using a natural cubic spline interpolation) will be define to pass +smoothly through all these new coordinates. The new defined points needs to be +strictly increasing over the x-axis, and their @var{x} and @var{y} values must +be in the @var{[0;1]} interval. If the computed curves happened to go outside +the vector spaces, the values will be clipped accordingly. + +If there is no key point defined in @code{x=0}, the filter will automatically +insert a @var{(0;0)} point. In the same way, if there is no key point defined +in @code{x=1}, the filter will automatically insert a @var{(1;1)} point. + +The filter accepts the following options: + +@table @option +@item preset +Select one of the available color presets. This option can be used in addition +to the @option{r}, @option{g}, @option{b} parameters; in this case, the later +options takes priority on the preset values. +Available presets are: +@table @samp +@item none +@item color_negative +@item cross_process +@item darker +@item increase_contrast +@item lighter +@item linear_contrast +@item medium_contrast +@item negative +@item strong_contrast +@item vintage +@end table +Default is @code{none}. +@item master, m +Set the master key points. These points will define a second pass mapping. It +is sometimes called a "luminance" or "value" mapping. It can be used with +@option{r}, @option{g}, @option{b} or @option{all} since it acts like a +post-processing LUT. +@item red, r +Set the key points for the red component. +@item green, g +Set the key points for the green component. +@item blue, b +Set the key points for the blue component. +@item all +Set the key points for all components (not including master). +Can be used in addition to the other key points component +options. In this case, the unset component(s) will fallback on this +@option{all} setting. +@item psfile +Specify a Photoshop curves file (@code{.asv}) to import the settings from. +@end table + +To avoid some filtergraph syntax conflicts, each key points list need to be +defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}. + +@subsection Examples + +@itemize +@item +Increase slightly the middle level of blue: +@example +curves=blue='0.5/0.58' +@end example + +@item +Vintage effect: +@example +curves=r='0/0.11 .42/.51 1/0.95':g='0.50/0.48':b='0/0.22 .49/.44 1/0.8' +@end example +Here we obtain the following coordinates for each components: +@table @var +@item red +@code{(0;0.11) (0.42;0.51) (1;0.95)} +@item green +@code{(0;0) (0.50;0.48) (1;1)} +@item blue +@code{(0;0.22) (0.49;0.44) (1;0.80)} +@end table + +@item +The previous example can also be achieved with the associated built-in preset: +@example +curves=preset=vintage +@end example + +@item +Or simply: +@example +curves=vintage +@end example + +@item +Use a Photoshop preset and redefine the points of the green component: +@example +curves=psfile='MyCurvesPresets/purple.asv':green='0.45/0.53' +@end example +@end itemize + +@section dctdnoiz + +Denoise frames using 2D DCT (frequency domain filtering). + +This filter is not designed for real time and can be extremely slow. + +The filter accepts the following options: + +@table @option +@item sigma, s +Set the noise sigma constant. + +This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT +coefficient (absolute value) below this threshold with be dropped. + +If you need a more advanced filtering, see @option{expr}. + +Default is @code{0}. + +@item overlap +Set number overlapping pixels for each block. Each block is of size +@code{16x16}. Since the filter can be slow, you may want to reduce this value, +at the cost of a less effective filter and the risk of various artefacts. + +If the overlapping value doesn't allow to process the whole input width or +height, a warning will be displayed and according borders won't be denoised. + +Default value is @code{15}. + +@item expr, e +Set the coefficient factor expression. + +For each coefficient of a DCT block, this expression will be evaluated as a +multiplier value for the coefficient. + +If this is option is set, the @option{sigma} option will be ignored. + +The absolute value of the coefficient can be accessed through the @var{c} +variable. +@end table + +@subsection Examples + +Apply a denoise with a @option{sigma} of @code{4.5}: +@example +dctdnoiz=4.5 +@end example + +The same operation can be achieved using the expression system: +@example +dctdnoiz=e='gte(c, 4.5*3)' +@end example + +@anchor{decimate} +@section decimate + +Drop duplicated frames at regular intervals. + +The filter accepts the following options: + +@table @option +@item cycle +Set the number of frames from which one will be dropped. Setting this to +@var{N} means one frame in every batch of @var{N} frames will be dropped. +Default is @code{5}. + +@item dupthresh +Set the threshold for duplicate detection. If the difference metric for a frame +is less than or equal to this value, then it is declared as duplicate. Default +is @code{1.1} + +@item scthresh +Set scene change threshold. Default is @code{15}. + +@item blockx +@item blocky +Set the size of the x and y-axis blocks used during metric calculations. +Larger blocks give better noise suppression, but also give worse detection of +small movements. Must be a power of two. Default is @code{32}. + +@item ppsrc +Mark main input as a pre-processed input and activate clean source input +stream. This allows the input to be pre-processed with various filters to help +the metrics calculation while keeping the frame selection lossless. When set to +@code{1}, the first stream is for the pre-processed input, and the second +stream is the clean source from where the kept frames are chosen. Default is +@code{0}. + +@item chroma +Set whether or not chroma is considered in the metric calculations. Default is +@code{1}. +@end table + +@section dejudder + +Remove judder produced by partially interlaced telecined content. + +Judder can be introduced, for instance, by @ref{pullup} filter. If the original +source was partially telecined content then the output of @code{pullup,dejudder} +will have a variable frame rate. May change the recorded frame rate of the +container. Aside from that change, this filter will not affect constant frame +rate video. + +The option available in this filter is: +@table @option + +@item cycle +Specify the length of the window over which the judder repeats. + +Accepts any integer greater than 1. Useful values are: +@table @samp + +@item 4 +If the original was telecined from 24 to 30 fps (Film to NTSC). + +@item 5 +If the original was telecined from 25 to 30 fps (PAL to NTSC). + +@item 20 +If a mixture of the two. +@end table + +The default is @samp{4}. +@end table + @section delogo Suppress a TV station logo by a simple interpolation of the surrounding @@ -1077,11 +3349,13 @@ pixels. Just set a rectangle covering the logo and watch it disappear It accepts the following parameters: @table @option -@item x, y +@item x +@item y Specify the top left corner coordinates of the logo. They must be specified. -@item w, h +@item w +@item h Specify the width and height of the logo to clear. They must be specified. @@ -1091,15 +3365,19 @@ Specify the thickness of the fuzzy edge of the rectangle (added to @item show When set to 1, a green rectangle is drawn on the screen to simplify -finding the right @var{x}, @var{y}, @var{w}, @var{h} parameters, and -@var{band} is set to 4. The default value is 0. +finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters. +The default value is 0. + +The rectangle is drawn on the outermost pixels which will be (partly) +replaced with interpolated values. The values of the next pixels +immediately outside this rectangle in each direction will be used to +compute the interpolated pixel values inside the rectangle. @end table -An example: +@subsection Examples @itemize - @item Set a rectangle covering the area with top left corner coordinates 0,0 and size 100x77, and a band of size 10: @@ -1109,6 +3387,86 @@ delogo=x=0:y=0:w=100:h=77:band=10 @end itemize +@section deshake + +Attempt to fix small changes in horizontal and/or vertical shift. This +filter helps remove camera shake from hand-holding a camera, bumping a +tripod, moving on a vehicle, etc. + +The filter accepts the following options: + +@table @option + +@item x +@item y +@item w +@item h +Specify a rectangular area where to limit the search for motion +vectors. +If desired the search for motion vectors can be limited to a +rectangular area of the frame defined by its top left corner, width +and height. These parameters have the same meaning as the drawbox +filter which can be used to visualise the position of the bounding +box. + +This is useful when simultaneous movement of subjects within the frame +might be confused for camera motion by the motion vector search. + +If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1 +then the full frame is used. This allows later options to be set +without specifying the bounding box for the motion vector search. + +Default - search the whole frame. + +@item rx +@item ry +Specify the maximum extent of movement in x and y directions in the +range 0-64 pixels. Default 16. + +@item edge +Specify how to generate pixels to fill blanks at the edge of the +frame. Available values are: +@table @samp +@item blank, 0 +Fill zeroes at blank locations +@item original, 1 +Original image at blank locations +@item clamp, 2 +Extruded edge value at blank locations +@item mirror, 3 +Mirrored edge at blank locations +@end table +Default value is @samp{mirror}. + +@item blocksize +Specify the blocksize to use for motion search. Range 4-128 pixels, +default 8. + +@item contrast +Specify the contrast threshold for blocks. Only blocks with more than +the specified contrast (difference between darkest and lightest +pixels) will be considered. Range 1-255, default 125. + +@item search +Specify the search strategy. Available values are: +@table @samp +@item exhaustive, 0 +Set exhaustive search +@item less, 1 +Set less exhaustive search. +@end table +Default value is @samp{exhaustive}. + +@item filename +If set then a detailed log of the motion search is written to the +specified file. + +@item opencl +If set to 1, specify using OpenCL capabilities, only available if +FFmpeg was configured with @code{--enable-opencl}. Default value is 0. + +@end table + @section drawbox Draw a colored box on the input image. @@ -1116,130 +3474,251 @@ Draw a colored box on the input image. It accepts the following parameters: @table @option +@item x +@item y +The expressions which specify the top left corner coordinates of the box. It defaults to 0. -@item x, y -Specify the top left corner coordinates of the box. It defaults to 0. - -@item width, height -Specify the width and height of the box; if 0 they are interpreted as +@item width, w +@item height, h +The expressions which specify the width and height of the box; if 0 they are interpreted as the input width and height. It defaults to 0. -@item color -Specify the color of the box to write. It can be the name of a color -(case insensitive match) or a 0xRRGGBB[AA] sequence. +@item color, c +Specify the color of the box to write. For the general syntax of this option, +check the "Color" section in the ffmpeg-utils manual. If the special +value @code{invert} is used, the box edge color is the same as the +video with inverted luma. + +@item thickness, t +The expression which sets the thickness of the box edge. Default value is @code{3}. + +See below for the list of accepted constants. @end table -Some examples: +The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the +following constants: + +@table @option +@item dar +The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. + +@item hsub +@item vsub +horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. + +@item in_h, ih +@item in_w, iw +The input width and height. + +@item sar +The input sample aspect ratio. + +@item x +@item y +The x and y offset coordinates where the box is drawn. + +@item w +@item h +The width and height of the drawn box. + +@item t +The thickness of the drawn box. + +These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to +each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. + +@end table + +@subsection Examples + +@itemize +@item +Draw a black box around the edge of the input image: @example -# Draw a black box around the edge of the input image drawbox +@end example -# Draw a box with color red and an opacity of 50% -drawbox=x=10:y=20:width=200:height=60:color=red@@0.5" +@item +Draw a box with color red and an opacity of 50%: +@example +drawbox=10:20:200:60:red@@0.5 @end example -@section drawtext +The previous example can be specified as: +@example +drawbox=x=10:y=20:w=200:h=60:color=red@@0.5 +@end example -Draw a text string or text from a specified file on top of a video, using the -libfreetype library. +@item +Fill the box with pink color: +@example +drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max +@end example -To enable compilation of this filter, you need to configure Libav with -@code{--enable-libfreetype}. -To enable default font fallback and the @var{font} option you need to -configure Libav with @code{--enable-libfontconfig}. +@item +Draw a 2-pixel red 2.40:1 mask: +@example +drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red +@end example +@end itemize -The filter also recognizes strftime() sequences in the provided text -and expands them accordingly. Check the documentation of strftime(). +@section drawgrid + +Draw a grid on the input image. It accepts the following parameters: @table @option +@item x +@item y +The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0. -@item font -The font family to be used for drawing text. By default Sans. - -@item fontfile -The font file to be used for drawing text. The path must be included. -This parameter is mandatory if the fontconfig support is disabled. +@item width, w +@item height, h +The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the +input width and height, respectively, minus @code{thickness}, so image gets +framed. Default to 0. -@item text -The text string to be drawn. The text must be a sequence of UTF-8 -encoded characters. -This parameter is mandatory if no file is specified with the parameter -@var{textfile}. +@item color, c +Specify the color of the grid. For the general syntax of this option, +check the "Color" section in the ffmpeg-utils manual. If the special +value @code{invert} is used, the grid color is the same as the +video with inverted luma. -@item textfile -A text file containing text to be drawn. The text must be a sequence -of UTF-8 encoded characters. +@item thickness, t +The expression which sets the thickness of the grid line. Default value is @code{1}. -This parameter is mandatory if no text string is specified with the -parameter @var{text}. +See below for the list of accepted constants. +@end table -If both text and textfile are specified, an error is thrown. +The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the +following constants: -@item x, y -The offsets where text will be drawn within the video frame. -It is relative to the top/left border of the output image. -They accept expressions similar to the @ref{overlay} filter: @table @option +@item dar +The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. -@item x, y -The computed values for @var{x} and @var{y}. They are evaluated for -each new frame. - -@item main_w, main_h -The main input width and height. +@item hsub +@item vsub +horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. -@item W, H -These are the same as @var{main_w} and @var{main_h}. +@item in_h, ih +@item in_w, iw +The input grid cell width and height. -@item text_w, text_h -The rendered text's width and height. +@item sar +The input sample aspect ratio. -@item w, h -These are the same as @var{text_w} and @var{text_h}. +@item x +@item y +The x and y coordinates of some point of grid intersection (meant to configure offset). -@item n -The number of frames processed, starting from 0. +@item w +@item h +The width and height of the drawn cell. @item t -The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown. +The thickness of the drawn cell. + +These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to +each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. @end table -The default value of @var{x} and @var{y} is 0. +@subsection Examples -@item fontsize -The font size to be used for drawing text. -The default value of @var{fontsize} is 16. +@itemize +@item +Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%: +@example +drawgrid=width=100:height=100:thickness=2:color=red@@0.5 +@end example -@item fontcolor -The color to be used for drawing fonts. -It is either a string (e.g. "red"), or in 0xRRGGBB[AA] format -(e.g. "0xff000033"), possibly followed by an alpha specifier. -The default value of @var{fontcolor} is "black". +@item +Draw a white 3x3 grid with an opacity of 50%: +@example +drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5 +@end example +@end itemize -@item boxcolor -The color to be used for drawing box around text. -It is either a string (e.g. "yellow") or in 0xRRGGBB[AA] format -(e.g. "0xff00ff"), possibly followed by an alpha specifier. -The default value of @var{boxcolor} is "white". +@anchor{drawtext} +@section drawtext + +Draw a text string or text from a specified file on top of a video, using the +libfreetype library. + +To enable compilation of this filter, you need to configure FFmpeg with +@code{--enable-libfreetype}. +To enable default font fallback and the @var{font} option you need to +configure FFmpeg with @code{--enable-libfontconfig}. +To enable the @var{text_shaping} option, you need to configure FFmpeg with +@code{--enable-libfribidi}. + +@subsection Syntax + +It accepts the following parameters: + +@table @option @item box Used to draw a box around text using the background color. The value must be either 1 (enable) or 0 (disable). The default value of @var{box} is 0. -@item shadowx, shadowy -The x and y offsets for the text shadow position with respect to the -position of the text. They can be either positive or negative -values. The default value for both is "0". +@item boxcolor +The color to be used for drawing box around text. For the syntax of this +option, check the "Color" section in the ffmpeg-utils manual. -@item shadowcolor -The color to be used for drawing a shadow behind the drawn text. It -can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA] -form (e.g. "0xff00ff"), possibly followed by an alpha specifier. -The default value of @var{shadowcolor} is "black". +The default value of @var{boxcolor} is "white". + +@item borderw +Set the width of the border to be drawn around the text using @var{bordercolor}. +The default value of @var{borderw} is 0. + +@item bordercolor +Set the color to be used for drawing border around text. For the syntax of this +option, check the "Color" section in the ffmpeg-utils manual. + +The default value of @var{bordercolor} is "black". + +@item expansion +Select how the @var{text} is expanded. Can be either @code{none}, +@code{strftime} (deprecated) or +@code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section +below for details. + +@item fix_bounds +If true, check and fix text coords to avoid clipping. + +@item fontcolor +The color to be used for drawing fonts. For the syntax of this option, check +the "Color" section in the ffmpeg-utils manual. + +The default value of @var{fontcolor} is "black". + +@item fontcolor_expr +String which is expanded the same way as @var{text} to obtain dynamic +@var{fontcolor} value. By default this option has empty value and is not +processed. When this option is set, it overrides @var{fontcolor} option. + +@item font +The font family to be used for drawing text. By default Sans. + +@item fontfile +The font file to be used for drawing text. The path must be included. +This parameter is mandatory if the fontconfig support is disabled. + +@item fontsize +The font size to be used for drawing text. +The default value of @var{fontsize} is 16. + +@item text_shaping +If set to 1, attempt to shape the text (for example, reverse the order of +right-to-left text and join Arabic characters) before drawing it. +Otherwise, just draw the text exactly as given. +By default 1 (if supported). @item ft_load_flags The flags to be used for loading the fonts. @@ -1262,47 +3741,427 @@ a combination of the following values: @item monochrome @item linear_design @item no_autohint -@item end table @end table -Default value is "render". +Default value is "default". For more information consult the documentation for the FT_LOAD_* libfreetype flags. +@item shadowcolor +The color to be used for drawing a shadow behind the drawn text. For the +syntax of this option, check the "Color" section in the ffmpeg-utils manual. + +The default value of @var{shadowcolor} is "black". + +@item shadowx +@item shadowy +The x and y offsets for the text shadow position with respect to the +position of the text. They can be either positive or negative +values. The default value for both is "0". + +@item start_number +The starting frame number for the n/frame_num variable. The default value +is "0". + @item tabsize The size in number of spaces to use for rendering the tab. Default value is 4. -@item fix_bounds -If true, check and fix text coords to avoid clipping. +@item timecode +Set the initial timecode representation in "hh:mm:ss[:;.]ff" +format. It can be used with or without text parameter. @var{timecode_rate} +option must be specified. + +@item timecode_rate, rate, r +Set the timecode frame rate (timecode only). + +@item text +The text string to be drawn. The text must be a sequence of UTF-8 +encoded characters. +This parameter is mandatory if no file is specified with the parameter +@var{textfile}. + +@item textfile +A text file containing text to be drawn. The text must be a sequence +of UTF-8 encoded characters. + +This parameter is mandatory if no text string is specified with the +parameter @var{text}. + +If both @var{text} and @var{textfile} are specified, an error is thrown. + +@item reload +If set to 1, the @var{textfile} will be reloaded before each frame. +Be sure to update it atomically, or it may be read partially, or even fail. + +@item x +@item y +The expressions which specify the offsets where text will be drawn +within the video frame. They are relative to the top/left border of the +output image. + +The default value of @var{x} and @var{y} is "0". + +See below for the list of accepted constants and functions. +@end table + +The parameters for @var{x} and @var{y} are expressions containing the +following constants and functions: + +@table @option +@item dar +input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} + +@item hsub +@item vsub +horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. + +@item line_h, lh +the height of each text line + +@item main_h, h, H +the input height + +@item main_w, w, W +the input width + +@item max_glyph_a, ascent +the maximum distance from the baseline to the highest/upper grid +coordinate used to place a glyph outline point, for all the rendered +glyphs. +It is a positive value, due to the grid's orientation with the Y axis +upwards. + +@item max_glyph_d, descent +the maximum distance from the baseline to the lowest grid coordinate +used to place a glyph outline point, for all the rendered glyphs. +This is a negative value, due to the grid's orientation, with the Y axis +upwards. + +@item max_glyph_h +maximum glyph height, that is the maximum height for all the glyphs +contained in the rendered text, it is equivalent to @var{ascent} - +@var{descent}. + +@item max_glyph_w +maximum glyph width, that is the maximum width for all the glyphs +contained in the rendered text + +@item n +the number of input frame, starting from 0 + +@item rand(min, max) +return a random number included between @var{min} and @var{max} + +@item sar +The input sample aspect ratio. + +@item t +timestamp expressed in seconds, NAN if the input timestamp is unknown + +@item text_h, th +the height of the rendered text + +@item text_w, tw +the width of the rendered text + +@item x +@item y +the x and y offset coordinates where the text is drawn. + +These parameters allow the @var{x} and @var{y} expressions to refer +each other, so you can for example specify @code{y=x/dar}. @end table -For example the command: +@anchor{drawtext_expansion} +@subsection Text expansion + +If @option{expansion} is set to @code{strftime}, +the filter recognizes strftime() sequences in the provided text and +expands them accordingly. Check the documentation of strftime(). This +feature is deprecated. + +If @option{expansion} is set to @code{none}, the text is printed verbatim. + +If @option{expansion} is set to @code{normal} (which is the default), +the following expansion mechanism is used. + +The backslash character '\', followed by any character, always expands to +the second character. + +Sequence of the form @code{%@{...@}} are expanded. The text between the +braces is a function name, possibly followed by arguments separated by ':'. +If the arguments contain special characters or delimiters (':' or '@}'), +they should be escaped. + +Note that they probably must also be escaped as the value for the +@option{text} option in the filter argument string and as the filter +argument in the filtergraph description, and possibly also for the shell, +that makes up to four levels of escaping; using a text file avoids these +problems. + +The following functions are available: + +@table @command + +@item expr, e +The expression evaluation result. + +It must take one argument specifying the expression to be evaluated, +which accepts the same constants and functions as the @var{x} and +@var{y} values. Note that not all constants should be used, for +example the text size is not known when evaluating the expression, so +the constants @var{text_w} and @var{text_h} will have an undefined +value. + +@item expr_int_format, eif +Evaluate the expression's value and output as formatted integer. + +First argument is expression to be evaluated, same as for @var{expr} function. +Second argument specifies output format. Allowed values are 'x', 'X', 'd' and +'u', they are treated exactly as in printf function. +Third parameter is optional and sets the number of positions taken by output. +Effectively this allows to add padding with zeros from the left. + +@item gmtime +The time at which the filter is running, expressed in UTC. +It can accept an argument: a strftime() format string. + +@item localtime +The time at which the filter is running, expressed in the local time zone. +It can accept an argument: a strftime() format string. + +@item metadata +Frame metadata. It must take one argument specifying metadata key. + +@item n, frame_num +The frame number, starting from 0. + +@item pict_type +A 1 character description of the current picture type. + +@item pts +The timestamp of the current frame. +It can take up to two arguments. + +The first argument is the format of the timestamp; it defaults to @code{flt} +for seconds as a decimal number with microsecond accuracy; @code{hms} stands +for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy. + +The second argument is an offset added to the timestamp. + +@end table + +@subsection Examples + +@itemize +@item +Draw "Test Text" with font FreeSerif, using the default values for the +optional parameters. + @example drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'" @end example -will draw "Test Text" with font FreeSerif, using the default values -for the optional parameters. +@item +Draw 'Test Text' with font FreeSerif of size 24 at position x=100 +and y=50 (counting from the top-left corner of the screen), text is +yellow with a red box around it. Both the text and the box have an +opacity of 20%. -The command: @example drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\ x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2" @end example -will draw 'Test Text' with font FreeSerif of size 24 at position x=100 -and y=50 (counting from the top-left corner of the screen), text is -yellow with a red box around it. Both the text and the box have an -opacity of 20%. - Note that the double quotes are not necessary if spaces are not used within the parameter list. +@item +Show the text at the center of the video frame: +@example +drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2" +@end example + +@item +Show a text line sliding from right to left in the last row of the video +frame. The file @file{LONG_LINE} is assumed to contain a single line +with no newlines. +@example +drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t" +@end example + +@item +Show the content of file @file{CREDITS} off the bottom of the frame and scroll up. +@example +drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t" +@end example + +@item +Draw a single green letter "g", at the center of the input video. +The glyph baseline is placed at half screen height. +@example +drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent" +@end example + +@item +Show text for 1 second every 3 seconds: +@example +drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'" +@end example + +@item +Use fontconfig to set the font. Note that the colons need to be escaped. +@example +drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg' +@end example + +@item +Print the date of a real-time encoding (see strftime(3)): +@example +drawtext='fontfile=FreeSans.ttf:text=%@{localtime:%a %b %d %Y@}' +@end example + +@item +Shwo text fading in and out (appearing/disappearing): +@example +#!/bin/sh +DS=1.0 # display start +DE=10.0 # display end +FID=1.5 # fade in duration +FOD=5 # fade out duration +ffplay -f lavfi "color,drawtext=text=TEST:fontsize=50:fontfile=FreeSerif.ttf:fontcolor_expr=ff0000%@{eif\\\\: clip(255*(1*between(t\\, $DS + $FID\\, $DE - $FOD) + ((t - $DS)/$FID)*between(t\\, $DS\\, $DS + $FID) + (-(t - $DE)/$FOD)*between(t\\, $DE - $FOD\\, $DE) )\\, 0\\, 255) \\\\: x\\\\: 2 @}" +@end example + +@end itemize + For more information about libfreetype, check: @url{http://www.freetype.org/}. +For more information about fontconfig, check: +@url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}. + +For more information about libfribidi, check: +@url{http://fribidi.org/}. + +@section edgedetect + +Detect and draw edges. The filter uses the Canny Edge Detection algorithm. + +The filter accepts the following options: + +@table @option +@item low +@item high +Set low and high threshold values used by the Canny thresholding +algorithm. + +The high threshold selects the "strong" edge pixels, which are then +connected through 8-connectivity with the "weak" edge pixels selected +by the low threshold. + +@var{low} and @var{high} threshold values must be chosen in the range +[0,1], and @var{low} should be lesser or equal to @var{high}. + +Default value for @var{low} is @code{20/255}, and default value for @var{high} +is @code{50/255}. + +@item mode +Define the drawing mode. + +@table @samp +@item wires +Draw white/gray wires on black background. + +@item colormix +Mix the colors to create a paint/cartoon effect. +@end table + +Default value is @var{wires}. +@end table + +@subsection Examples + +@itemize +@item +Standard edge detection with custom values for the hysteresis thresholding: +@example +edgedetect=low=0.1:high=0.4 +@end example + +@item +Painting effect without thresholding: +@example +edgedetect=mode=colormix:high=0 +@end example +@end itemize + +@section extractplanes + +Extract color channel components from input video stream into +separate grayscale video streams. + +The filter accepts the following option: + +@table @option +@item planes +Set plane(s) to extract. + +Available values for planes are: +@table @samp +@item y +@item u +@item v +@item a +@item r +@item g +@item b +@end table + +Choosing planes not available in the input will result in an error. +That means you cannot select @code{r}, @code{g}, @code{b} planes +with @code{y}, @code{u}, @code{v} planes at same time. +@end table + +@subsection Examples + +@itemize +@item +Extract luma, u and v color channel component from input video frame +into 3 grayscale outputs: +@example +ffmpeg -i video.avi -filter_complex 'extractplanes=y+u+v[y][u][v]' -map '[y]' y.avi -map '[u]' u.avi -map '[v]' v.avi +@end example +@end itemize + +@section elbg + +Apply a posterize effect using the ELBG (Enhanced LBG) algorithm. + +For each input image, the filter will compute the optimal mapping from +the input to the output given the codebook length, that is the number +of distinct output colors. + +This filter accepts the following options. + +@table @option +@item codebook_length, l +Set codebook length. The value must be a positive integer, and +represents the number of distinct output colors. Default value is 256. + +@item nb_steps, n +Set the maximum number of iterations to apply for computing the optimal +mapping. The higher the value the better the result and the higher the +computation time. Default value is 1. + +@item seed, s +Set a random seed, must be an integer included between 0 and +UINT32_MAX. If not specified, or if explicitly set to -1, the filter +will try to use a good random seed on a best effort basis. +@end table + @section fade Apply a fade-in/out effect to the input video. @@ -1310,34 +4169,424 @@ Apply a fade-in/out effect to the input video. It accepts the following parameters: @table @option - -@item type +@item type, t The effect type can be either "in" for a fade-in, or "out" for a fade-out effect. +Default is @code{in}. -@item start_frame -The number of the frame to start applying the fade effect at. +@item start_frame, s +Specify the number of the frame to start applying the fade +effect at. Default is 0. -@item nb_frames +@item nb_frames, n The number of frames that the fade effect lasts. 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. - +At the end of the fade-out transition, the output video will be filled with the +selected @option{color}. +Default is 25. + +@item alpha +If set to 1, fade only alpha channel, if one exists on the input. +Default value is 0. + +@item start_time, st +Specify the timestamp (in seconds) of the frame to start to apply the fade +effect. If both start_frame and start_time are specified, the fade will start at +whichever comes last. Default is 0. + +@item duration, d +The number of seconds 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 filled with the +selected @option{color}. +If both duration and nb_frames are specified, duration is used. Default is 0. + +@item color, c +Specify the color of the fade. Default is "black". @end table -Some examples: +@subsection Examples + +@itemize +@item +Fade in the first 30 frames of video: @example -# Fade in the first 30 frames of video -fade=type=in:nb_frames=30 +fade=in:0:30 +@end example + +The command above is equivalent to: +@example +fade=t=in:s=0:n=30 +@end example -# Fade out the last 45 frames of a 200-frame video +@item +Fade out the last 45 frames of a 200-frame video: +@example +fade=out:155:45 fade=type=out:start_frame=155:nb_frames=45 +@end example + +@item +Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video: +@example +fade=in:0:25, fade=out:975:25 +@end example + +@item +Make the first 5 frames yellow, then fade in from frame 5-24: +@example +fade=in:5:20:color=yellow +@end example -# Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video -fade=type=in:start_frame=0:nb_frames=25, fade=type=out:start_frame=975:nb_frames=25 +@item +Fade in alpha over first 25 frames of video: +@example +fade=in:0:25:alpha=1 +@end example -# Make the first 5 frames black, then fade in from frame 5-24 -fade=type=in:start_frame=5:nb_frames=20 +@item +Make the first 5.5 seconds black, then fade in for 0.5 seconds: +@example +fade=t=in:st=5.5:d=0.5 +@end example + +@end itemize + +@section field + +Extract a single field from an interlaced image using stride +arithmetic to avoid wasting CPU time. The output frames are marked as +non-interlaced. + +The filter accepts the following options: + +@table @option +@item type +Specify whether to extract the top (if the value is @code{0} or +@code{top}) or the bottom field (if the value is @code{1} or +@code{bottom}). +@end table + +@section fieldmatch + +Field matching filter for inverse telecine. It is meant to reconstruct the +progressive frames from a telecined stream. The filter does not drop duplicated +frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be +followed by a decimation filter such as @ref{decimate} in the filtergraph. + +The separation of the field matching and the decimation is notably motivated by +the possibility of inserting a de-interlacing filter fallback between the two. +If the source has mixed telecined and real interlaced content, +@code{fieldmatch} will not be able to match fields for the interlaced parts. +But these remaining combed frames will be marked as interlaced, and thus can be +de-interlaced by a later filter such as @ref{yadif} before decimation. + +In addition to the various configuration options, @code{fieldmatch} can take an +optional second stream, activated through the @option{ppsrc} option. If +enabled, the frames reconstruction will be based on the fields and frames from +this second stream. This allows the first input to be pre-processed in order to +help the various algorithms of the filter, while keeping the output lossless +(assuming the fields are matched properly). Typically, a field-aware denoiser, +or brightness/contrast adjustments can help. + +Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project) +and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from +which @code{fieldmatch} is based on. While the semantic and usage are very +close, some behaviour and options names can differ. + +The filter accepts the following options: + +@table @option +@item order +Specify the assumed field order of the input stream. Available values are: + +@table @samp +@item auto +Auto detect parity (use FFmpeg's internal parity value). +@item bff +Assume bottom field first. +@item tff +Assume top field first. +@end table + +Note that it is sometimes recommended not to trust the parity announced by the +stream. + +Default value is @var{auto}. + +@item mode +Set the matching mode or strategy to use. @option{pc} mode is the safest in the +sense that it won't risk creating jerkiness due to duplicate frames when +possible, but if there are bad edits or blended fields it will end up +outputting combed frames when a good match might actually exist. On the other +hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness, +but will almost always find a good frame if there is one. The other values are +all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking +jerkiness and creating duplicate frames versus finding good matches in sections +with bad edits, orphaned fields, blended fields, etc. + +More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section. + +Available values are: + +@table @samp +@item pc +2-way matching (p/c) +@item pc_n +2-way matching, and trying 3rd match if still combed (p/c + n) +@item pc_u +2-way matching, and trying 3rd match (same order) if still combed (p/c + u) +@item pc_n_ub +2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if +still combed (p/c + n + u/b) +@item pcn +3-way matching (p/c/n) +@item pcn_ub +3-way matching, and trying 4th/5th matches if all 3 of the original matches are +detected as combed (p/c/n + u/b) +@end table + +The parenthesis at the end indicate the matches that would be used for that +mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or +@var{top}). + +In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is +the slowest. + +Default value is @var{pc_n}. + +@item ppsrc +Mark the main input stream as a pre-processed input, and enable the secondary +input stream as the clean source to pick the fields from. See the filter +introduction for more details. It is similar to the @option{clip2} feature from +VFM/TFM. + +Default value is @code{0} (disabled). + +@item field +Set the field to match from. It is recommended to set this to the same value as +@option{order} unless you experience matching failures with that setting. In +certain circumstances changing the field that is used to match from can have a +large impact on matching performance. Available values are: + +@table @samp +@item auto +Automatic (same value as @option{order}). +@item bottom +Match from the bottom field. +@item top +Match from the top field. +@end table + +Default value is @var{auto}. + +@item mchroma +Set whether or not chroma is included during the match comparisons. In most +cases it is recommended to leave this enabled. You should set this to @code{0} +only if your clip has bad chroma problems such as heavy rainbowing or other +artifacts. Setting this to @code{0} could also be used to speed things up at +the cost of some accuracy. + +Default value is @code{1}. + +@item y0 +@item y1 +These define an exclusion band which excludes the lines between @option{y0} and +@option{y1} from being included in the field matching decision. An exclusion +band can be used to ignore subtitles, a logo, or other things that may +interfere with the matching. @option{y0} sets the starting scan line and +@option{y1} sets the ending line; all lines in between @option{y0} and +@option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting +@option{y0} and @option{y1} to the same value will disable the feature. +@option{y0} and @option{y1} defaults to @code{0}. + +@item scthresh +Set the scene change detection threshold as a percentage of maximum change on +the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change +detection is only relevant in case @option{combmatch}=@var{sc}. The range for +@option{scthresh} is @code{[0.0, 100.0]}. + +Default value is @code{12.0}. + +@item combmatch +When @option{combatch} is not @var{none}, @code{fieldmatch} will take into +account the combed scores of matches when deciding what match to use as the +final match. Available values are: + +@table @samp +@item none +No final matching based on combed scores. +@item sc +Combed scores are only used when a scene change is detected. +@item full +Use combed scores all the time. +@end table + +Default is @var{sc}. + +@item combdbg +Force @code{fieldmatch} to calculate the combed metrics for certain matches and +print them. This setting is known as @option{micout} in TFM/VFM vocabulary. +Available values are: + +@table @samp +@item none +No forced calculation. +@item pcn +Force p/c/n calculations. +@item pcnub +Force p/c/n/u/b calculations. +@end table + +Default value is @var{none}. + +@item cthresh +This is the area combing threshold used for combed frame detection. This +essentially controls how "strong" or "visible" combing must be to be detected. +Larger values mean combing must be more visible and smaller values mean combing +can be less visible or strong and still be detected. Valid settings are from +@code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will +be detected as combed). This is basically a pixel difference value. A good +range is @code{[8, 12]}. + +Default value is @code{9}. + +@item chroma +Sets whether or not chroma is considered in the combed frame decision. Only +disable this if your source has chroma problems (rainbowing, etc.) that are +causing problems for the combed frame detection with chroma enabled. Actually, +using @option{chroma}=@var{0} is usually more reliable, except for the case +where there is chroma only combing in the source. + +Default value is @code{0}. + +@item blockx +@item blocky +Respectively set the x-axis and y-axis size of the window used during combed +frame detection. This has to do with the size of the area in which +@option{combpel} pixels are required to be detected as combed for a frame to be +declared combed. See the @option{combpel} parameter description for more info. +Possible values are any number that is a power of 2 starting at 4 and going up +to 512. + +Default value is @code{16}. + +@item combpel +The number of combed pixels inside any of the @option{blocky} by +@option{blockx} size blocks on the frame for the frame to be detected as +combed. While @option{cthresh} controls how "visible" the combing must be, this +setting controls "how much" combing there must be in any localized area (a +window defined by the @option{blockx} and @option{blocky} settings) on the +frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at +which point no frames will ever be detected as combed). This setting is known +as @option{MI} in TFM/VFM vocabulary. + +Default value is @code{80}. +@end table + +@anchor{p/c/n/u/b meaning} +@subsection p/c/n/u/b meaning + +@subsubsection p/c/n + +We assume the following telecined stream: + +@example +Top fields: 1 2 2 3 4 +Bottom fields: 1 2 3 4 4 +@end example + +The numbers correspond to the progressive frame the fields relate to. Here, the +first two frames are progressive, the 3rd and 4th are combed, and so on. + +When @code{fieldmatch} is configured to run a matching from bottom +(@option{field}=@var{bottom}) this is how this input stream get transformed: + +@example +Input stream: + T 1 2 2 3 4 + B 1 2 3 4 4 <-- matching reference + +Matches: c c n n c + +Output stream: + T 1 2 3 4 4 + B 1 2 3 4 4 +@end example + +As a result of the field matching, we can see that some frames get duplicated. +To perform a complete inverse telecine, you need to rely on a decimation filter +after this operation. See for instance the @ref{decimate} filter. + +The same operation now matching from top fields (@option{field}=@var{top}) +looks like this: + +@example +Input stream: + T 1 2 2 3 4 <-- matching reference + B 1 2 3 4 4 + +Matches: c c p p c + +Output stream: + T 1 2 2 3 4 + B 1 2 2 3 4 +@end example + +In these examples, we can see what @var{p}, @var{c} and @var{n} mean; +basically, they refer to the frame and field of the opposite parity: + +@itemize +@item @var{p} matches the field of the opposite parity in the previous frame +@item @var{c} matches the field of the opposite parity in the current frame +@item @var{n} matches the field of the opposite parity in the next frame +@end itemize + +@subsubsection u/b + +The @var{u} and @var{b} matching are a bit special in the sense that they match +from the opposite parity flag. In the following examples, we assume that we are +currently matching the 2nd frame (Top:2, bottom:2). According to the match, a +'x' is placed above and below each matched fields. + +With bottom matching (@option{field}=@var{bottom}): +@example +Match: c p n b u + + x x x x x + Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 + Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 + x x x x x + +Output frames: + 2 1 2 2 2 + 2 2 2 1 3 +@end example + +With top matching (@option{field}=@var{top}): +@example +Match: c p n b u + + x x x x x + Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 + Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 + x x x x x + +Output frames: + 2 2 2 1 2 + 2 1 3 2 2 +@end example + +@subsection Examples + +Simple IVTC of a top field first telecined stream: +@example +fieldmatch=order=tff:combmatch=none, decimate +@end example + +Advanced IVTC, with fallback on @ref{yadif} for still combed frames: +@example +fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate @end example @section fieldorder @@ -1353,7 +4602,7 @@ The output field order. Valid values are @var{tff} for top field first or @var{b for bottom field first. @end table -The default value is "tff". +The default value is @samp{tff}. The transformation is done by shifting the picture content up or down by one line, and filling the remaining line with appropriate picture content. @@ -1368,7 +4617,7 @@ which is bottom field first. For example: @example -./avconv -i in.vob -vf "fieldorder=order=bff" out.dv +ffmpeg -i in.vob -vf "fieldorder=bff" out.dv @end example @section fifo @@ -1380,6 +4629,7 @@ framework. It does not take parameters. +@anchor{format} @section format Convert the input video to one of the specified pixel formats. @@ -1395,26 +4645,50 @@ A '|'-separated list of pixel format names, such as @end table -Some examples: +@subsection Examples + +@itemize +@item +Convert the input video to the @var{yuv420p} format @example -# Convert the input video to the "yuv420p" format format=pix_fmts=yuv420p +@end example -# Convert the input video to any of the formats in the list +Convert the input video to any of the formats in the list +@example format=pix_fmts=yuv420p|yuv444p|yuv410p @end example +@end itemize @anchor{fps} @section fps -Convert the video to specified constant framerate by duplicating or dropping +Convert the video to specified constant frame rate by duplicating or dropping frames as necessary. It accepts the following parameters: @table @option @item fps -The desired output framerate. +The desired output frame rate. The default is @code{25}. + +@item round +Rounding method. + +Possible values are: +@table @option +@item zero +zero round towards 0 +@item inf +round away from 0 +@item down +round towards -infinity +@item up +round towards +infinity +@item near +round to nearest +@end table +The default is @code{near}. @item start_time Assume the first PTS should be the given value, in seconds. This allows for @@ -1426,6 +4700,27 @@ frames with a negative PTS. @end table +Alternatively, the options can be specified as a flat string: +@var{fps}[:@var{round}]. + +See also the @ref{setpts} filter. + +@subsection Examples + +@itemize +@item +A typical usage in order to set the fps to 25: +@example +fps=fps=25 +@end example + +@item +Sets the fps to 24, using abbreviation and rounding method to round to nearest: +@example +fps=fps=film:round=near +@end example +@end itemize + @section framepack Pack two different video streams into a stereoscopic video, setting proper @@ -1465,19 +4760,30 @@ Some examples: @example # Convert left and right views into a frame-sequential video -avconv -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT +ffmpeg -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 +ffmpeg -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 +@section framestep + +Select one frame every N-th frame. + +This filter accepts the following option: +@table @option +@item step +Select frame after every @code{step} frames. +Allowed values are positive integers higher than 0. Default value is @code{1}. +@end table + @anchor{frei0r} @section frei0r Apply a frei0r effect to the input video. To enable the compilation of this filter, you need to install the frei0r -header and configure Libav with --enable-frei0r. +header and configure FFmpeg with @code{--enable-frei0r}. It accepts the following parameters: @@ -1499,35 +4805,167 @@ A '|'-separated list of parameters to pass to the frei0r effect. A frei0r effect parameter can be a boolean (its value is either "y" or "n"), a double, a color (specified as @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point -numbers between 0.0 and 1.0, inclusive) or by an @code{av_parse_color()} color -description), a position (specified as @var{X}/@var{Y}, where +numbers between 0.0 and 1.0, inclusive) or by a color description specified in the "Color" +section in the ffmpeg-utils manual), a position (specified as @var{X}/@var{Y}, where @var{X} and @var{Y} are floating point numbers) and/or a string. The number and types of parameters depend on the loaded effect. If an effect parameter is not specified, the default value is set. -Some examples: +@subsection Examples + +@itemize +@item +Apply the distort0r effect, setting the first two double parameters: @example -# Apply the distort0r effect, setting the first two double parameters frei0r=filter_name=distort0r:filter_params=0.5|0.01 +@end example -# Apply the colordistance effect, taking a color as the first parameter +@item +Apply the colordistance effect, taking a color as the first parameter: +@example frei0r=colordistance:0.2/0.3/0.4 frei0r=colordistance:violet frei0r=colordistance:0x112233 +@end example -# Apply the perspective effect, specifying the top left and top right -# image positions +@item +Apply the perspective effect, specifying 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 geq + +The filter accepts the following options: + +@table @option +@item lum_expr, lum +Set the luminance expression. +@item cb_expr, cb +Set the chrominance blue expression. +@item cr_expr, cr +Set the chrominance red expression. +@item alpha_expr, a +Set the alpha expression. +@item red_expr, r +Set the red expression. +@item green_expr, g +Set the green expression. +@item blue_expr, b +Set the blue expression. +@end table + +The colorspace is selected according to the specified options. If one +of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr} +options is specified, the filter will automatically select a YCbCr +colorspace. If one of the @option{red_expr}, @option{green_expr}, or +@option{blue_expr} options is specified, it will select an RGB +colorspace. + +If one of the chrominance expression is not defined, it falls back on the other +one. If no alpha expression is specified it will evaluate to opaque value. +If none of chrominance expressions are specified, they will evaluate +to the luminance expression. + +The expressions can use the following variables and functions: + +@table @option +@item N +The sequential number of the filtered frame, starting from @code{0}. + +@item X +@item Y +The coordinates of the current sample. + +@item W +@item H +The width and height of the image. + +@item SW +@item SH +Width and height scale depending on the currently filtered plane. It is the +ratio between the corresponding luma plane number of pixels and the current +plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and +@code{0.5,0.5} for chroma planes. + +@item T +Time of the current frame, expressed in seconds. + +@item p(x, y) +Return the value of the pixel at location (@var{x},@var{y}) of the current +plane. + +@item lum(x, y) +Return the value of the pixel at location (@var{x},@var{y}) of the luminance +plane. + +@item cb(x, y) +Return the value of the pixel at location (@var{x},@var{y}) of the +blue-difference chroma plane. Return 0 if there is no such plane. + +@item cr(x, y) +Return the value of the pixel at location (@var{x},@var{y}) of the +red-difference chroma plane. Return 0 if there is no such plane. + +@item r(x, y) +@item g(x, y) +@item b(x, y) +Return the value of the pixel at location (@var{x},@var{y}) of the +red/green/blue component. Return 0 if there is no such component. + +@item alpha(x, y) +Return the value of the pixel at location (@var{x},@var{y}) of the alpha +plane. Return 0 if there is no such plane. +@end table + +For functions, if @var{x} and @var{y} are outside the area, the value will be +automatically clipped to the closer edge. + +@subsection Examples + +@itemize +@item +Flip the image horizontally: +@example +geq=p(W-X\,Y) +@end example + +@item +Generate a bidimensional sine wave, with angle @code{PI/3} and a +wavelength of 100 pixels: +@example +geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128 +@end example + +@item +Generate a fancy enigmatic moving light: +@example +nullsrc=s=256x256,geq=random(1)/hypot(X-cos(N*0.07)*W/2-W/2\,Y-sin(N*0.09)*H/2-H/2)^2*1000000*sin(N*0.02):128:128 +@end example + +@item +Generate a quick emboss effect: +@example +format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2' +@end example + +@item +Modify RGB components depending on pixel position: +@example +geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)' +@end example +@end itemize @section gradfun Fix the banding artifacts that are sometimes introduced into nearly flat -regions by truncation to 8bit colordepth. +regions by truncation to 8bit color depth. Interpolate the gradients that should go where the bands are, and dither them. @@ -1553,23 +4991,264 @@ values will be clipped to the valid range. @end table +Alternatively, the options can be specified as a flat string: +@var{strength}[:@var{radius}] + +@subsection Examples + +@itemize +@item +Apply the filter with a @code{3.5} strength and radius of @code{8}: +@example +gradfun=3.5:8 +@end example + +@item +Specify radius, omitting the strength (which will fall-back to the default +value): +@example +gradfun=radius=8 +@end example + +@end itemize + +@anchor{haldclut} +@section haldclut + +Apply a Hald CLUT to a video stream. + +First input is the video stream to process, and second one is the Hald CLUT. +The Hald CLUT input can be a simple picture or a complete video stream. + +The filter accepts the following options: + +@table @option +@item shortest +Force termination when the shortest input terminates. Default is @code{0}. +@item repeatlast +Continue applying the last CLUT after the end of the stream. A value of +@code{0} disable the filter after the last frame of the CLUT is reached. +Default is @code{1}. +@end table + +@code{haldclut} also has the same interpolation options as @ref{lut3d} (both +filters share the same internals). + +More information about the Hald CLUT can be found on Eskil Steenberg's website +(Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}. + +@subsection Workflow examples + +@subsubsection Hald CLUT video stream + +Generate an identity Hald CLUT stream altered with various effects: +@example +ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "hue=H=2*PI*t:s=sin(2*PI*t)+1, curves=cross_process" -t 10 -c:v ffv1 clut.nut +@end example + +Note: make sure you use a lossless codec. + +Then use it with @code{haldclut} to apply it on some random stream: +@example +ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv +@end example + +The Hald CLUT will be applied to the 10 first seconds (duration of +@file{clut.nut}), then the latest picture of that CLUT stream will be applied +to the remaining frames of the @code{mandelbrot} stream. + +@subsubsection Hald CLUT with preview + +A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by +@code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the +biggest possible square starting at the top left of the picture. The remaining +padding pixels (bottom or right) will be ignored. This area can be used to add +a preview of the Hald CLUT. + +Typically, the following generated Hald CLUT will be supported by the +@code{haldclut} filter: + @example -# Default parameters -gradfun=strength=1.2:radius=16 +ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf " + pad=iw+320 [padded_clut]; + smptebars=s=320x256, split [a][b]; + [padded_clut][a] overlay=W-320:h, curves=color_negative [main]; + [main][b] overlay=W-320" -frames:v 1 clut.png +@end example -# Omitting the radius -gradfun=1.2 +It contains the original and a preview of the effect of the CLUT: SMPTE color +bars are displayed on the right-top, and below the same color bars processed by +the color changes. + +Then, the effect of this Hald CLUT can be visualized with: +@example +ffplay input.mkv -vf "movie=clut.png, [in] haldclut" @end example @section hflip Flip the input video horizontally. -For example, to horizontally flip the input video with @command{avconv}: +For example, to horizontally flip the input video with @command{ffmpeg}: @example -avconv -i in.avi -vf "hflip" out.avi +ffmpeg -i in.avi -vf "hflip" out.avi @end example +@section histeq +This filter applies a global color histogram equalization on a +per-frame basis. + +It can be used to correct video that has a compressed range of pixel +intensities. The filter redistributes the pixel intensities to +equalize their distribution across the intensity range. It may be +viewed as an "automatically adjusting contrast filter". This filter is +useful only for correcting degraded or poorly captured source +video. + +The filter accepts the following options: + +@table @option +@item strength +Determine the amount of equalization to be applied. As the strength +is reduced, the distribution of pixel intensities more-and-more +approaches that of the input frame. The value must be a float number +in the range [0,1] and defaults to 0.200. + +@item intensity +Set the maximum intensity that can generated and scale the output +values appropriately. The strength should be set as desired and then +the intensity can be limited if needed to avoid washing-out. The value +must be a float number in the range [0,1] and defaults to 0.210. + +@item antibanding +Set the antibanding level. If enabled the filter will randomly vary +the luminance of output pixels by a small amount to avoid banding of +the histogram. Possible values are @code{none}, @code{weak} or +@code{strong}. It defaults to @code{none}. +@end table + +@section histogram + +Compute and draw a color distribution histogram for the input video. + +The computed histogram is a representation of the color component +distribution in an image. + +The filter accepts the following options: + +@table @option +@item mode +Set histogram mode. + +It accepts the following values: +@table @samp +@item levels +Standard histogram that displays the color components distribution in an +image. Displays color graph for each color component. Shows distribution of +the Y, U, V, A or R, G, B components, depending on input format, in the +current frame. Below each graph a color component scale meter is shown. + +@item color +Displays chroma values (U/V color placement) in a two dimensional +graph (which is called a vectorscope). The brighter a pixel in the +vectorscope, the more pixels of the input frame correspond to that pixel +(i.e., more pixels have this chroma value). The V component is displayed on +the horizontal (X) axis, with the leftmost side being V = 0 and the rightmost +side being V = 255. The U component is displayed on the vertical (Y) axis, +with the top representing U = 0 and the bottom representing U = 255. + +The position of a white pixel in the graph corresponds to the chroma value of +a pixel of the input clip. The graph can therefore be used to read the hue +(color flavor) and the saturation (the dominance of the hue in the color). As +the hue of a color changes, it moves around the square. At the center of the +square the saturation is zero, which means that the corresponding pixel has no +color. If the amount of a specific color is increased (while leaving the other +colors unchanged) the saturation increases, and the indicator moves towards +the edge of the square. + +@item color2 +Chroma values in vectorscope, similar as @code{color} but actual chroma values +are displayed. + +@item waveform +Per row/column color component graph. In row mode, the graph on the left side +represents color component value 0 and the right side represents value = 255. +In column mode, the top side represents color component value = 0 and bottom +side represents value = 255. +@end table +Default value is @code{levels}. + +@item level_height +Set height of level in @code{levels}. Default value is @code{200}. +Allowed range is [50, 2048]. + +@item scale_height +Set height of color scale in @code{levels}. Default value is @code{12}. +Allowed range is [0, 40]. + +@item step +Set step for @code{waveform} mode. Smaller values are useful to find out how +many values of the same luminance are distributed across input rows/columns. +Default value is @code{10}. Allowed range is [1, 255]. + +@item waveform_mode +Set mode for @code{waveform}. Can be either @code{row}, or @code{column}. +Default is @code{row}. + +@item waveform_mirror +Set mirroring mode for @code{waveform}. @code{0} means unmirrored, @code{1} +means mirrored. In mirrored mode, higher values will be represented on the left +side for @code{row} mode and at the top for @code{column} mode. Default is +@code{0} (unmirrored). + +@item display_mode +Set display mode for @code{waveform} and @code{levels}. +It accepts the following values: +@table @samp +@item parade +Display separate graph for the color components side by side in +@code{row} waveform mode or one below the other in @code{column} waveform mode +for @code{waveform} histogram mode. For @code{levels} histogram mode, +per color component graphs are placed below each other. + +Using this display mode in @code{waveform} histogram mode makes it easy to +spot color casts in the highlights and shadows of an image, by comparing the +contours of the top and the bottom graphs of each waveform. Since whites, +grays, and blacks are characterized by exactly equal amounts of red, green, +and blue, neutral areas of the picture should display three waveforms of +roughly equal width/height. If not, the correction is easy to perform by +making level adjustments the three waveforms. + +@item overlay +Presents information identical to that in the @code{parade}, except +that the graphs representing color components are superimposed directly +over one another. + +This display mode in @code{waveform} histogram mode makes it easier to spot +relative differences or similarities in overlapping areas of the color +components that are supposed to be identical, such as neutral whites, grays, +or blacks. +@end table +Default is @code{parade}. + +@item levels_mode +Set mode for @code{levels}. Can be either @code{linear}, or @code{logarithmic}. +Default is @code{linear}. +@end table + +@subsection Examples + +@itemize + +@item +Calculate and draw histogram: +@example +ffplay -i input -vf histogram +@end example + +@end itemize + +@anchor{hqdn3d} @section hqdn3d This is a high precision/quality 3d denoise filter. It aims to reduce @@ -1596,6 +5275,181 @@ A floating point number which specifies chroma temporal strength. It defaults to @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}. @end table +@section hqx + +Apply a high-quality magnification filter designed for pixel art. This filter +was originally created by Maxim Stepin. + +It accepts the following option: + +@table @option +@item n +Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for +@code{hq3x} and @code{4} for @code{hq4x}. +Default is @code{3}. +@end table + +@section hue + +Modify the hue and/or the saturation of the input. + +It accepts the following parameters: + +@table @option +@item h +Specify the hue angle as a number of degrees. It accepts an expression, +and defaults to "0". + +@item s +Specify the saturation in the [-10,10] range. It accepts an expression and +defaults to "1". + +@item H +Specify the hue angle as a number of radians. It accepts an +expression, and defaults to "0". + +@item b +Specify the brightness in the [-10,10] range. It accepts an expression and +defaults to "0". +@end table + +@option{h} and @option{H} are mutually exclusive, and can't be +specified at the same time. + +The @option{b}, @option{h}, @option{H} and @option{s} option values are +expressions containing the following constants: + +@table @option +@item n +frame count of the input frame starting from 0 + +@item pts +presentation timestamp of the input frame expressed in time base units + +@item r +frame rate of the input video, NAN if the input frame rate is unknown + +@item t +timestamp expressed in seconds, NAN if the input timestamp is unknown + +@item tb +time base of the input video +@end table + +@subsection Examples + +@itemize +@item +Set the hue to 90 degrees and the saturation to 1.0: +@example +hue=h=90:s=1 +@end example + +@item +Same command but expressing the hue in radians: +@example +hue=H=PI/2:s=1 +@end example + +@item +Rotate hue and make the saturation swing between 0 +and 2 over a period of 1 second: +@example +hue="H=2*PI*t: s=sin(2*PI*t)+1" +@end example + +@item +Apply a 3 seconds saturation fade-in effect starting at 0: +@example +hue="s=min(t/3\,1)" +@end example + +The general fade-in expression can be written as: +@example +hue="s=min(0\, max((t-START)/DURATION\, 1))" +@end example + +@item +Apply a 3 seconds saturation fade-out effect starting at 5 seconds: +@example +hue="s=max(0\, min(1\, (8-t)/3))" +@end example + +The general fade-out expression can be written as: +@example +hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))" +@end example + +@end itemize + +@subsection Commands + +This filter supports the following commands: +@table @option +@item b +@item s +@item h +@item H +Modify the hue and/or the saturation and/or brightness of the input video. +The command accepts the same syntax of the corresponding option. + +If the specified expression is not valid, it is kept at its current +value. +@end table + +@section idet + +Detect video interlacing type. + +This filter tries to detect if the input is interlaced or progressive, +top or bottom field first. + +The filter accepts the following options: + +@table @option +@item intl_thres +Set interlacing threshold. +@item prog_thres +Set progressive threshold. +@end table + +@section il + +Deinterleave or interleave fields. + +This filter allows one to process interlaced images fields without +deinterlacing them. Deinterleaving splits the input frame into 2 +fields (so called half pictures). Odd lines are moved to the top +half of the output image, even lines to the bottom half. +You can process (filter) them independently and then re-interleave them. + +The filter accepts the following options: + +@table @option +@item luma_mode, l +@item chroma_mode, c +@item alpha_mode, a +Available values for @var{luma_mode}, @var{chroma_mode} and +@var{alpha_mode} are: + +@table @samp +@item none +Do nothing. + +@item deinterleave, d +Deinterleave fields, placing one above the other. + +@item interleave, i +Interleave fields. Reverse the effect of deinterleaving. +@end table +Default value is @code{none}. + +@item luma_swap, ls +@item chroma_swap, cs +@item alpha_swap, as +Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}. +@end table + @section interlace Simple interlacing filter from progressive contents. This interleaves upper (or @@ -1626,6 +5480,95 @@ Enable (default) or disable the vertical lowpass filter to avoid twitter interlacing and reduce moire patterns. @end table +@section kerndeint + +Deinterlace input video by applying Donald Graft's adaptive kernel +deinterling. Work on interlaced parts of a video to produce +progressive frames. + +The description of the accepted parameters follows. + +@table @option +@item thresh +Set the threshold which affects the filter's tolerance when +determining if a pixel line must be processed. It must be an integer +in the range [0,255] and defaults to 10. A value of 0 will result in +applying the process on every pixels. + +@item map +Paint pixels exceeding the threshold value to white if set to 1. +Default is 0. + +@item order +Set the fields order. Swap fields if set to 1, leave fields alone if +0. Default is 0. + +@item sharp +Enable additional sharpening if set to 1. Default is 0. + +@item twoway +Enable twoway sharpening if set to 1. Default is 0. +@end table + +@subsection Examples + +@itemize +@item +Apply default values: +@example +kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0 +@end example + +@item +Enable additional sharpening: +@example +kerndeint=sharp=1 +@end example + +@item +Paint processed pixels in white: +@example +kerndeint=map=1 +@end example +@end itemize + +@anchor{lut3d} +@section lut3d + +Apply a 3D LUT to an input video. + +The filter accepts the following options: + +@table @option +@item file +Set the 3D LUT file name. + +Currently supported formats: +@table @samp +@item 3dl +AfterEffects +@item cube +Iridas +@item dat +DaVinci +@item m3d +Pandora +@end table +@item interp +Select interpolation mode. + +Available values are: + +@table @samp +@item nearest +Use values from the nearest defined point. +@item trilinear +Interpolate values using the 8 points defining a cube. +@item tetrahedral +Interpolate values using a tetrahedron. +@end table +@end table + @section lut, lutrgb, lutyuv Compute a look-up table for binding each pixel component input value @@ -1636,19 +5579,30 @@ to an RGB input video. These filters accept the following parameters: @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) - -@item @var{r} (red component) -@item @var{g} (green component) -@item @var{b} (blue component) -@item @var{a} (alpha component) +@item c0 +set first pixel component expression +@item c1 +set second pixel component expression +@item c2 +set third pixel component expression +@item c3 +set fourth pixel component expression, corresponds to the alpha component + +@item r +set red component expression +@item g +set green component expression +@item b +set blue component expression +@item a +alpha component expression -@item @var{y} (Y/luminance component) -@item @var{u} (U/Cb component) -@item @var{v} (V/Cr component) +@item y +set Y/luminance component expression +@item u +set U/Cb component expression +@item v +set V/Cr component expression @end table Each of them specifies the expression to use for computing the lookup table for @@ -1663,11 +5617,8 @@ The @var{lut} filter requires either YUV or RGB pixel formats in input, The expressions can contain the following constants and functions: @table @option -@item E, PI, PHI -These are approximated values for the mathematical constants e -(Euler's number), pi (Greek pi), and phi (the golden ratio). - -@item w, h +@item w +@item h The input width and height. @item val @@ -1701,35 +5652,253 @@ expression All expressions default to "val". -Some examples: +@subsection Examples + +@itemize +@item +Negate input video: @example -# Negate input video lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val" lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val" +@end example -# The above is the same as +The above is the same as: +@example lutrgb="r=negval:g=negval:b=negval" lutyuv="y=negval:u=negval:v=negval" +@end example -# Negate luminance -lutyuv=negval +@item +Negate luminance: +@example +lutyuv=y=negval +@end example -# Remove chroma components, turning the video into a graytone image +@item +Remove chroma components, turning the video into a graytone image: +@example lutyuv="u=128:v=128" +@end example -# Apply a luma burning effect +@item +Apply a luma burning effect: +@example lutyuv="y=2*val" +@end example -# Remove green and blue components +@item +Remove green and blue components: +@example lutrgb="g=0:b=0" +@end example -# Set a constant alpha channel value on input +@item +Set a constant alpha channel value on input: +@example format=rgba,lutrgb=a="maxval-minval/2" +@end example -# Correct luminance gamma by a factor of 0.5 +@item +Correct luminance gamma by a factor of 0.5: +@example lutyuv=y=gammaval(0.5) @end example +@item +Discard least significant bits of luma: +@example +lutyuv=y='bitand(val, 128+64+32)' +@end example +@end itemize + +@section mergeplanes + +Merge color channel components from several video streams. + +The filter accepts up to 4 input streams, and merge selected input +planes to the output video. + +This filter accepts the following options: +@table @option +@item mapping +Set input to output plane mapping. Default is @code{0}. + +The mappings is specified as a bitmap. It should be specified as a +hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the +mapping for the first plane of the output stream. 'A' sets the number of +the input stream to use (from 0 to 3), and 'a' the plane number of the +corresponding input to use (from 0 to 3). The rest of the mappings is +similar, 'Bb' describes the mapping for the output stream second +plane, 'Cc' describes the mapping for the output stream third plane and +'Dd' describes the mapping for the output stream fourth plane. + +@item format +Set output pixel format. Default is @code{yuva444p}. +@end table + +@subsection Examples + +@itemize +@item +Merge three gray video streams of same width and height into single video stream: +@example +[a0][a1][a2]mergeplanes=0x001020:yuv444p +@end example + +@item +Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream: +@example +[a0][a1]mergeplanes=0x00010210:yuva444p +@end example + +@item +Swap Y and A plane in yuva444p stream: +@example +format=yuva444p,mergeplanes=0x03010200:yuva444p +@end example + +@item +Swap U and V plane in yuv420p stream: +@example +format=yuv420p,mergeplanes=0x000201:yuv420p +@end example + +@item +Cast a rgb24 clip to yuv444p: +@example +format=rgb24,mergeplanes=0x000102:yuv444p +@end example +@end itemize + +@section mcdeint + +Apply motion-compensation deinterlacing. + +It needs one field per frame as input and must thus be used together +with yadif=1/3 or equivalent. + +This filter accepts the following options: +@table @option +@item mode +Set the deinterlacing mode. + +It accepts one of the following values: +@table @samp +@item fast +@item medium +@item slow +use iterative motion estimation +@item extra_slow +like @samp{slow}, but use multiple reference frames. +@end table +Default value is @samp{fast}. + +@item parity +Set the picture field parity assumed for the input video. It must be +one of the following values: + +@table @samp +@item 0, tff +assume top field first +@item 1, bff +assume bottom field first +@end table + +Default value is @samp{bff}. + +@item qp +Set per-block quantization parameter (QP) used by the internal +encoder. + +Higher values should result in a smoother motion vector field but less +optimal individual vectors. Default value is 1. +@end table + +@section mp + +Apply an MPlayer filter to the input video. + +This filter provides a wrapper around some of the filters of +MPlayer/MEncoder. + +This wrapper is considered experimental. Some of the wrapped filters +may not work properly and we may drop support for them, as they will +be implemented natively into FFmpeg. Thus you should avoid +depending on them when writing portable scripts. + +The filter accepts the parameters: +@var{filter_name}[:=]@var{filter_params} + +@var{filter_name} is the name of a supported MPlayer filter, +@var{filter_params} is a string containing the parameters accepted by +the named filter. + +The list of the currently supported filters follows: +@table @var +@item eq2 +@item eq +@item fspp +@item ilpack +@item pp7 +@item softpulldown +@item uspp +@end table + +The parameter syntax and behavior for the listed filters are the same +of the corresponding MPlayer filters. For detailed instructions check +the "VIDEO FILTERS" section in the MPlayer manual. + +@subsection Examples + +@itemize +@item +Adjust gamma, brightness, contrast: +@example +mp=eq2=1.0:2:0.5 +@end example +@end itemize + +See also mplayer(1), @url{http://www.mplayerhq.hu/}. + +@section mpdecimate + +Drop frames that do not differ greatly from the previous frame in +order to reduce frame rate. + +The main use of this filter is for very-low-bitrate encoding +(e.g. streaming over dialup modem), but it could in theory be used for +fixing movies that were inverse-telecined incorrectly. + +A description of the accepted options follows. + +@table @option +@item max +Set the maximum number of consecutive frames which can be dropped (if +positive), or the minimum interval between dropped frames (if +negative). If the value is 0, the frame is dropped unregarding the +number of previous sequentially dropped frames. + +Default value is 0. + +@item hi +@item lo +@item frac +Set the dropping threshold values. + +Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and +represent actual pixel value differences, so a threshold of 64 +corresponds to 1 unit of difference for each pixel, or the same spread +out differently over the block. + +A frame is a candidate for dropping if no 8x8 blocks differ by more +than a threshold of @option{hi}, and if no more than @option{frac} blocks (1 +meaning the whole image) differ by more than a threshold of @option{lo}. + +Default value for @option{hi} is 64*12, default value for @option{lo} is +64*5, and default value for @option{frac} is 0.33. +@end table + + @section negate Negate input video. @@ -1751,15 +5920,71 @@ apix_fmts=yuv420p|monow|rgb24". @end table -Some examples: +@subsection Examples + +@itemize +@item +Force libavfilter to use a format different from @var{yuv420p} for the +input to the vflip filter: @example -# Force libavfilter to use a format different from "yuv420p" for the -# input to the vflip filter noformat=pix_fmts=yuv420p,vflip +@end example -# Convert the input video to any of the formats not contained in the list +@item +Convert the input video to any of the formats not contained in the list: +@example noformat=yuv420p|yuv444p|yuv410p @end example +@end itemize + +@section noise + +Add noise on video input frame. + +The filter accepts the following options: + +@table @option +@item all_seed +@item c0_seed +@item c1_seed +@item c2_seed +@item c3_seed +Set noise seed for specific pixel component or all pixel components in case +of @var{all_seed}. Default value is @code{123457}. + +@item all_strength, alls +@item c0_strength, c0s +@item c1_strength, c1s +@item c2_strength, c2s +@item c3_strength, c3s +Set noise strength for specific pixel component or all pixel components in case +@var{all_strength}. Default value is @code{0}. Allowed range is [0, 100]. + +@item all_flags, allf +@item c0_flags, c0f +@item c1_flags, c1f +@item c2_flags, c2f +@item c3_flags, c3f +Set pixel component flags or set flags for all components if @var{all_flags}. +Available values for component flags are: +@table @samp +@item a +averaged temporal noise (smoother) +@item p +mix random noise with a (semi)regular pattern +@item t +temporal noise (noise pattern changes between frames) +@item u +uniform noise (gaussian otherwise) +@end table +@end table + +@subsection Examples + +Add temporal and uniform noise to input video: +@example +noise=alls=20:allf=t+u +@end example @section null @@ -1770,7 +5995,7 @@ Pass the video source unchanged to the output. Apply a video transform using libopencv. To enable this filter, install the libopencv library and headers and -configure Libav with --enable-libopencv. +configure FFmpeg with @code{--enable-libopencv}. It accepts the following parameters: @@ -1879,30 +6104,15 @@ video on which the second input is overlayed. It accepts the following parameters: -@table @option +A description of the accepted options follows. +@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 - -The parameters are expressions containing the following parameters: - -@table @option -@item main_w, main_h -The main input width and height. - -@item W, H -These are the same as @var{main_w} and @var{main_h}. - -@item overlay_w, overlay_h -The overlay input width and height. - -@item w, h -These are the same as @var{overlay_w} and @var{overlay_h}. +Set the expression for the x and y coordinates of the overlayed video +on the main video. Default value is "0" for both expressions. In case +the expression is invalid, it is set to a huge value (meaning that the +overlay will not be displayed within the output visible area). @item eof_action The action to take when EOF is encountered on the secondary input; it accepts @@ -1917,40 +6127,229 @@ End both streams. Pass the main input through. @end table +@item eval +Set when the expressions for @option{x}, and @option{y} are evaluated. + +It accepts the following values: +@table @samp +@item init +only evaluate expressions once during the filter initialization or +when a command is processed + +@item frame +evaluate expressions for each incoming frame +@end table + +Default value is @samp{frame}. + +@item shortest +If set to 1, force the output to terminate when the shortest input +terminates. Default value is 0. + +@item format +Set the format for the output video. + +It accepts the following values: +@table @samp +@item yuv420 +force YUV420 output + +@item yuv422 +force YUV422 output + +@item yuv444 +force YUV444 output + +@item rgb +force RGB output +@end table + +Default value is @samp{yuv420}. + +@item rgb @emph{(deprecated)} +If set to 1, force the filter to accept inputs in the RGB +color space. Default value is 0. This option is deprecated, use +@option{format} instead. + +@item repeatlast +If set to 1, force the filter to draw the last overlay frame over the +main input until the end of the stream. A value of 0 disables this +behavior. Default value is 1. @end table +The @option{x}, and @option{y} expressions can contain the following +parameters. + +@table @option +@item main_w, W +@item main_h, H +The main input width and height. + +@item overlay_w, w +@item overlay_h, h +The overlay input width and height. + +@item x +@item y +The computed values for @var{x} and @var{y}. They are evaluated for +each new frame. + +@item hsub +@item vsub +horizontal and vertical chroma subsample values of the output +format. For example for the pixel format "yuv422p" @var{hsub} is 2 and +@var{vsub} is 1. + +@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 +The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown. + +@end table + +Note that the @var{n}, @var{pos}, @var{t} variables are available only +when evaluation is done @emph{per frame}, and will evaluate to NAN +when @option{eval} is set to @samp{init}. + Be aware that frames are taken from each input video in timestamp -order, hence, if their initial timestamps differ, it is a a good idea +order, hence, if their initial timestamps differ, it is a good idea to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to have them begin in the same zero timestamp, as the example for the @var{movie} filter does. -Some examples: +You can chain together more overlays but you should test the +efficiency of such approach. + +@subsection Commands + +This filter supports the following commands: +@table @option +@item x +@item y +Modify the x and y of the overlay input. +The command accepts the same syntax of the corresponding option. + +If the specified expression is not valid, it is kept at its current +value. +@end table + +@subsection Examples + +@itemize +@item +Draw the overlay at 10 pixels from the bottom right corner of the main +video: +@example +overlay=main_w-overlay_w-10:main_h-overlay_h-10 +@end example + +Using named options the example above becomes: @example -# Draw the overlay at 10 pixels from the bottom right -# corner of the main video overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10 +@end example + +@item +Insert a transparent PNG logo in the bottom left corner of the input, +using the @command{ffmpeg} tool with the @code{-filter_complex} option: +@example +ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output +@end example -# Insert a transparent PNG logo in the bottom left corner of the input -avconv -i input -i logo -filter_complex 'overlay=x=10:y=main_h-overlay_h-10' output +@item +Insert 2 different transparent PNG logos (second logo on bottom +right corner) using the @command{ffmpeg} tool: +@example +ffmpeg -i input -i logo1 -i logo2 -filter_complex 'overlay=x=10:y=H-h-10,overlay=x=W-w-10:y=H-h-10' output +@end example + +@item +Add a transparent color layer on top of the main video; @code{WxH} +must specify the size of the main input to the overlay filter: +@example +color=color=red@@.3:size=WxH [over]; [in][over] overlay [out] +@end example + +@item +Play an original video and a filtered version (here with the deshake +filter) side by side using the @command{ffplay} tool: +@example +ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w' +@end example -# Insert 2 different transparent PNG logos (second logo on bottom -# right corner) -avconv -i input -i logo1 -i logo2 -filter_complex -'overlay=x=10:y=H-h-10,overlay=x=W-w-10:y=H-h-10' output +The above command is the same as: +@example +ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w' +@end example -# 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] +@item +Make a sliding overlay appearing from the left to the right top part of the +screen starting since time 2: +@example +overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0 +@end example -# 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 +@item +Compose output by putting two input videos side to side: +@example +ffmpeg -i left.avi -i right.avi -filter_complex " +nullsrc=size=200x100 [background]; +[0:v] setpts=PTS-STARTPTS, scale=100x100 [left]; +[1:v] setpts=PTS-STARTPTS, scale=100x100 [right]; +[background][left] overlay=shortest=1 [background+left]; +[background+left][right] overlay=shortest=1:x=100 [left+right] +" +@end example + +@item +Mask 10-20 seconds of a video by applying the delogo filter to a section +@example +ffmpeg -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 -approach is yet to be tested. +@item +Chain several overlays in cascade: +@example +nullsrc=s=200x200 [bg]; +testsrc=s=100x100, split=4 [in0][in1][in2][in3]; +[in0] lutrgb=r=0, [bg] overlay=0:0 [mid0]; +[in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1]; +[in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2]; +[in3] null, [mid2] overlay=100:100 [out0] +@end example + +@end itemize + +@section owdenoise + +Apply Overcomplete Wavelet denoiser. + +The filter accepts the following options: + +@table @option +@item depth +Set depth. + +Larger depth values will denoise lower frequency components more, but +slow down filtering. + +Must be an int in the range 8-16, default is @code{8}. + +@item luma_strength, ls +Set luma strength. + +Must be a double value in the range 0-1000, default is @code{1.0}. + +@item chroma_strength, cs +Set chroma strength. + +Must be a double value in the range 0-1000, default is @code{1.0}. +@end table @section pad @@ -1960,19 +6359,19 @@ provided @var{x}, @var{y} coordinates. It 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. +@item width, w +@item height, h +Specify an expression for 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 - +@item x +@item y Specify the offsets to place the input image at within the padded area, with respect to the top/left border of the output image. @@ -1982,71 +6381,210 @@ 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 an 0xRRGGBB[AA] sequence. +Specify the color of the padded area. For the syntax of this option, +check the "Color" section in the ffmpeg-utils manual. 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: +The value for the @var{width}, @var{height}, @var{x}, and @var{y} +options are expressions containing the following constants: @table @option -@item E, PI, PHI -These are approximated values for the mathematical constants e -(Euler's number), pi (Greek pi), and phi (the golden ratio). - -@item in_w, in_h +@item in_w +@item in_h The input video width and height. -@item iw, ih +@item iw +@item ih These are the same as @var{in_w} and @var{in_h}. -@item out_w, out_h +@item out_w +@item out_h The output width and height (the size of the padded area), as specified by the @var{width} and @var{height} expressions. -@item ow, oh +@item ow +@item oh These are the same as @var{out_w} and @var{out_h}. -@item x, y +@item x +@item y The x and y offsets as specified by the @var{x} and @var{y} expressions, or NAN if not yet specified. @item a -The input display aspect ratio, same as @var{iw} / @var{ih}. +same as @var{iw} / @var{ih} -@item hsub, vsub +@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 +@item vsub The horizontal and vertical chroma subsample values. For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. @end table -Some examples: +@subsection Examples +@itemize +@item +Add paddings with the color "violet" to the input video. The output video +size is 640x480, and the top-left corner of the input video is placed at +column 0, row 40 +@example +pad=640:480:0:40:violet +@end example + +The example above is equivalent to the following command: @example -# Add paddings with the color "violet" to the input video. The output video -# size is 640x480, and the top-left corner of the input video is placed at -# column 0, row 40 pad=width=640:height=480:x=0:y=40:color=violet +@end example -# Pad the input to get an output with dimensions increased by 3/2, -# and put the input video at the center of the padded area +@item +Pad the input to get an output with dimensions increased by 3/2, +and put the input video at the center of the padded area: +@example pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2" +@end example -# Pad the input to get a squared output with size equal to the maximum -# value between the input width and height, and put the input video at -# the center of the padded area +@item +Pad the input to get a squared output with size equal to the maximum +value between the input width and height, and put the input video at +the center of the padded area: +@example pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2" +@end example -# Pad the input to get a final w/h ratio of 16:9 +@item +Pad the input to get a final w/h ratio of 16:9: +@example pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2" +@end example + +@item +In case of anamorphic video, in order to set the output display aspect +correctly, it is necessary to use @var{sar} in the expression, +according to the relation: +@example +(ih * X / ih) * sar = output_dar +X = output_dar / sar +@end example + +Thus the previous example needs to be modified to: +@example +pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2" +@end example -# Double the output size and put the input video in the bottom-right -# corner of the output padded area +@item +Double the output size and put the input video in the bottom-right +corner of the output padded area: +@example pad="2*iw:2*ih:ow-iw:oh-ih" @end example +@end itemize + +@section perspective + +Correct perspective of video not recorded perpendicular to the screen. + +A description of the accepted parameters follows. + +@table @option +@item x0 +@item y0 +@item x1 +@item y1 +@item x2 +@item y2 +@item x3 +@item y3 +Set coordinates expression for top left, top right, bottom left and bottom right corners. +Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged. + +The expressions can use the following variables: + +@table @option +@item W +@item H +the width and height of video frame. +@end table + +@item interpolation +Set interpolation for perspective correction. + +It accepts the following values: +@table @samp +@item linear +@item cubic +@end table + +Default value is @samp{linear}. +@end table + +@section phase + +Delay interlaced video by one field time so that the field order changes. + +The intended use is to fix PAL movies that have been captured with the +opposite field order to the film-to-video transfer. + +A description of the accepted parameters follows. + +@table @option +@item mode +Set phase mode. + +It accepts the following values: +@table @samp +@item t +Capture field order top-first, transfer bottom-first. +Filter will delay the bottom field. + +@item b +Capture field order bottom-first, transfer top-first. +Filter will delay the top field. + +@item p +Capture and transfer with the same field order. This mode only exists +for the documentation of the other options to refer to, but if you +actually select it, the filter will faithfully do nothing. + +@item a +Capture field order determined automatically by field flags, transfer +opposite. +Filter selects among @samp{t} and @samp{b} modes on a frame by frame +basis using field flags. If no field information is available, +then this works just like @samp{u}. + +@item u +Capture unknown or varying, transfer opposite. +Filter selects among @samp{t} and @samp{b} on a frame by frame basis by +analyzing the images and selecting the alternative that produces best +match between the fields. + +@item T +Capture top-first, transfer unknown or varying. +Filter selects among @samp{t} and @samp{p} using image analysis. + +@item B +Capture bottom-first, transfer unknown or varying. +Filter selects among @samp{b} and @samp{p} using image analysis. + +@item A +Capture determined by field flags, transfer unknown or varying. +Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and +image analysis. If no field information is available, then this works just +like @samp{U}. This is the default mode. + +@item U +Both capture and transfer unknown or varying. +Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only. +@end table +@end table @section pixdesctest @@ -2060,367 +6598,853 @@ format=monow, pixdesctest can be used to test the monowhite pixel format descriptor definition. -@anchor{scale} -@section scale +@section pp -Scale the input video and/or convert the image format. +Enable the specified chain of postprocessing subfilters using libpostproc. This +library should be automatically selected with a GPL build (@code{--enable-gpl}). +Subfilters must be separated by '/' and can be disabled by prepending a '-'. +Each subfilter and some options have a short and a long name that can be used +interchangeably, i.e. dr/dering are the same. -It accepts the following parameters: +The filters accept the following options: @table @option +@item subfilters +Set postprocessing subfilters string. +@end table -@item w -The output video width. +All subfilters share common options to determine their scope: -@item h -The output video height. +@table @option +@item a/autoq +Honor the quality commands for this subfilter. + +@item c/chrom +Do chrominance filtering, too (default). +@item y/nochrom +Do luminance filtering only (no chrominance). + +@item n/noluma +Do chrominance filtering only (no luminance). @end table -The parameters @var{w} and @var{h} are expressions containing -the following constants: +These options can be appended after the subfilter name, separated by a '|'. + +Available subfilters are: @table @option -@item E, PI, PHI -These are approximated values for the mathematical constants e -(Euler's number), pi (Greek pi), and phi (the golden ratio). +@item hb/hdeblock[|difference[|flatness]] +Horizontal deblocking filter +@table @option +@item difference +Difference factor where higher values mean more deblocking (default: @code{32}). +@item flatness +Flatness threshold where lower values mean more deblocking (default: @code{39}). +@end table -@item in_w, in_h -The input width and height. +@item vb/vdeblock[|difference[|flatness]] +Vertical deblocking filter +@table @option +@item difference +Difference factor where higher values mean more deblocking (default: @code{32}). +@item flatness +Flatness threshold where lower values mean more deblocking (default: @code{39}). +@end table -@item iw, ih -These are the same as @var{in_w} and @var{in_h}. +@item ha/hadeblock[|difference[|flatness]] +Accurate horizontal deblocking filter +@table @option +@item difference +Difference factor where higher values mean more deblocking (default: @code{32}). +@item flatness +Flatness threshold where lower values mean more deblocking (default: @code{39}). +@end table -@item out_w, out_h -The output (cropped) width and height. +@item va/vadeblock[|difference[|flatness]] +Accurate vertical deblocking filter +@table @option +@item difference +Difference factor where higher values mean more deblocking (default: @code{32}). +@item flatness +Flatness threshold where lower values mean more deblocking (default: @code{39}). +@end table +@end table -@item ow, oh -These are the same as @var{out_w} and @var{out_h}. +The horizontal and vertical deblocking filters share the difference and +flatness values so you cannot set different horizontal and vertical +thresholds. -@item a -This is the same as @var{iw} / @var{ih}. +@table @option +@item h1/x1hdeblock +Experimental horizontal deblocking filter -@item sar -input sample aspect ratio +@item v1/x1vdeblock +Experimental vertical deblocking filter -@item dar -The input display aspect ratio; it is the same as -(@var{iw} / @var{ih}) * @var{sar}. +@item dr/dering +Deringing filter -@item hsub, vsub -The horizontal and vertical chroma subsample values. For example, for the -pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. +@item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer +@table @option +@item threshold1 +larger -> stronger filtering +@item threshold2 +larger -> stronger filtering +@item threshold3 +larger -> stronger filtering @end table -If the input image format is different from the format requested by -the next filter, the scale filter will convert the input to the -requested format. +@item al/autolevels[:f/fullyrange], automatic brightness / contrast correction +@table @option +@item f/fullyrange +Stretch luminance to @code{0-255}. +@end table -If the value for @var{w} or @var{h} is 0, the respective input -size is used for the output. +@item lb/linblenddeint +Linear blend deinterlacing filter that deinterlaces the given block by +filtering all lines with a @code{(1 2 1)} filter. -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. +@item li/linipoldeint +Linear interpolating deinterlacing filter that deinterlaces the given block by +linearly interpolating every second line. -The default value of @var{w} and @var{h} is 0. +@item ci/cubicipoldeint +Cubic interpolating deinterlacing filter deinterlaces the given block by +cubically interpolating every second line. -Some examples: -@example -# Scale the input video to a size of 200x100 -scale=w=200:h=100 +@item md/mediandeint +Median deinterlacing filter that deinterlaces the given block by applying a +median filter to every second line. -# Scale the input to 2x -scale=w=2*iw:h=2*ih -# The above is the same as -scale=2*in_w:2*in_h +@item fd/ffmpegdeint +FFmpeg deinterlacing filter that deinterlaces the given block by filtering every +second line with a @code{(-1 4 2 4 -1)} filter. -# Scale the input to half the original size -scale=w=iw/2:h=ih/2 +@item l5/lowpass5 +Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given +block by filtering all lines with a @code{(-1 2 6 2 -1)} filter. -# Increase the width, and set the height to the same size -scale=3/2*iw:ow +@item fq/forceQuant[|quantizer] +Overrides the quantizer table from the input with the constant quantizer you +specify. +@table @option +@item quantizer +Quantizer to use +@end table -# Seek Greek harmony -scale=iw:1/PHI*iw -scale=ih*PHI:ih +@item de/default +Default pp filter combination (@code{hb|a,vb|a,dr|a}) -# Increase the height, and set the width to 3/2 of the height -scale=w=3/2*oh:h=3/5*ih +@item fa/fast +Fast pp filter combination (@code{h1|a,v1|a,dr|a}) -# Increase the size, making the size a multiple of the chroma -scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub" +@item ac +High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a}) +@end table -# Increase the width to a maximum of 500 pixels, -# keeping the same aspect ratio as the input -scale=w='min(500\, iw*3/2):h=-1' +@subsection Examples + +@itemize +@item +Apply horizontal and vertical deblocking, deringing and automatic +brightness/contrast: +@example +pp=hb/vb/dr/al @end example -@section select -Select frames to pass in output. +@item +Apply default filters without brightness/contrast correction: +@example +pp=de/-al +@end example -It accepts the following parameters: +@item +Apply default filters and temporal denoiser: +@example +pp=default/tmpnoise|1|2|3 +@end example -@table @option +@item +Apply deblocking on luminance only, and switch vertical deblocking on or off +automatically depending on available CPU time: +@example +pp=hb|y/vb|a +@end example +@end itemize -@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. +@section psnr -@end table +Obtain the average, maximum and minimum PSNR (Peak Signal to Noise +Ratio) between two input videos. -The expression can contain the following constants: +This filter takes in input two input videos, the first input is +considered the "main" source and is passed unchanged to the +output. The second input is used as a "reference" video for computing +the PSNR. + +Both video inputs must have the same resolution and pixel format for +this filter to work correctly. Also it assumes that both inputs +have the same number of frames, which are compared one by one. + +The obtained average PSNR is printed through the logging system. + +The filter stores the accumulated MSE (mean squared error) of each +frame, and at the end of the processing it is averaged across all frames +equally, and the following formula is applied to obtain the PSNR: + +@example +PSNR = 10*log10(MAX^2/MSE) +@end example + +Where MAX is the average of the maximum values of each component of the +image. + +The description of the accepted parameters follows. @table @option -@item E, PI, PHI -These are approximated values for the mathematical constants e -(Euler's number), pi (Greek pi), and phi (the golden ratio). +@item stats_file, f +If specified the filter will use the named file to save the PSNR of +each individual frame. +@end table + +The file printed if @var{stats_file} is selected, contains a sequence of +key/value pairs of the form @var{key}:@var{value} for each compared +couple of frames. +A description of each shown parameter follows: + +@table @option @item n -The (sequential) number of the filtered frame, starting from 0. +sequential number of the input frame, starting from 1 -@item selected_n -The (sequential) number of the selected frame, starting from 0. +@item mse_avg +Mean Square Error pixel-by-pixel average difference of the compared +frames, averaged over all the image components. -@item prev_selected_n -The sequential number of the last selected frame. It's NAN if undefined. +@item mse_y, mse_u, mse_v, mse_r, mse_g, mse_g, mse_a +Mean Square Error pixel-by-pixel average difference of the compared +frames for the component specified by the suffix. -@item TB -The timebase of the input timestamps. +@item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a +Peak Signal to Noise ratio of the compared frames for the component +specified by the suffix. +@end table -@item pts -The PTS (Presentation TimeStamp) of the filtered video frame, -expressed in @var{TB} units. It's NAN if undefined. +For example: +@example +movie=ref_movie.mpg, setpts=PTS-STARTPTS [main]; +[main][ref] psnr="stats_file=stats.log" [out] +@end example -@item t -The PTS of the filtered video frame, -expressed in seconds. It's NAN if undefined. +On this example the input file being processed is compared with the +reference file @file{ref_movie.mpg}. The PSNR of each individual frame +is stored in @file{stats.log}. -@item prev_pts -The PTS of the previously filtered video frame. It's NAN if undefined. +@anchor{pullup} +@section pullup -@item prev_selected_pts -The PTS of the last previously filtered video frame. It's NAN if undefined. +Pulldown reversal (inverse telecine) filter, capable of handling mixed +hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive +content. -@item prev_selected_t -The PTS of the last previously selected video frame. It's NAN if undefined. +The pullup filter is designed to take advantage of future context in making +its decisions. This filter is stateless in the sense that it does not lock +onto a pattern to follow, but it instead looks forward to the following +fields in order to identify matches and rebuild progressive frames. -@item start_pts -The PTS of the first video frame in the video. It's NAN if undefined. +To produce content with an even framerate, insert the fps filter after +pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps, +@code{fps=24} for 30fps and the (rare) telecined 25fps input. -@item start_t -The time of the first video frame in the video. It's NAN if undefined. +The filter accepts the following options: -@item pict_type -The type of the filtered frame. It can assume one of the following -values: @table @option -@item I -@item P -@item B -@item S -@item SI -@item SP -@item BI +@item jl +@item jr +@item jt +@item jb +These options set the amount of "junk" to ignore at the left, right, top, and +bottom of the image, respectively. Left and right are in units of 8 pixels, +while top and bottom are in units of 2 lines. +The default is 8 pixels on each side. + +@item sb +Set the strict breaks. Setting this option to 1 will reduce the chances of +filter generating an occasional mismatched frame, but it may also cause an +excessive number of frames to be dropped during high motion sequences. +Conversely, setting it to -1 will make filter match fields more easily. +This may help processing of video where there is slight blurring between +the fields, but may also cause there to be interlaced frames in the output. +Default value is @code{0}. + +@item mp +Set the metric plane to use. It accepts the following values: +@table @samp +@item l +Use luma plane. + +@item u +Use chroma blue plane. + +@item v +Use chroma red plane. @end table -@item interlace_type -The frame interlace type. It can assume one of the following values: +This option may be set to use chroma plane instead of the default luma plane +for doing filter's computations. This may improve accuracy on very clean +source material, but more likely will decrease accuracy, especially if there +is chroma noise (rainbow effect) or any grayscale video. +The main purpose of setting @option{mp} to a chroma plane is to reduce CPU +load and make pullup usable in realtime on slow machines. +@end table + +For best results (without duplicated frames in the output file) it is +necessary to change the output frame rate. For example, to inverse +telecine NTSC input: +@example +ffmpeg -i input -vf pullup -r 24000/1001 ... +@end example + +@section removelogo + +Suppress a TV station logo, using an image file to determine which +pixels comprise the logo. It works by filling in the pixels that +comprise the logo with neighboring pixels. + +The filter accepts the following options: + @table @option -@item PROGRESSIVE -The frame is progressive (not interlaced). -@item TOPFIRST -The frame is top-field-first. -@item BOTTOMFIRST -The frame is bottom-field-first. +@item filename, f +Set the filter bitmap file, which can be any image format supported by +libavformat. The width and height of the image file must match those of the +video stream being processed. @end table -@item key -This is 1 if the filtered frame is a key-frame, 0 otherwise. +Pixels in the provided bitmap image with a value of zero are not +considered part of the logo, non-zero pixels are considered part of +the logo. If you use white (255) for the logo and black (0) for the +rest, you will be safe. For making the filter bitmap, it is +recommended to take a screen capture of a black frame with the logo +visible, and then using a threshold filter followed by the erode +filter once or twice. + +If needed, little splotches can be fixed manually. Remember that if +logo pixels are not covered, the filter quality will be much +reduced. Marking too many pixels as part of the logo does not hurt as +much, but it will increase the amount of blurring needed to cover over +the image and will destroy more information than necessary, and extra +pixels will slow things down on a large logo. + +@section rotate + +Rotate video by an arbitrary angle expressed in radians. + +The filter accepts the following options: + +A description of the optional parameters follows. +@table @option +@item angle, a +Set an expression for the angle by which to rotate the input video +clockwise, expressed as a number of radians. A negative value will +result in a counter-clockwise rotation. By default it is set to "0". + +This expression is evaluated for each frame. + +@item out_w, ow +Set the output width expression, default value is "iw". +This expression is evaluated just once during configuration. + +@item out_h, oh +Set the output height expression, default value is "ih". +This expression is evaluated just once during configuration. + +@item bilinear +Enable bilinear interpolation if set to 1, a value of 0 disables +it. Default value is 1. + +@item fillcolor, c +Set the color used to fill the output area not covered by the rotated +image. For the generalsyntax of this option, check the "Color" section in the +ffmpeg-utils manual. If the special value "none" is selected then no +background is printed (useful for example if the background is never shown). +Default value is "black". @end table -The default value of the select expression is "1". +The expressions for the angle and the output size can contain the +following constants and functions: -Some examples: +@table @option +@item n +sequential number of the input frame, starting from 0. It is always NAN +before the first frame is filtered. -@example -# Select all the frames in input -select +@item t +time in seconds of the input frame, it is set to 0 when the filter is +configured. It is always NAN before the first frame is filtered. -# The above is the same as -select=expr=1 +@item hsub +@item vsub +horizontal and vertical chroma subsample values. For example for the +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. -# Skip all frames -select=expr=0 +@item in_w, iw +@item in_h, ih +the input video width and height -# Select only I-frames -select='expr=eq(pict_type\,I)' +@item out_w, ow +@item out_h, oh +the output width and height, that is the size of the padded area as +specified by the @var{width} and @var{height} expressions -# Select one frame per 100 -select='not(mod(n\,100))' +@item rotw(a) +@item roth(a) +the minimal width/height required for completely containing the input +video rotated by @var{a} radians. -# Select only frames contained in the 10-20 time interval -select='gte(t\,10)*lte(t\,20)' +These are only available when computing the @option{out_w} and +@option{out_h} expressions. +@end table -# Select only I frames contained in the 10-20 time interval -select='gte(t\,10)*lte(t\,20)*eq(pict_type\,I)' +@subsection Examples -# Select frames with a minimum distance of 10 seconds -select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)' +@itemize +@item +Rotate the input by PI/6 radians clockwise: +@example +rotate=PI/6 @end example -@anchor{setdar} -@section setdar +@item +Rotate the input by PI/6 radians counter-clockwise: +@example +rotate=-PI/6 +@end example -Set the Display Aspect Ratio for the filter output video. +@item +Rotate the input by 45 degrees clockwise: +@example +rotate=45*PI/180 +@end example -This is done by changing the specified Sample (aka Pixel) Aspect -Ratio, according to the following equation: -@math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR} +@item +Apply a constant rotation with period T, starting from an angle of PI/3: +@example +rotate=PI/3+2*PI*t/T +@end example -Keep in mind that this filter does not modify the pixel dimensions of -the video frame. Also, the display aspect ratio set by this filter may -be changed by later filters in the filterchain, e.g. in case of -scaling or if another "setdar" or a "setsar" filter is applied. +@item +Make the input video rotation oscillating with a period of T +seconds and an amplitude of A radians: +@example +rotate=A*sin(2*PI/T*t) +@end example -It accepts the following parameters: +@item +Rotate the video, output size is chosen so that the whole rotating +input video is always completely contained in the output: +@example +rotate='2*PI*t:ow=hypot(iw,ih):oh=ow' +@end example + +@item +Rotate the video, reduce the output size so that no background is ever +shown: +@example +rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none +@end example +@end itemize + +@subsection Commands + +The filter supports the following commands: @table @option +@item a, angle +Set the angle expression. +The command accepts the same syntax of the corresponding option. -@item dar -The output display aspect ratio. +If the specified expression is not valid, it is kept at its current +value. +@end table + +@section sab +Apply Shape Adaptive Blur. + +The filter accepts the following options: + +@table @option +@item luma_radius, lr +Set luma blur filter strength, must be a value in range 0.1-4.0, default +value is 1.0. A greater value will result in a more blurred image, and +in slower processing. + +@item luma_pre_filter_radius, lpfr +Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default +value is 1.0. + +@item luma_strength, ls +Set luma maximum difference between pixels to still be considered, must +be a value in the 0.1-100.0 range, default value is 1.0. + +@item chroma_radius, cr +Set chroma blur filter strength, must be a value in range 0.1-4.0. A +greater value will result in a more blurred image, and in slower +processing. + +@item chroma_pre_filter_radius, cpfr +Set chroma pre-filter radius, must be a value in the 0.1-2.0 range. + +@item chroma_strength, cs +Set chroma maximum difference between pixels to still be considered, +must be a value in the 0.1-100.0 range. @end table -The parameter @var{dar} is an expression containing -the following constants: +Each chroma option value, if not explicitly specified, is set to the +corresponding luma option value. + +@anchor{scale} +@section scale + +Scale (resize) the input video, using the libswscale library. + +The scale filter forces the output display aspect ratio to be the same +of the input, by changing the output sample aspect ratio. + +If the input image format is different from the format requested by +the next filter, the scale filter will convert the input to the +requested format. + +@subsection Options +The filter accepts the following options, or any of the options +supported by the libswscale scaler. + +See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for +the complete list of scaler options. @table @option -@item E, PI, PHI -These are approximated values for the mathematical constants e -(Euler's number), pi (Greek pi), and phi (the golden ratio). +@item width, w +@item height, h +Set the output video dimension expression. Default value is the input +dimension. -@item w, h -The input width and height. +If the value is 0, the input width is used for the output. -@item a -This is the same as @var{w} / @var{h}. +If one of the values is -1, the scale filter will use a value that +maintains the aspect ratio of the input image, calculated from the +other specified dimension. If both of them are -1, the input size is +used -@item sar -The input sample aspect ratio. +If one of the values is -n with n > 1, the scale filter will also use a value +that maintains the aspect ratio of the input image, calculated from the other +specified dimension. After that it will, however, make sure that the calculated +dimension is divisible by n and adjust the value if necessary. -@item dar -The input display aspect ratio. It is the same as -(@var{w} / @var{h}) * @var{sar}. +See below for the list of accepted constants for use in the dimension +expression. -@item hsub, vsub -The horizontal and vertical chroma subsample values. For example, for the -pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. +@item interl +Set the interlacing mode. It accepts the following values: + +@table @samp +@item 1 +Force interlaced aware scaling. + +@item 0 +Do not apply interlaced scaling. + +@item -1 +Select interlaced aware scaling depending on whether the source frames +are flagged as interlaced or not. @end table -To change the display aspect ratio to 16:9, specify: -@example -setdar=dar=16/9 -# The above is equivalent to -setdar=dar=1.77777 -@end example +Default value is @samp{0}. -Also see the the @ref{setsar} filter documentation. +@item flags +Set libswscale scaling flags. See +@ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the +complete list of values. If not explicitly specified the filter applies +the default flags. -@section setpts +@item size, s +Set the video size. For the syntax of this option, check the "Video size" +section in the ffmpeg-utils manual. -Change the PTS (presentation timestamp) of the input video frames. +@item in_color_matrix +@item out_color_matrix +Set in/output YCbCr color space type. -It accepts the following parameters: +This allows the autodetected value to be overridden as well as allows forcing +a specific value used for the output and encoder. -@table @option +If not specified, the color space type depends on the pixel format. -@item expr -The expression which is evaluated for each frame to construct its timestamp. +Possible values: + +@table @samp +@item auto +Choose automatically. + +@item bt709 +Format conforming to International Telecommunication Union (ITU) +Recommendation BT.709. + +@item fcc +Set color space conforming to the United States Federal Communications +Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a). +@item bt601 +Set color space conforming to: + +@itemize +@item +ITU Radiocommunication Sector (ITU-R) Recommendation BT.601 + +@item +ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G + +@item +Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004 + +@end itemize + +@item smpte240m +Set color space conforming to SMPTE ST 240:1999. @end table -The expression is evaluated through the eval API and can contain the following -constants: +@item in_range +@item out_range +Set in/output YCbCr sample range. -@table @option -@item PTS -The presentation timestamp in input. +This allows the autodetected value to be overridden as well as allows forcing +a specific value used for the output and encoder. If not specified, the +range depends on the pixel format. Possible values: -@item E, PI, PHI -These are approximated values for the mathematical constants e -(Euler's number), pi (Greek pi), and phi (the golden ratio). +@table @samp +@item auto +Choose automatically. -@item N -The count of the input frame, starting from 0. +@item jpeg/full/pc +Set full range (0-255 in case of 8-bit luma). -@item STARTPTS -The PTS of the first video frame. +@item mpeg/tv +Set "MPEG" range (16-235 in case of 8-bit luma). +@end table -@item INTERLACED -State whether the current frame is interlaced. +@item force_original_aspect_ratio +Enable decreasing or increasing output video width or height if necessary to +keep the original aspect ratio. Possible values: -@item PREV_INPTS -The previous input PTS. +@table @samp +@item disable +Scale the video as specified and disable this feature. -@item PREV_OUTPTS -The previous output PTS. +@item decrease +The output video dimensions will automatically be decreased if needed. -@item RTCTIME -The wallclock (RTC) time in microseconds. +@item increase +The output video dimensions will automatically be increased if needed. -@item RTCSTART -The wallclock (RTC) time at the start of the movie in microseconds. +@end table -@item TB -The timebase of the input timestamps. +One useful instance of this option is that when you know a specific device's +maximum allowed resolution, you can use this to limit the output video to +that, while retaining the aspect ratio. For example, device A allows +1280x720 playback, and your video is 1920x800. Using this option (set it to +decrease) and specifying 1280x720 to the command line makes the output +1280x533. + +Please note that this is a different thing than specifying -1 for @option{w} +or @option{h}, you still need to specify the output resolution for this option +to work. @end table -Some examples: +The values of the @option{w} and @option{h} options are expressions +containing the following constants: + +@table @var +@item in_w +@item in_h +The input width and height + +@item iw +@item ih +These are the same as @var{in_w} and @var{in_h}. + +@item out_w +@item out_h +The output (scaled) width and height + +@item ow +@item oh +These are the same as @var{out_w} and @var{out_h} + +@item a +The same as @var{iw} / @var{ih} +@item sar +input sample aspect ratio + +@item dar +The input display aspect ratio. Calculated from @code{(iw / ih) * sar}. + +@item hsub +@item vsub +horizontal and vertical input chroma subsample values. For example for the +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. + +@item ohsub +@item ovsub +horizontal and vertical output chroma subsample values. For example for the +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. +@end table + +@subsection Examples + +@itemize +@item +Scale the input video to a size of 200x100 @example -# Start counting the PTS from zero -setpts=expr=PTS-STARTPTS +scale=w=200:h=100 +@end example -# Fast motion -setpts=expr=0.5*PTS +This is equivalent to: +@example +scale=200:100 +@end example -# Slow motion -setpts=2.0*PTS +or: +@example +scale=200x100 +@end example -# Fixed rate 25 fps -setpts=N/(25*TB) +@item +Specify a size abbreviation for the output size: +@example +scale=qcif +@end example -# Fixed rate 25 fps with some jitter -setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))' +which can also be written as: +@example +scale=size=qcif +@end example + +@item +Scale the input to 2x: +@example +scale=w=2*iw:h=2*ih +@end example -# Generate timestamps from a "live source" and rebase onto the current timebase -setpts='(RTCTIME - RTCSTART) / (TB * 1000000)" +@item +The above is the same as: +@example +scale=2*in_w:2*in_h @end example -@anchor{setsar} -@section setsar +@item +Scale the input to 2x with forced interlaced scaling: +@example +scale=2*iw:2*ih:interl=1 +@end example -Set the Sample (aka Pixel) Aspect Ratio for the filter output video. +@item +Scale the input to half size: +@example +scale=w=iw/2:h=ih/2 +@end example + +@item +Increase the width, and set the height to the same size: +@example +scale=3/2*iw:ow +@end example + +@item +Seek Greek harmony: +@example +scale=iw:1/PHI*iw +scale=ih*PHI:ih +@end example + +@item +Increase the height, and set the width to 3/2 of the height: +@example +scale=w=3/2*oh:h=3/5*ih +@end example + +@item +Increase the size, making the size a multiple of the chroma +subsample values: +@example +scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub" +@end example + +@item +Increase the width to a maximum of 500 pixels, +keeping the same aspect ratio as the input: +@example +scale=w='min(500\, iw*3/2):h=-1' +@end example +@end itemize + +@section separatefields + +The @code{separatefields} takes a frame-based video input and splits +each frame into its components fields, producing a new half height clip +with twice the frame rate and twice the frame count. + +This filter use field-dominance information in frame to decide which +of each pair of fields to place first in the output. +If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter. + +@section setdar, setsar + +The @code{setdar} filter sets the Display Aspect Ratio for the filter +output video. + +This is done by changing the specified Sample (aka Pixel) Aspect +Ratio, according to the following equation: +@example +@var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR} +@end example + +Keep in mind that the @code{setdar} filter does not modify the pixel +dimensions of the video frame. Also, the display aspect ratio set by +this filter may 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 @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for +the filter output video. Note that as a consequence of the application of this filter, the -output display aspect ratio will change according to the following -equation: -@math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR} +output display aspect ratio will change according to the equation +above. -Keep in mind that the sample aspect ratio set by this filter may be -changed by later filters in the filterchain, e.g. if another "setsar" -or a "setdar" filter is applied. +Keep in mind that the sample aspect ratio set by the @code{setsar} +filter may be changed by later filters in the filterchain, e.g. if +another "setsar" or a "setdar" filter is applied. It accepts the following parameters: @table @option +@item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only) +Set the aspect ratio used by the filter. -@item sar -The output sample aspect ratio. +The parameter can be a floating point number string, an expression, or +a string 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". +In case the form "@var{num}:@var{den}" is used, the @code{:} character +should be escaped. + +@item max +Set the maximum integer value to use for expressing numerator and +denominator when reducing the expressed aspect ratio to a rational. +Default value is @code{100}. @end table @@ -2450,48 +7474,64 @@ Horizontal and vertical chroma subsample values. For example, for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. @end table +@subsection Examples + +@itemize + +@item +To change the display aspect ratio to 16:9, specify one of the following: +@example +setdar=dar=1.77777 +setdar=dar=16/9 +setdar=dar=1.77777 +@end example + +@item To change the sample aspect ratio to 10:11, specify: @example setsar=sar=10/11 @end example -@section settb - -Set the timebase to use for the output frames timestamps. -It is mainly useful for testing timebase configuration. - -It accepts the following parameters: +@item +To set a display aspect ratio of 16:9, and specify a maximum integer value of +1000 in the aspect ratio reduction, use the command: +@example +setdar=ratio=16/9:max=1000 +@end example -@table @option +@end itemize -@item expr -The expression which is evaluated into the output timebase. +@anchor{setfield} +@section setfield -@end table +Force field for the output video frame. -The expression can contain the constants "PI", "E", "PHI", "AVTB" (the -default timebase), and "intb" (the input timebase). +The @code{setfield} filter marks the interlace type field for the +output frames. It does not change the input frame, but only sets the +corresponding property, which affects how the frame is treated by +following filters (e.g. @code{fieldorder} or @code{yadif}). -The default value for the input is "intb". +The filter accepts the following options: -Some examples: +@table @option -@example -# Set the timebase to 1/25 -settb=expr=1/25 +@item mode +Available values are: -# Set the timebase to 1/10 -settb=expr=0.1 +@table @samp +@item auto +Keep the same field property. -# Set the timebase to 1001/1000 -settb=1+0.001 +@item bff +Mark the frame as bottom-field-first. -#Set the timebase to 2*intb -settb=2*intb +@item tff +Mark the frame as top-field-first. -#Set the default timebase value -settb=AVTB -@end example +@item prog +Mark the frame as progressive. +@end table +@end table @section showinfo @@ -2527,8 +7567,8 @@ The sample aspect ratio of the input frame, expressed in the form @var{num}/@var{den}. @item s -The size of the input frame, expressed in the form -@var{width}x@var{height}. +The size of the input frame. For the syntax of this option, check the "Video size" +section in the ffmpeg-utils manual. @item i The type of interlaced mode ("P" for "progressive", "T" for top field first, "B" @@ -2545,11 +7585,11 @@ the @code{av_get_picture_type_char} function defined in @file{libavutil/avutil.h}. @item checksum -The Adler-32 checksum of all the planes of the input frame. +The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame. @item plane_checksum -The Adler-32 checksum of each plane of the input frame, expressed in the form -"[@var{c0} @var{c1} @var{c2} @var{c3}]". +The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, +expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]". @end table @section shuffleplanes @@ -2578,20 +7618,677 @@ The first plane has the index 0. The default is to keep the input unchanged. Swap the second and third planes of the input: @example -avconv -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT +ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT @end example -@section split +@section signalstats +Evaluate various visual metrics that assist in determining issues associated +with the digitization of analog video media. -Split input video into several identical outputs. +By default the filter will log these metadata values: -It accepts a single parameter, which specifies the number of outputs. If -unspecified, it defaults to 2. +@table @option +@item YMIN +Display the minimal Y value contained within the input frame. Expressed in +range of [0-255]. + +@item YLOW +Display the Y value at the 10% percentile within the input frame. Expressed in +range of [0-255]. + +@item YAVG +Display the average Y value within the input frame. Expressed in range of +[0-255]. + +@item YHIGH +Display the Y value at the 90% percentile within the input frame. Expressed in +range of [0-255]. + +@item YMAX +Display the maximum Y value contained within the input frame. Expressed in +range of [0-255]. + +@item UMIN +Display the minimal U value contained within the input frame. Expressed in +range of [0-255]. + +@item ULOW +Display the U value at the 10% percentile within the input frame. Expressed in +range of [0-255]. + +@item UAVG +Display the average U value within the input frame. Expressed in range of +[0-255]. + +@item UHIGH +Display the U value at the 90% percentile within the input frame. Expressed in +range of [0-255]. + +@item UMAX +Display the maximum U value contained within the input frame. Expressed in +range of [0-255]. + +@item VMIN +Display the minimal V value contained within the input frame. Expressed in +range of [0-255]. + +@item VLOW +Display the V value at the 10% percentile within the input frame. Expressed in +range of [0-255]. + +@item VAVG +Display the average V value within the input frame. Expressed in range of +[0-255]. + +@item VHIGH +Display the V value at the 90% percentile within the input frame. Expressed in +range of [0-255]. + +@item VMAX +Display the maximum V value contained within the input frame. Expressed in +range of [0-255]. + +@item SATMIN +Display the minimal saturation value contained within the input frame. +Expressed in range of [0-~181.02]. + +@item SATLOW +Display the saturation value at the 10% percentile within the input frame. +Expressed in range of [0-~181.02]. + +@item SATAVG +Display the average saturation value within the input frame. Expressed in range +of [0-~181.02]. + +@item SATHIGH +Display the saturation value at the 90% percentile within the input frame. +Expressed in range of [0-~181.02]. + +@item SATMAX +Display the maximum saturation value contained within the input frame. +Expressed in range of [0-~181.02]. + +@item HUEMED +Display the median value for hue within the input frame. Expressed in range of +[0-360]. + +@item HUEAVG +Display the average value for hue within the input frame. Expressed in range of +[0-360]. + +@item YDIF +Display the average of sample value difference between all values of the Y +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. + +@item UDIF +Display the average of sample value difference between all values of the U +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. + +@item VDIF +Display the average of sample value difference between all values of the V +plane in the current frame and corresponding values of the previous input frame. +Expressed in range of [0-255]. +@end table + +The filter accepts the following options: + +@table @option +@item stat +@item out + +@option{stat} specify an additional form of image analysis. +@option{out} output video with the specified type of pixel highlighted. + +Both options accept the following values: + +@table @samp +@item tout +Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel +unlike the neighboring pixels of the same field. Examples of temporal outliers +include the results of video dropouts, head clogs, or tape tracking issues. + +@item vrep +Identify @var{vertical line repetition}. Vertical line repetition includes +similar rows of pixels within a frame. In born-digital video vertical line +repetition is common, but this pattern is uncommon in video digitized from an +analog source. When it occurs in video that results from the digitization of an +analog source it can indicate concealment from a dropout compensator. + +@item brng +Identify pixels that fall outside of legal broadcast range. +@end table + +@item color, c +Set the highlight color for the @option{out} option. The default color is +yellow. +@end table + +@subsection Examples + +@itemize +@item +Output data of various video metrics: +@example +ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames +@end example + +@item +Output specific data about the minimum and maximum values of the Y plane per frame: +@example +ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN +@end example + +@item +Playback video while highlighting pixels that are outside of broadcast range in red. +@example +ffplay example.mov -vf signalstats="out=brng:color=red" +@end example + +@item +Playback video with signalstats metadata drawn over the frame. +@example +ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt +@end example + +The contents of signalstat_drawtext.txt used in the command are: +@example +time %@{pts:hms@} +Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@}) +U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@}) +V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@}) +saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@} + +@end example +@end itemize + +@anchor{smartblur} +@section smartblur + +Blur the input video without impacting the outlines. + +It accepts the following options: + +@table @option +@item luma_radius, lr +Set the luma radius. The option value must be a float number in +the range [0.1,5.0] that specifies the variance of the gaussian filter +used to blur the image (slower if larger). Default value is 1.0. + +@item luma_strength, ls +Set the luma strength. The option value must be a float number +in the range [-1.0,1.0] that configures the blurring. A value included +in [0.0,1.0] will blur the image whereas a value included in +[-1.0,0.0] will sharpen the image. Default value is 1.0. + +@item luma_threshold, lt +Set the luma threshold used as a coefficient to determine +whether a pixel should be blurred or not. The option value must be an +integer in the range [-30,30]. A value of 0 will filter all the image, +a value included in [0,30] will filter flat areas and a value included +in [-30,0] will filter edges. Default value is 0. + +@item chroma_radius, cr +Set the chroma radius. The option value must be a float number in +the range [0.1,5.0] that specifies the variance of the gaussian filter +used to blur the image (slower if larger). Default value is 1.0. + +@item chroma_strength, cs +Set the chroma strength. The option value must be a float number +in the range [-1.0,1.0] that configures the blurring. A value included +in [0.0,1.0] will blur the image whereas a value included in +[-1.0,0.0] will sharpen the image. Default value is 1.0. + +@item chroma_threshold, ct +Set the chroma threshold used as a coefficient to determine +whether a pixel should be blurred or not. The option value must be an +integer in the range [-30,30]. A value of 0 will filter all the image, +a value included in [0,30] will filter flat areas and a value included +in [-30,0] will filter edges. Default value is 0. +@end table + +If a chroma option is not explicitly set, the corresponding luma value +is set. + +@section stereo3d + +Convert between different stereoscopic image formats. + +The filters accept the following options: + +@table @option +@item in +Set stereoscopic image format of input. + +Available values for input image formats are: +@table @samp +@item sbsl +side by side parallel (left eye left, right eye right) + +@item sbsr +side by side crosseye (right eye left, left eye right) + +@item sbs2l +side by side parallel with half width resolution +(left eye left, right eye right) + +@item sbs2r +side by side crosseye with half width resolution +(right eye left, left eye right) + +@item abl +above-below (left eye above, right eye below) + +@item abr +above-below (right eye above, left eye below) + +@item ab2l +above-below with half height resolution +(left eye above, right eye below) + +@item ab2r +above-below with half height resolution +(right eye above, left eye below) + +@item al +alternating frames (left eye first, right eye second) + +@item ar +alternating frames (right eye first, left eye second) + +Default value is @samp{sbsl}. +@end table + +@item out +Set stereoscopic image format of output. -Create 5 copies of the input video: +Available values for output image formats are all the input formats as well as: +@table @samp +@item arbg +anaglyph red/blue gray +(red filter on left eye, blue filter on right eye) + +@item argg +anaglyph red/green gray +(red filter on left eye, green filter on right eye) + +@item arcg +anaglyph red/cyan gray +(red filter on left eye, cyan filter on right eye) + +@item arch +anaglyph red/cyan half colored +(red filter on left eye, cyan filter on right eye) + +@item arcc +anaglyph red/cyan color +(red filter on left eye, cyan filter on right eye) + +@item arcd +anaglyph red/cyan color optimized with the least squares projection of dubois +(red filter on left eye, cyan filter on right eye) + +@item agmg +anaglyph green/magenta gray +(green filter on left eye, magenta filter on right eye) + +@item agmh +anaglyph green/magenta half colored +(green filter on left eye, magenta filter on right eye) + +@item agmc +anaglyph green/magenta colored +(green filter on left eye, magenta filter on right eye) + +@item agmd +anaglyph green/magenta color optimized with the least squares projection of dubois +(green filter on left eye, magenta filter on right eye) + +@item aybg +anaglyph yellow/blue gray +(yellow filter on left eye, blue filter on right eye) + +@item aybh +anaglyph yellow/blue half colored +(yellow filter on left eye, blue filter on right eye) + +@item aybc +anaglyph yellow/blue colored +(yellow filter on left eye, blue filter on right eye) + +@item aybd +anaglyph yellow/blue color optimized with the least squares projection of dubois +(yellow filter on left eye, blue filter on right eye) + +@item irl +interleaved rows (left eye has top row, right eye starts on next row) + +@item irr +interleaved rows (right eye has top row, left eye starts on next row) + +@item ml +mono output (left eye only) + +@item mr +mono output (right eye only) +@end table + +Default value is @samp{arcd}. +@end table + +@subsection Examples + +@itemize +@item +Convert input video from side by side parallel to anaglyph yellow/blue dubois: +@example +stereo3d=sbsl:aybd +@end example + +@item +Convert input video from above bellow (left eye above, right eye below) to side by side crosseye. @example -avconv -i INPUT -filter_complex split=5 OUTPUT +stereo3d=abl:sbsr @end example +@end itemize + +@section spp + +Apply a simple postprocessing filter that compresses and decompresses the image +at several (or - in the case of @option{quality} level @code{6} - all) shifts +and average the results. + +The filter accepts the following options: + +@table @option +@item quality +Set quality. This option defines the number of levels for averaging. It accepts +an integer in the range 0-6. If set to @code{0}, the filter will have no +effect. A value of @code{6} means the higher quality. For each increment of +that value the speed drops by a factor of approximately 2. Default value is +@code{3}. + +@item qp +Force a constant quantization parameter. If not set, the filter will use the QP +from the video stream (if available). + +@item mode +Set thresholding mode. Available modes are: + +@table @samp +@item hard +Set hard thresholding (default). +@item soft +Set soft thresholding (better de-ringing effect, but likely blurrier). +@end table + +@item use_bframe_qp +Enable the use of the QP from the B-Frames if set to @code{1}. Using this +option may cause flicker since the B-Frames have often larger QP. Default is +@code{0} (not enabled). +@end table + +@anchor{subtitles} +@section subtitles + +Draw subtitles on top of input video using the libass library. + +To enable compilation of this filter you need to configure FFmpeg with +@code{--enable-libass}. This filter also requires a build with libavcodec and +libavformat to convert the passed subtitles file to ASS (Advanced Substation +Alpha) subtitles format. + +The filter accepts the following options: + +@table @option +@item filename, f +Set the filename of the subtitle file to read. It must be specified. + +@item original_size +Specify the size of the original video, the video for which the ASS file +was composed. For the syntax of this option, check the "Video size" section in +the ffmpeg-utils manual. Due to a misdesign in ASS aspect ratio arithmetic, +this is necessary to correctly scale the fonts if the aspect ratio has been +changed. + +@item charenc +Set subtitles input character encoding. @code{subtitles} filter only. Only +useful if not UTF-8. + +@item stream_index, si +Set subtitles stream index. @code{subtitles} filter only. +@end table + +If the first key is not specified, it is assumed that the first value +specifies the @option{filename}. + +For example, to render the file @file{sub.srt} on top of the input +video, use the command: +@example +subtitles=sub.srt +@end example + +which is equivalent to: +@example +subtitles=filename=sub.srt +@end example + +To render the default subtitles stream from file @file{video.mkv}, use: +@example +subtitles=video.mkv +@end example + +To render the second subtitles stream from that file, use: +@example +subtitles=video.mkv:si=1 +@end example + +@section super2xsai + +Scale the input by 2x and smooth using the Super2xSaI (Scale and +Interpolate) pixel art scaling algorithm. + +Useful for enlarging pixel art images without reducing sharpness. + +@section swapuv +Swap U & V plane. + +@section telecine + +Apply telecine process to the video. + +This filter accepts the following options: + +@table @option +@item first_field +@table @samp +@item top, t +top field first +@item bottom, b +bottom field first +The default value is @code{top}. +@end table + +@item pattern +A string of numbers representing the pulldown pattern you wish to apply. +The default value is @code{23}. +@end table + +@example +Some typical patterns: + +NTSC output (30i): +27.5p: 32222 +24p: 23 (classic) +24p: 2332 (preferred) +20p: 33 +18p: 334 +16p: 3444 + +PAL output (25i): +27.5p: 12222 +24p: 222222222223 ("Euro pulldown") +16.67p: 33 +16p: 33333334 +@end example + +@section thumbnail +Select the most representative frame in a given sequence of consecutive frames. + +The filter accepts the following options: + +@table @option +@item n +Set the frames batch size to analyze; in a set of @var{n} frames, the filter +will pick one of them, and then handle the next batch of @var{n} frames until +the end. Default is @code{100}. +@end table + +Since the filter keeps track of the whole frames sequence, a bigger @var{n} +value will result in a higher memory usage, so a high value is not recommended. + +@subsection Examples + +@itemize +@item +Extract one picture each 50 frames: +@example +thumbnail=50 +@end example + +@item +Complete example of a thumbnail creation with @command{ffmpeg}: +@example +ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png +@end example +@end itemize + +@section tile + +Tile several successive frames together. + +The filter accepts the following options: + +@table @option + +@item layout +Set the grid size (i.e. the number of lines and columns). For the syntax of +this option, check the "Video size" section in the ffmpeg-utils manual. + +@item nb_frames +Set the maximum number of frames to render in the given area. It must be less +than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all +the area will be used. + +@item margin +Set the outer border margin in pixels. + +@item padding +Set the inner border thickness (i.e. the number of pixels between frames). For +more advanced padding options (such as having different values for the edges), +refer to the pad video filter. + +@item color +Specify the color of the unused areaFor the syntax of this option, check the +"Color" section in the ffmpeg-utils manual. The default value of @var{color} +is "black". +@end table + +@subsection Examples + +@itemize +@item +Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie: +@example +ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png +@end example +The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from +duplicating each output frame to accommodate the originally detected frame +rate. + +@item +Display @code{5} pictures in an area of @code{3x2} frames, +with @code{7} pixels between them, and @code{2} pixels of initial margin, using +mixed flat and named options: +@example +tile=3x2:nb_frames=5:padding=7:margin=2 +@end example +@end itemize + +@section tinterlace + +Perform various types of temporal field interlacing. + +Frames are counted starting from 1, so the first input frame is +considered odd. + +The filter accepts the following options: + +@table @option + +@item mode +Specify the mode of the interlacing. This option can also be specified +as a value alone. See below for a list of values for this option. + +Available values are: + +@table @samp +@item merge, 0 +Move odd frames into the upper field, even into the lower field, +generating a double height frame at half frame rate. + +@item drop_odd, 1 +Only output even frames, odd frames are dropped, generating a frame with +unchanged height at half frame rate. + +@item drop_even, 2 +Only output odd frames, even frames are dropped, generating a frame with +unchanged height at half frame rate. + +@item pad, 3 +Expand each frame to full height, but pad alternate lines with black, +generating a frame with double height at the same input frame rate. + +@item interleave_top, 4 +Interleave the upper field from odd frames with the lower field from +even frames, generating a frame with unchanged height at half frame rate. + +@item interleave_bottom, 5 +Interleave the lower field from odd frames with the upper field from +even frames, generating a frame with unchanged height at half frame rate. + +@item interlacex2, 6 +Double frame rate with unchanged height. Frames are inserted each +containing the second temporal field from the previous input frame and +the first temporal field from the next input frame. This mode relies on +the top_field_first flag. Useful for interlaced video displays with no +field synchronisation. +@end table + +Numeric values are deprecated but are accepted for backward +compatibility reasons. + +Default mode is @code{merge}. + +@item flags +Specify flags influencing the filter process. + +Available value for @var{flags} is: + +@table @option +@item low_pass_filter, vlfp +Enable vertical low-pass filtering in the filter. +Vertical low-pass filtering is required when creating an interlaced +destination from a progressive source which contains high-frequency +vertical detail. Filtering will reduce interlace 'twitter' and Moire +patterning. + +Vertical low-pass filtering can only be enabled for @option{mode} +@var{interleave_top} and @var{interleave_bottom}. + +@end table +@end table @section transpose @@ -2602,14 +8299,11 @@ It accepts the following parameters: @table @option @item dir -The direction of the transpose. - -@end table - -The direction can assume the following values: +Specify the transposition direction. +Can assume the following values: @table @samp -@item cclock_flip +@item 0, 4, cclock_flip Rotate by 90 degrees counterclockwise and vertically flip (default), that is: @example L.R L.l @@ -2617,7 +8311,7 @@ L.R L.l l.r R.r @end example -@item clock +@item 1, 5, clock Rotate by 90 degrees clockwise, that is: @example L.R l.L @@ -2625,7 +8319,7 @@ L.R l.L l.r r.R @end example -@item cclock +@item 2, 6, cclock Rotate by 90 degrees counterclockwise, that is: @example L.R R.r @@ -2633,7 +8327,7 @@ L.R R.r l.r L.l @end example -@item clock_flip +@item 3, 7, clock_flip Rotate by 90 degrees clockwise and vertically flip, that is: @example L.R r.R @@ -2642,17 +8336,50 @@ l.r l.L @end example @end table +For values between 4-7, the transposition is only done if the input +video geometry is portrait and not landscape. These values are +deprecated, the @code{passthrough} option should be used instead. + +Numerical values are deprecated, and should be dropped in favor of +symbolic constants. + +@item passthrough +Do not apply the transposition if the input geometry matches the one +specified by the specified value. It accepts the following values: +@table @samp +@item none +Always apply transposition. +@item portrait +Preserve portrait geometry (when @var{height} >= @var{width}). +@item landscape +Preserve landscape geometry (when @var{width} >= @var{height}). +@end table + +Default value is @code{none}. +@end table + +For example to rotate by 90 degrees clockwise and preserve portrait +layout: +@example +transpose=dir=1:passthrough=portrait +@end example + +The command above can also be specified as: +@example +transpose=1:portrait +@end example + @section trim Trim the input so that the output contains one continuous subpart of the input. It accepts the following parameters: @table @option @item start -The timestamp (in seconds) of the start of the kept section. The frame with the +Specify the time 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 -The timestamp (in seconds) of the first frame that will be dropped. The frame +Specify the time 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. @@ -2674,6 +8401,10 @@ The number of the first frame that should be passed to the output. The number of the first frame that should be dropped. @end table +@option{start}, @option{end}, @option{duration} are expressed as time +duration specifications, check the "Time duration" section in the +ffmpeg-utils manual. + 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 @@ -2693,16 +8424,18 @@ Examples: @item Drop everything except the second minute of input: @example -avconv -i INPUT -vf trim=60:120 +ffmpeg -i INPUT -vf trim=60:120 @end example @item Keep only the first second: @example -avconv -i INPUT -vf trim=duration=1 +ffmpeg -i INPUT -vf trim=duration=1 @end example @end itemize + + @section unsharp Sharpen or blur the input video. @@ -2710,56 +8443,457 @@ Sharpen or blur the input video. It accepts the following parameters: @table @option +@item luma_msize_x, lx +Set the luma matrix horizontal size. It must be an odd integer between +3 and 63. The default value is 5. + +@item luma_msize_y, ly +Set the luma matrix vertical size. It must be an odd integer between 3 +and 63. The default value is 5. + +@item luma_amount, la +Set the luma effect strength. It must be a floating point number, reasonable +values lay between -1.5 and 1.5. + +Negative values will blur the input video, while positive values will +sharpen it, a value of zero will disable the effect. -@item luma_msize_x -Set the luma matrix horizontal size. It must be an integer between 3 -and 13. The default value is 5. +Default value is 1.0. -@item luma_msize_y -Set the luma matrix vertical size. It must be an integer between 3 -and 13. The default value is 5. +@item chroma_msize_x, cx +Set the chroma matrix horizontal size. It must be an odd integer +between 3 and 63. The default value is 5. -@item luma_amount -Set the luma effect strength. It must be a floating point number between -2.0 -and 5.0. The default value is 1.0. +@item chroma_msize_y, cy +Set the chroma matrix vertical size. It must be an odd integer +between 3 and 63. The default value is 5. -@item chroma_msize_x -Set the chroma matrix horizontal size. It must be an integer between 3 -and 13. The default value is 5. +@item chroma_amount, ca +Set the chroma effect strength. It must be a floating point number, reasonable +values lay between -1.5 and 1.5. -@item chroma_msize_y -Set the chroma matrix vertical size. It must be an integer between 3 -and 13. The default value is 5. +Negative values will blur the input video, while positive values will +sharpen it, a value of zero will disable the effect. -@item chroma_amount -Set the chroma effect strength. It must be a floating point number between -2.0 -and 5.0. The default value is 0.0. +Default value is 0.0. + +@item opencl +If set to 1, specify using OpenCL capabilities, only available if +FFmpeg was configured with @code{--enable-opencl}. Default value is 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'. +All parameters are optional and default to the equivalent of the +string '5:5:1.0:5:5:0.0'. + +@subsection Examples +@itemize +@item +Apply strong luma sharpen effect: @example -# Strong luma sharpen effect parameters unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5 +@end example -# A strong blur of both luma and chroma parameters +@item +Apply a strong blur of both luma and chroma parameters: +@example unsharp=7:7:-2:7:7:-2 +@end example +@end itemize + +@anchor{vidstabdetect} +@section vidstabdetect + +Analyze video stabilization/deshaking. Perform pass 1 of 2, see +@ref{vidstabtransform} for pass 2. + +This filter generates a file with relative translation and rotation +transform information about subsequent frames, which is then used by +the @ref{vidstabtransform} filter. + +To enable compilation of this filter you need to configure FFmpeg with +@code{--enable-libvidstab}. + +This filter accepts the following options: -# Use the default values with @command{avconv} -./avconv -i in.avi -vf "unsharp" out.mp4 +@table @option +@item result +Set the path to the file used to write the transforms information. +Default value is @file{transforms.trf}. + +@item shakiness +Set how shaky the video is and how quick the camera is. It accepts an +integer in the range 1-10, a value of 1 means little shakiness, a +value of 10 means strong shakiness. Default value is 5. + +@item accuracy +Set the accuracy of the detection process. It must be a value in the +range 1-15. A value of 1 means low accuracy, a value of 15 means high +accuracy. Default value is 15. + +@item stepsize +Set stepsize of the search process. The region around minimum is +scanned with 1 pixel resolution. Default value is 6. + +@item mincontrast +Set minimum contrast. Below this value a local measurement field is +discarded. Must be a floating point value in the range 0-1. Default +value is 0.3. + +@item tripod +Set reference frame number for tripod mode. + +If enabled, the motion of the frames is compared to a reference frame +in the filtered stream, identified by the specified number. The idea +is to compensate all movements in a more-or-less static scene and keep +the camera view absolutely still. + +If set to 0, it is disabled. The frames are counted starting from 1. + +@item show +Show fields and transforms in the resulting frames. It accepts an +integer in the range 0-2. Default value is 0, which disables any +visualization. +@end table + +@subsection Examples + +@itemize +@item +Use default values: +@example +vidstabdetect +@end example + +@item +Analyze strongly shaky movie and put the results in file +@file{mytransforms.trf}: +@example +vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf" @end example +@item +Visualize the result of internal transformations in the resulting +video: +@example +vidstabdetect=show=1 +@end example + +@item +Analyze a video with medium shakiness using @command{ffmpeg}: +@example +ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi +@end example +@end itemize + +@anchor{vidstabtransform} +@section vidstabtransform + +Video stabilization/deshaking: pass 2 of 2, +see @ref{vidstabdetect} for pass 1. + +Read a file with transform information for each frame and +apply/compensate them. Together with the @ref{vidstabdetect} +filter this can be used to deshake videos. See also +@url{http://public.hronopik.de/vid.stab}. It is important to also use +the unsharp filter, see below. + +To enable compilation of this filter you need to configure FFmpeg with +@code{--enable-libvidstab}. + +@subsection Options + +@table @option +@item input +Set path to the file used to read the transforms. Default value is +@file{transforms.trf}). + +@item smoothing +Set the number of frames (value*2 + 1) used for lowpass filtering the +camera movements. Default value is 10. + +For example a number of 10 means that 21 frames are used (10 in the +past and 10 in the future) to smoothen the motion in the video. A +larger values leads to a smoother video, but limits the acceleration +of the camera (pan/tilt movements). 0 is a special case where a +static camera is simulated. + +@item optalgo +Set the camera path optimization algorithm. + +Accepted values are: +@table @samp +@item gauss +gaussian kernel low-pass filter on camera motion (default) +@item avg +averaging on transformations +@end table + +@item maxshift +Set maximal number of pixels to translate frames. Default value is -1, +meaning no limit. + +@item maxangle +Set maximal angle in radians (degree*PI/180) to rotate frames. Default +value is -1, meaning no limit. + +@item crop +Specify how to deal with borders that may be visible due to movement +compensation. + +Available values are: +@table @samp +@item keep +keep image information from previous frame (default) +@item black +fill the border black +@end table + +@item invert +Invert transforms if set to 1. Default value is 0. + +@item relative +Consider transforms as relative to previsou frame if set to 1, +absolute if set to 0. Default value is 0. + +@item zoom +Set percentage to zoom. A positive value will result in a zoom-in +effect, a negative value in a zoom-out effect. Default value is 0 (no +zoom). + +@item optzoom +Set optimal zooming to avoid borders. + +Accepted values are: +@table @samp +@item 0 +disabled +@item 1 +optimal static zoom value is determined (only very strong movements +will lead to visible borders) (default) +@item 2 +optimal adaptive zoom value is determined (no borders will be +visible), see @option{zoomspeed} +@end table + +Note that the value given at zoom is added to the one calculated here. + +@item zoomspeed +Set percent to zoom maximally each frame (enabled when +@option{optzoom} is set to 2). Range is from 0 to 5, default value is +0.25. + +@item interpol +Specify type of interpolation. + +Available values are: +@table @samp +@item no +no interpolation +@item linear +linear only horizontal +@item bilinear +linear in both directions (default) +@item bicubic +cubic in both directions (slow) +@end table + +@item tripod +Enable virtual tripod mode if set to 1, which is equivalent to +@code{relative=0:smoothing=0}. Default value is 0. + +Use also @code{tripod} option of @ref{vidstabdetect}. + +@item debug +Increase log verbosity if set to 1. Also the detected global motions +are written to the temporary file @file{global_motions.trf}. Default +value is 0. +@end table + +@subsection Examples + +@itemize +@item +Use @command{ffmpeg} for a typical stabilization with default values: +@example +ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg +@end example + +Note the use of the unsharp filter which is always recommended. + +@item +Zoom in a bit more and load transform data from a given file: +@example +vidstabtransform=zoom=5:input="mytransforms.trf" +@end example + +@item +Smoothen the video even more: +@example +vidstabtransform=smoothing=30 +@end example +@end itemize + @section vflip Flip the input video vertically. +For example, to vertically flip a video with @command{ffmpeg}: @example -./avconv -i in.avi -vf "vflip" out.avi +ffmpeg -i in.avi -vf "vflip" out.avi @end example +@section vignette + +Make or reverse a natural vignetting effect. + +The filter accepts the following options: + +@table @option +@item angle, a +Set lens angle expression as a number of radians. + +The value is clipped in the @code{[0,PI/2]} range. + +Default value: @code{"PI/5"} + +@item x0 +@item y0 +Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"} +by default. + +@item mode +Set forward/backward mode. + +Available modes are: +@table @samp +@item forward +The larger the distance from the central point, the darker the image becomes. + +@item backward +The larger the distance from the central point, the brighter the image becomes. +This can be used to reverse a vignette effect, though there is no automatic +detection to extract the lens @option{angle} and other settings (yet). It can +also be used to create a burning effect. +@end table + +Default value is @samp{forward}. + +@item eval +Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}). + +It accepts the following values: +@table @samp +@item init +Evaluate expressions only once during the filter initialization. + +@item frame +Evaluate expressions for each incoming frame. This is way slower than the +@samp{init} mode since it requires all the scalers to be re-computed, but it +allows advanced dynamic expressions. +@end table + +Default value is @samp{init}. + +@item dither +Set dithering to reduce the circular banding effects. Default is @code{1} +(enabled). + +@item aspect +Set vignette aspect. This setting allows one to adjust the shape of the vignette. +Setting this value to the SAR of the input will make a rectangular vignetting +following the dimensions of the video. + +Default is @code{1/1}. +@end table + +@subsection Expressions + +The @option{alpha}, @option{x0} and @option{y0} expressions can contain the +following parameters. + +@table @option +@item w +@item h +input width and height + +@item n +the number of input frame, starting from 0 + +@item pts +the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in +@var{TB} units, NAN if undefined + +@item r +frame rate of the input video, NAN if the input frame rate is unknown + +@item t +the PTS (Presentation TimeStamp) of the filtered video frame, +expressed in seconds, NAN if undefined + +@item tb +time base of the input video +@end table + + +@subsection Examples + +@itemize +@item +Apply simple strong vignetting effect: +@example +vignette=PI/4 +@end example + +@item +Make a flickering vignetting: +@example +vignette='PI/4+random(1)*PI/50':eval=frame +@end example + +@end itemize + +@section w3fdif + +Deinterlace the input video ("w3fdif" stands for "Weston 3 Field +Deinterlacing Filter"). + +Based on the process described by Martin Weston for BBC R&D, and +implemented based on the de-interlace algorithm written by Jim +Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter +uses filter coefficients calculated by BBC R&D. + +There are two sets of filter coefficients, so called "simple": +and "complex". Which set of filter coefficients is used can +be set by passing an optional parameter: + +@table @option +@item filter +Set the interlacing filter coefficients. Accepts one of the following values: + +@table @samp +@item simple +Simple filter coefficient set. +@item complex +More-complex filter coefficient set. +@end table +Default value is @samp{complex}. + +@item deint +Specify which frames to deinterlace. Accept one of the following values: + +@table @samp +@item all +Deinterlace all frames, +@item interlaced +Only deinterlace frames marked as interlaced. +@end table + +Default value is @samp{all}. +@end table + +@anchor{yadif} @section yadif Deinterlace the input video ("yadif" means "yet another deinterlacing @@ -2767,56 +8901,144 @@ filter"). It accepts the following parameters: + @table @option @item mode The interlacing mode to adopt. It accepts one of the following values: @table @option -@item 0 +@item 0, send_frame Output one frame for each frame. -@item 1 +@item 1, send_field Output one frame for each field. -@item 2 -Like 0, but it skips the spatial interlacing check. -@item 3 -Like 1, but it skips the spatial interlacing check. +@item 2, send_frame_nospatial +Like @code{send_frame}, but it skips the spatial interlacing check. +@item 3, send_field_nospatial +Like @code{send_field}, but it skips the spatial interlacing check. @end table -The default value is 0. +The default value is @code{send_frame}. @item parity The picture field parity assumed for the input interlaced video. It accepts one of the following values: @table @option -@item 0 +@item 0, tff Assume the top field is first. -@item 1 +@item 1, bff Assume the bottom field is first. -@item -1 +@item -1, auto Enable automatic detection of field parity. @end table -The default value is -1. +The default value is @code{auto}. If the interlacing is unknown or the decoder does not export this information, top field first will be assumed. -@item auto -Whether the deinterlacer should trust the interlaced flag and only deinterlace -frames marked as interlaced. +@item deint +Specify which frames to deinterlace. Accept one of the following +values: @table @option -@item 0 +@item 0, all Deinterlace all frames. -@item 1 +@item 1, interlaced Only deinterlace frames marked as interlaced. @end table -The default value is 0. +The default value is @code{all}. +@end table + +@section zoompan + +Apply Zoom & Pan effect. + +This filter accepts the following options: +@table @option +@item zoom, z +Set the zoom expression. Default is 1. + +@item x +@item y +Set the x and y expression. Default is 0. + +@item d +Set the duration expression in number of frames. +This sets for how many number of frames effect will last for +single input image. + +@item s +Set the output image size, default is 'hd720'. @end table +Each expression can contain the following constants: + +@table @option +@item in_w, iw +Input width. + +@item in_h, ih +Input height. + +@item out_w, ow +Output width. + +@item out_h, oh +Output height. + +@item in +Input frame count. + +@item on +Output frame count. + +@item x +@item y +Last calculated 'x' and 'y' position from 'x' and 'y' expression +for current input frame. + +@item px +@item py +'x' and 'y' of last output frame of previous input frame or 0 when there was +not yet such frame (first input frame). + +@item zoom +Last calculated zoom from 'z' expression for current input frame. + +@item pzoom +Last calculated zoom of last output frame of previous input frame. + +@item duration +Number of output frames for current input frame. Calculated from 'd' expression +for each input frame. + +@item pduration +number of output frames created for previous input frame + +@item a +Rational number: input width / input height + +@item sar +sample aspect ratio + +@item dar +display aspect ratio + +@end table + +@subsection Examples + +@itemize +@item +Zoom-in up to 1.5 and pan at same time to some spot near center of picture: +@example +zoompan=z='min(zoom+0.0015,1.5)':d=700:x='if(gte(zoom,1.5),x,x+1/a)':y='if(gte(zoom,1.5),y,y+1)':s=640x360 +@end example +@end itemize + @c man end VIDEO FILTERS @chapter Video Sources @@ -2835,6 +9057,11 @@ It accepts the following parameters: @table @option +@item video_size +Specify the size (width and height) of the buffered video frames. For the +syntax of this option, check the "Video size" section in the ffmpeg-utils +manual. + @item width The input video width. @@ -2842,14 +9069,23 @@ The input video width. The input video height. @item pix_fmt -The name of the input video pixel format. +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. +Specify the timebase assumed by the timestamps of the buffered frames. -@item sar +@item frame_rate +Specify the frame rate expected for the video stream. + +@item pixel_aspect, sar The sample (pixel) aspect ratio of the input video. +@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. @end table For example: @@ -2860,131 +9096,275 @@ buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1 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 AVPixelFormat definition in @file{libavutil/pixfmt.h}), +this example corresponds to: +@example +buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1 +@end example -@section color +Alternatively, the options can be specified as a flat string, but this +syntax is deprecated: -Provide an uniformly colored input. +@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}] -It accepts the following parameters: +@section cellauto + +Create a pattern generated by an elementary cellular automaton. + +The initial state of the cellular automaton can be defined through the +@option{filename}, and @option{pattern} options. If such options are +not specified an initial state is created randomly. + +At each new frame a new row in the video is filled with the result of +the cellular automaton next generation. The behavior when the whole +frame is filled is defined by the @option{scroll} option. + +This source accepts the following options: @table @option +@item filename, f +Read the initial cellular automaton state, i.e. the starting row, from +the specified file. +In the file, each non-whitespace character is considered an alive +cell, a newline will terminate the row, and further characters in the +file will be ignored. -@item color -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 pattern, p +Read the initial cellular automaton state, i.e. the starting row, from +the specified string. -@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". +Each non-whitespace character in the string is considered an alive +cell, a newline will terminate the row, and further characters in the +string will be ignored. -@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 floating point -number or a valid video frame rate abbreviation. The default value is -"25". +@item rate, r +Set the video rate, that is the number of frames generated per second. +Default is 25. + +@item random_fill_ratio, ratio +Set the random fill ratio for the initial cellular automaton row. It +is a floating point number value ranging from 0 to 1, defaults to +1/PHI. + +This option is ignored when a file or a pattern is specified. + +@item random_seed, seed +Set the seed for filling randomly the initial row, must be an integer +included between 0 and UINT32_MAX. If not specified, or if explicitly +set to -1, the filter will try to use a good random seed on a best +effort basis. +@item rule +Set the cellular automaton rule, it is a number ranging from 0 to 255. +Default value is 110. + +@item size, s +Set the size of the output video. For the syntax of this option, check +the "Video size" section in the ffmpeg-utils manual. + +If @option{filename} or @option{pattern} is specified, the size is set +by default to the width of the specified initial state row, and the +height is set to @var{width} * PHI. + +If @option{size} is set, it must contain the width of the specified +pattern string, and the specified pattern will be centered in the +larger row. + +If a filename or a pattern string is not specified, the size value +defaults to "320x518" (used for a randomly generated initial state). + +@item scroll +If set to 1, scroll the output upward when all the rows in the output +have been already filled. If set to 0, the new generated row will be +written over the top row just after the bottom row is filled. +Defaults to 1. + +@item start_full, full +If set to 1, completely fill the output with generated rows before +outputting the first frame. +This is the default behavior, for disabling set the value to 0. + +@item stitch +If set to 1, stitch the left and right row edges together. +This is the default behavior, for disabling set the value to 0. @end table -The following graph description will generate a red source -with an opacity of 0.2, with size "qcif" and a frame rate of 10 -frames per second, which will be overlayed over the source connected -to the pad with identifier "in": +@subsection Examples +@itemize +@item +Read the initial state from @file{pattern}, and specify an output of +size 200x400. @example -"color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]" +cellauto=f=pattern:s=200x400 @end example -@section movie +@item +Generate a random initial row with a width of 200 cells, with a fill +ratio of 2/3: +@example +cellauto=ratio=2/3:s=200x200 +@end example + +@item +Create a pattern generated by rule 18 starting by a single alive cell +centered on an initial row with width 100: +@example +cellauto=p=@@:s=100x400:full=0:rule=18 +@end example -Read a video stream from a movie container. +@item +Specify a more elaborated initial pattern: +@example +cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18 +@end example + +@end itemize -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. It should never be used with -@command{avconv}; the @option{-filter_complex} option fully replaces it. +@section mandelbrot -It accepts the following parameters: +Generate a Mandelbrot set fractal, and progressively zoom towards the +point specified with @var{start_x} and @var{start_y}. + +This source accepts the following options: @table @option -@item filename -The name of the resource to read (not necessarily a file; it can also be a -device or a stream accessed through some protocol). +@item end_pts +Set the terminal pts value. Default value is 400. -@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 -format is guessed from @var{movie_name} or by probing. +@item end_scale +Set the terminal scale value. +Must be a floating point value. Default value is 0.3. -@item seek_point, sp -Specifies the seek point in seconds. The frames will be output -starting from this seek point. The parameter is evaluated with -@code{av_strtod}, so the numerical value may be suffixed by an IS -postfix. The default value is "0". +@item inner +Set the inner coloring mode, that is the algorithm used to draw the +Mandelbrot fractal internal region. -@item stream_index, si -Specifies the index of the video stream to read. If the value is -1, -the most suitable video stream will be automatically selected. The default -value is "-1". +It shall assume one of the following values: +@table @option +@item black +Set black mode. +@item convergence +Show time until convergence. +@item mincol +Set color based on point closest to the origin of the iterations. +@item period +Set period mode. +@end table + +Default value is @var{mincol}. + +@item bailout +Set the bailout value. Default value is 10.0. + +@item maxiter +Set the maximum of iterations performed by the rendering +algorithm. Default value is 7189. +@item outer +Set outer coloring mode. +It shall assume one of following values: +@table @option +@item iteration_count +Set iteration cound mode. +@item normalized_iteration_count +set normalized iteration count mode. @end table +Default value is @var{normalized_iteration_count}. -It allows overlaying a second video on top of the main input of -a filtergraph, as shown in this graph: -@example -input -----------> deltapts0 --> overlay --> output - ^ - | -movie --> scale--> deltapts1 -------+ -@end example +@item rate, r +Set frame rate, expressed as number of frames per second. Default +value is "25". -Some examples: -@example -# Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it -# on top of the input labelled "in" -movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie]; -[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out] +@item size, s +Set frame size. For the syntax of this option, check the "Video +size" section in the ffmpeg-utils manual. Default value is "640x480". + +@item start_scale +Set the initial scale value. Default value is 3.0. + +@item start_x +Set the initial x position. Must be a floating point value between +-100 and 100. Default value is -0.743643887037158704752191506114774. + +@item start_y +Set the initial y position. Must be a floating point value between +-100 and 100. Default value is -0.131825904205311970493132056385139. +@end table + +@section mptestsrc + +Generate various test patterns, as generated by the MPlayer test filter. -# Read from a video4linux2 device, and overlay it on top of the input -# labelled "in" -movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie]; -[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out] +The size of the generated video is fixed, and is 256x256. +This source is useful in particular for testing encoding features. +This source accepts the following options: + +@table @option + +@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 floating point +number or a valid video frame rate abbreviation. The default value is +"25". + +@item duration, d +Set the video duration of the sourced video. The accepted syntax is: +@example +[-]HH:MM:SS[.m...] +[-]S+[.m...] @end example +See also the function @code{av_parse_time()}. + +If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. + +@item test, t -@section nullsrc +Set the number or the name of the test to perform. Supported tests are: +@table @option +@item dc_luma +@item dc_chroma +@item freq_luma +@item freq_chroma +@item amp_luma +@item amp_chroma +@item cbp +@item mv +@item ring1 +@item ring2 +@item all -Null video source: never return images. It is mainly useful as a -template and to be employed in analysis / debugging tools. +@end table -It accepts a string of the form -@var{width}:@var{height}:@var{timebase} as an optional parameter. +Default value is "all", which will cycle through the list of all tests. +@end table -@var{width} and @var{height} specify the size of the configured -source. The default values of @var{width} and @var{height} are -respectively 352 and 288 (corresponding to the CIF size format). +Some examples: +@example +testsrc=t=dc_luma +@end example -@var{timebase} specifies an arithmetic expression representing a -timebase. The expression can contain the constants "PI", "E", "PHI", and -"AVTB" (the default timebase), and defaults to the value "AVTB". +will generate a "dc_luma" test pattern. @section frei0r_src Provide a frei0r source. To enable compilation of this filter you need to install the frei0r -header and configure Libav with --enable-frei0r. +header and configure FFmpeg with @code{--enable-frei0r}. This source accepts the following parameters: @table @option @item size -The size of the video to generate. It may be a string of the form -@var{width}x@var{height} or a frame size abbreviation. +The size of the video to generate. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. @item framerate The framerate of the generated video. It may be a string of the form @@ -3000,19 +9380,169 @@ A '|'-separated list of parameters to pass to the frei0r source. @end table -An example: +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 framerate 10 -# which is overlayed on the overlay filter main input frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay @end example -@section rgbtestsrc, testsrc +@section life + +Generate a life pattern. + +This source is based on a generalization of John Conway's life game. + +The sourced input represents a life grid, each pixel represents a cell +which can be in one of two possible states, alive or dead. Every cell +interacts with its eight neighbours, which are the cells that are +horizontally, vertically, or diagonally adjacent. + +At each interaction the grid evolves according to the adopted rule, +which specifies the number of neighbor alive cells which will make a +cell stay alive or born. The @option{rule} option allows one to specify +the rule to adopt. + +This source accepts the following options: + +@table @option +@item filename, f +Set the file from which to read the initial grid state. In the file, +each non-whitespace character is considered an alive cell, and newline +is used to delimit the end of each row. + +If this option is not specified, the initial grid is generated +randomly. + +@item rate, r +Set the video rate, that is the number of frames generated per second. +Default is 25. + +@item random_fill_ratio, ratio +Set the random fill ratio for the initial random grid. It is a +floating point number value ranging from 0 to 1, defaults to 1/PHI. +It is ignored when a file is specified. + +@item random_seed, seed +Set the seed for filling the initial random grid, must be an integer +included between 0 and UINT32_MAX. If not specified, or if explicitly +set to -1, the filter will try to use a good random seed on a best +effort basis. + +@item rule +Set the life rule. + +A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}", +where @var{NS} and @var{NB} are sequences of numbers in the range 0-8, +@var{NS} specifies the number of alive neighbor cells which make a +live cell stay alive, and @var{NB} the number of alive neighbor cells +which make a dead cell to become alive (i.e. to "born"). +"s" and "b" can be used in place of "S" and "B", respectively. + +Alternatively a rule can be specified by an 18-bits integer. The 9 +high order bits are used to encode the next cell state if it is alive +for each number of neighbor alive cells, the low order bits specify +the rule for "borning" new cells. Higher order bits encode for an +higher number of neighbor cells. +For example the number 6153 = @code{(12<<9)+9} specifies a stay alive +rule of 12 and a born rule of 9, which corresponds to "S23/B03". + +Default value is "S23/B3", which is the original Conway's game of life +rule, and will keep a cell alive if it has 2 or 3 neighbor alive +cells, and will born a new cell if there are three alive cells around +a dead cell. + +@item size, s +Set the size of the output video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. + +If @option{filename} is specified, the size is set by default to the +same size of the input file. If @option{size} is set, it must contain +the size specified in the input file, and the initial grid defined in +that file is centered in the larger resulting area. + +If a filename is not specified, the size value defaults to "320x240" +(used for a randomly generated initial grid). + +@item stitch +If set to 1, stitch the left and right grid edges together, and the +top and bottom edges also. Defaults to 1. + +@item mold +Set cell mold speed. If set, a dead cell will go from @option{death_color} to +@option{mold_color} with a step of @option{mold}. @option{mold} can have a +value from 0 to 255. + +@item life_color +Set the color of living (or new born) cells. + +@item death_color +Set the color of dead cells. If @option{mold} is set, this is the first color +used to represent a dead cell. + +@item mold_color +Set mold color, for definitely dead and moldy cells. + +For the syntax of these 3 color options, check the "Color" section in the +ffmpeg-utils manual. +@end table + +@subsection Examples + +@itemize +@item +Read a grid from @file{pattern}, and center it on a grid of size +300x300 pixels: +@example +life=f=pattern:s=300x300 +@end example + +@item +Generate a random grid of size 200x200, with a fill ratio of 2/3: +@example +life=ratio=2/3:s=200x200 +@end example + +@item +Specify a custom rule for evolving a randomly generated grid: +@example +life=rule=S14/B34 +@end example + +@item +Full example with slow death effect (mold) using @command{ffplay}: +@example +ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16 +@end example +@end itemize + +@anchor{color} +@anchor{haldclutsrc} +@anchor{nullsrc} +@anchor{rgbtestsrc} +@anchor{smptebars} +@anchor{smptehdbars} +@anchor{testsrc} +@section color, haldclutsrc, nullsrc, rgbtestsrc, smptebars, smptehdbars, testsrc + +The @code{color} source provides an uniformly colored input. + +The @code{haldclutsrc} source provides an identity Hald CLUT. See also +@ref{haldclut} filter. + +The @code{nullsrc} source returns unprocessed video frames. It is +mainly useful to be employed in analysis / debugging tools, or as the +source for filters which ignore the input data. The @code{rgbtestsrc} source generates an RGB test pattern useful for detecting RGB vs BGR issues. You should see a red, green and blue stripe from top to bottom. +The @code{smptebars} source generates a color bars pattern, based on +the SMPTE Engineering Guideline EG 1-1990. + +The @code{smptehdbars} source generates a color bars pattern, based on +the SMPTE RP 219-2002. + The @code{testsrc} source generates a test video pattern, showing a color pattern, a scrolling gradient and a timestamp. This is mainly intended for testing purposes. @@ -3021,10 +9551,23 @@ The sources accept the following parameters: @table @option +@item color, c +Specify the color of the source, only available in the @code{color} +source. For the syntax of this option, check the "Color" section in the +ffmpeg-utils manual. + +@item level +Specify the level of the Hald CLUT, only available in the @code{haldclutsrc} +source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N} +pixels to be used as identity matrix for 3D lookup tables. Each component is +coded on a @code{1/(N*N)} scale. + @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". +Specify the size of the sourced video. For the syntax of this option, check the +"Video size" section in the ffmpeg-utils manual. The default value is +"320x240". + +This option is not available with the @code{haldclutsrc} filter. @item rate, r Specify the frame rate of the sourced video, as the number of frames @@ -3036,7 +9579,7 @@ number or a valid video frame rate abbreviation. The default value is @item sar Set the sample aspect ratio of the sourced video. -@item duration +@item duration, d Set the video duration of the sourced video. The accepted syntax is: @example [-]HH[:MM[:SS[.m...]]] @@ -3046,6 +9589,14 @@ Also see the the @code{av_parse_time()} function. If not specified, or the expressed duration is negative, the video is supposed to be generated forever. + +@item decimals, n +Set the number of decimals to show in the timestamp, only available in the +@code{testsrc} source. + +The displayed timestamp value will correspond to the original +timestamp value multiplied by the power of 10 of the specified +value. Default value is 0. @end table For example the following: @@ -3054,7 +9605,31 @@ testsrc=duration=5.3:size=qcif:rate=10 @end example will generate a video with a duration of 5.3 seconds, with size -176x144 and a framerate of 10 frames per second. +176x144 and a frame rate of 10 frames per second. + +The following graph description will generate a red source +with an opacity of 0.2, with size "qcif" and a frame rate of 10 +frames per second. +@example +color=c=red@@0.2:s=qcif:r=10 +@end example + +If the input content is to be ignored, @code{nullsrc} can be used. The +following command generates noise in the luminance plane by employing +the @code{geq} filter: +@example +nullsrc=s=256x256, geq=random(1)*255:128:128 +@end example + +@subsection Commands + +The @code{color} source supports the following commands: + +@table @option +@item c, color +Set the color of the created image. Accepts the same syntax of the +corresponding @option{color} option. +@end table @c man end VIDEO SOURCES @@ -3068,8 +9643,13 @@ Below is a description of the currently available video sinks. Buffer video frames, and make them available to the end of the filter graph. -This sink is intended for programmatic use through the interface defined in -@file{libavfilter/buffersink.h}. +This sink is mainly intended for programmatic use, in particular +through the interface defined in @file{libavfilter/buffersink.h} +or the options system. + +It accepts a pointer to an AVBufferSinkContext structure, which +defines the incoming buffers' formats, to be passed as the opaque +parameter to @code{avfilter_init_filter} for initialization. @section nullsink @@ -3078,3 +9658,1286 @@ mainly useful as a template and for use in analysis / debugging tools. @c man end VIDEO SINKS + +@chapter Multimedia Filters +@c man begin MULTIMEDIA FILTERS + +Below is a description of the currently available multimedia filters. + +@section avectorscope + +Convert input audio to a video output, representing the audio vector +scope. + +The filter is used to measure the difference between channels of stereo +audio stream. A monoaural signal, consisting of identical left and right +signal, results in straight vertical line. Any stereo separation is visible +as a deviation from this line, creating a Lissajous figure. +If the straight (or deviation from it) but horizontal line appears this +indicates that the left and right channels are out of phase. + +The filter accepts the following options: + +@table @option +@item mode, m +Set the vectorscope mode. + +Available values are: +@table @samp +@item lissajous +Lissajous rotated by 45 degrees. + +@item lissajous_xy +Same as above but not rotated. +@end table + +Default value is @samp{lissajous}. + +@item size, s +Set the video size for the output. For the syntax of this option, check the "Video size" +section in the ffmpeg-utils manual. Default value is @code{400x400}. + +@item rate, r +Set the output frame rate. Default value is @code{25}. + +@item rc +@item gc +@item bc +Specify the red, green and blue contrast. Default values are @code{40}, @code{160} and @code{80}. +Allowed range is @code{[0, 255]}. + +@item rf +@item gf +@item bf +Specify the red, green and blue fade. Default values are @code{15}, @code{10} and @code{5}. +Allowed range is @code{[0, 255]}. + +@item zoom +Set the zoom factor. Default value is @code{1}. Allowed range is @code{[1, 10]}. +@end table + +@subsection Examples + +@itemize +@item +Complete example using @command{ffplay}: +@example +ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; + [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]' +@end example +@end itemize + +@section concat + +Concatenate audio and video streams, joining them together one after the +other. + +The filter works on segments of synchronized video and audio streams. All +segments must have the same number of streams of each type, and that will +also be the number of streams at output. + +The filter accepts the following options: + +@table @option + +@item n +Set the number of segments. Default is 2. + +@item v +Set the number of output video streams, that is also the number of video +streams in each segment. Default is 1. + +@item a +Set the number of output audio streams, that is also the number of audio +streams in each segment. Default is 0. + +@item unsafe +Activate unsafe mode: do not fail if segments have a different format. + +@end table + +The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then +@var{a} audio outputs. + +There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first +segment, in the same order as the outputs, then the inputs for the second +segment, etc. + +Related streams do not always have exactly the same duration, for various +reasons including codec frame size or sloppy authoring. For that reason, +related synchronized streams (e.g. a video and its audio track) should be +concatenated at once. The concat filter will use the duration of the longest +stream in each segment (except the last one), and if necessary pad shorter +audio streams with silence. + +For this filter to work correctly, all segments must start at timestamp 0. + +All corresponding streams must have the same parameters in all segments; the +filtering system will automatically select a common pixel format for video +streams, and a common sample format, sample rate and channel layout for +audio streams, but other settings, such as resolution, must be converted +explicitly by the user. + +Different frame rates are acceptable but will result in variable frame rate +at output; be sure to configure the output file to handle it. + +@subsection Examples + +@itemize +@item +Concatenate an opening, an episode and an ending, all in bilingual version +(video in stream 0, audio in streams 1 and 2): +@example +ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \ + '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2] + concat=n=3:v=1:a=2 [v] [a1] [a2]' \ + -map '[v]' -map '[a1]' -map '[a2]' output.mkv +@end example + +@item +Concatenate two parts, handling audio and video separately, using the +(a)movie sources, and adjusting the resolution: +@example +movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ; +movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ; +[v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa] +@end example +Note that a desync will happen at the stitch if the audio and video streams +do not have exactly the same duration in the first file. + +@end itemize + +@section ebur128 + +EBU R128 scanner filter. This filter takes an audio stream as input and outputs +it unchanged. By default, it logs a message at a frequency of 10Hz with the +Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}), +Integrated loudness (@code{I}) and Loudness Range (@code{LRA}). + +The filter also has a video output (see the @var{video} option) with a real +time graph to observe the loudness evolution. The graphic contains the logged +message mentioned above, so it is not printed anymore when this option is set, +unless the verbose logging is set. The main graphing area contains the +short-term loudness (3 seconds of analysis), and the gauge on the right is for +the momentary loudness (400 milliseconds). + +More information about the Loudness Recommendation EBU R128 on +@url{http://tech.ebu.ch/loudness}. + +The filter accepts the following options: + +@table @option + +@item video +Activate the video output. The audio stream is passed unchanged whether this +option is set or no. The video stream will be the first output stream if +activated. Default is @code{0}. + +@item size +Set the video size. This option is for video only. For the syntax of this +option, check the "Video size" section in the ffmpeg-utils manual. Default +and minimum resolution is @code{640x480}. + +@item meter +Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and +@code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any +other integer value between this range is allowed. + +@item metadata +Set metadata injection. If set to @code{1}, the audio input will be segmented +into 100ms output frames, each of them containing various loudness information +in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}. + +Default is @code{0}. + +@item framelog +Force the frame logging level. + +Available values are: +@table @samp +@item info +information logging level +@item verbose +verbose logging level +@end table + +By default, the logging level is set to @var{info}. If the @option{video} or +the @option{metadata} options are set, it switches to @var{verbose}. + +@item peak +Set peak mode(s). + +Available modes can be cumulated (the option is a @code{flag} type). Possible +values are: +@table @samp +@item none +Disable any peak mode (default). +@item sample +Enable sample-peak mode. + +Simple peak mode looking for the higher sample value. It logs a message +for sample-peak (identified by @code{SPK}). +@item true +Enable true-peak mode. + +If enabled, the peak lookup is done on an over-sampled version of the input +stream for better peak accuracy. It logs a message for true-peak. +(identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}). +This mode requires a build with @code{libswresample}. +@end table + +@end table + +@subsection Examples + +@itemize +@item +Real-time graph using @command{ffplay}, with a EBU scale meter +18: +@example +ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]" +@end example + +@item +Run an analysis with @command{ffmpeg}: +@example +ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null - +@end example +@end itemize + +@section interleave, ainterleave + +Temporally interleave frames from several inputs. + +@code{interleave} works with video inputs, @code{ainterleave} with audio. + +These filters read frames from several inputs and send the oldest +queued frame to the output. + +Input streams must have a well defined, monotonically increasing frame +timestamp values. + +In order to submit one frame to output, these filters need to enqueue +at least one frame for each input, so they cannot work in case one +input is not yet terminated and will not receive incoming frames. + +For example consider the case when one input is a @code{select} filter +which always drop input frames. The @code{interleave} filter will keep +reading from that input, but it will never be able to send new frames +to output until the input will send an end-of-stream signal. + +Also, depending on inputs synchronization, the filters will drop +frames in case one input receives more frames than the other ones, and +the queue is already filled. + +These filters accept the following options: + +@table @option +@item nb_inputs, n +Set the number of different inputs, it is 2 by default. +@end table + +@subsection Examples + +@itemize +@item +Interleave frames belonging to different streams using @command{ffmpeg}: +@example +ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi +@end example + +@item +Add flickering blur effect: +@example +select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave +@end example +@end itemize + +@section perms, aperms + +Set read/write permissions for the output frames. + +These filters are mainly aimed at developers to test direct path in the +following filter in the filtergraph. + +The filters accept the following options: + +@table @option +@item mode +Select the permissions mode. + +It accepts the following values: +@table @samp +@item none +Do nothing. This is the default. +@item ro +Set all the output frames read-only. +@item rw +Set all the output frames directly writable. +@item toggle +Make the frame read-only if writable, and writable if read-only. +@item random +Set each output frame read-only or writable randomly. +@end table + +@item seed +Set the seed for the @var{random} mode, must be an integer included between +@code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to +@code{-1}, the filter will try to use a good random seed on a best effort +basis. +@end table + +Note: in case of auto-inserted filter between the permission filter and the +following one, the permission might not be received as expected in that +following filter. Inserting a @ref{format} or @ref{aformat} filter before the +perms/aperms filter can avoid this problem. + +@section select, aselect + +Select frames to pass in output. + +This filter accepts the following options: + +@table @option + +@item expr, e +Set expression, which is evaluated for each input frame. + +If the expression is evaluated to zero, the frame is discarded. + +If the evaluation result is negative or NaN, the frame is sent to the +first output; otherwise it is sent to the output with index +@code{ceil(val)-1}, assuming that the input index starts from 0. + +For example a value of @code{1.2} corresponds to the output with index +@code{ceil(1.2)-1 = 2-1 = 1}, that is the second output. + +@item outputs, n +Set the number of outputs. The output to which to send the selected +frame is based on the result of the evaluation. Default value is 1. +@end table + +The expression can contain the following constants: + +@table @option +@item n +The (sequential) number of the filtered frame, starting from 0. + +@item selected_n +The (sequential) number of the selected frame, starting from 0. + +@item prev_selected_n +The sequential number of the last selected frame. It's NAN if undefined. + +@item TB +The timebase of the input timestamps. + +@item pts +The PTS (Presentation TimeStamp) of the filtered video frame, +expressed in @var{TB} units. It's NAN if undefined. + +@item t +The PTS of the filtered video frame, +expressed in seconds. It's NAN if undefined. + +@item prev_pts +The PTS of the previously filtered video frame. It's NAN if undefined. + +@item prev_selected_pts +The PTS of the last previously filtered video frame. It's NAN if undefined. + +@item prev_selected_t +The PTS of the last previously selected video frame. It's NAN if undefined. + +@item start_pts +The PTS of the first video frame in the video. It's NAN if undefined. + +@item start_t +The time of the first video frame in the video. It's NAN if undefined. + +@item pict_type @emph{(video only)} +The type of the filtered frame. It can assume one of the following +values: +@table @option +@item I +@item P +@item B +@item S +@item SI +@item SP +@item BI +@end table + +@item interlace_type @emph{(video only)} +The frame interlace type. It can assume one of the following values: +@table @option +@item PROGRESSIVE +The frame is progressive (not interlaced). +@item TOPFIRST +The frame is top-field-first. +@item BOTTOMFIRST +The frame is bottom-field-first. +@end table + +@item consumed_sample_n @emph{(audio only)} +the number of selected samples before the current frame + +@item samples_n @emph{(audio only)} +the number of samples in the current frame + +@item sample_rate @emph{(audio only)} +the input sample rate + +@item key +This is 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) + +@item scene @emph{(video only)} +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". + +@subsection Examples + +@itemize +@item +Select all frames in input: +@example +select +@end example + +The example above is the same as: +@example +select=1 +@end example + +@item +Skip all frames: +@example +select=0 +@end example + +@item +Select only I-frames: +@example +select='eq(pict_type\,I)' +@end example + +@item +Select one frame every 100: +@example +select='not(mod(n\,100))' +@end example + +@item +Select only frames contained in the 10-20 time interval: +@example +select=between(t\,10\,20) +@end example + +@item +Select only I frames contained in the 10-20 time interval: +@example +select=between(t\,10\,20)*eq(pict_type\,I) +@end example + +@item +Select frames with a minimum distance of 10 seconds: +@example +select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)' +@end example + +@item +Use aselect to select only audio frames with samples number > 100: +@example +aselect='gt(samples_n\,100)' +@end example + +@item +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. + +@item +Send even and odd frames to separate outputs, and compose them: +@example +select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h +@end example +@end itemize + +@section sendcmd, asendcmd + +Send commands to filters in the filtergraph. + +These filters read commands to be sent to other filters in the +filtergraph. + +@code{sendcmd} must be inserted between two video filters, +@code{asendcmd} must be inserted between two audio filters, but apart +from that they act the same way. + +The specification of commands can be provided in the filter arguments +with the @var{commands} option, or in a file specified by the +@var{filename} option. + +These filters accept the following options: +@table @option +@item commands, c +Set the commands to be read and sent to the other filters. +@item filename, f +Set the filename of the commands to be read and sent to the other +filters. +@end table + +@subsection Commands syntax + +A commands description consists of a sequence of interval +specifications, comprising a list of commands to be executed when a +particular event related to that interval occurs. The occurring event +is typically the current frame time entering or leaving a given time +interval. + +An interval is specified by the following syntax: +@example +@var{START}[-@var{END}] @var{COMMANDS}; +@end example + +The time interval is specified by the @var{START} and @var{END} times. +@var{END} is optional and defaults to the maximum time. + +The current frame time is considered within the specified interval if +it is included in the interval [@var{START}, @var{END}), that is when +the time is greater or equal to @var{START} and is lesser than +@var{END}. + +@var{COMMANDS} consists of a sequence of one or more command +specifications, separated by ",", relating to that interval. The +syntax of a command specification is given by: +@example +[@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG} +@end example + +@var{FLAGS} is optional and specifies the type of events relating to +the time interval which enable sending the specified command, and must +be a non-null sequence of identifier flags separated by "+" or "|" and +enclosed between "[" and "]". + +The following flags are recognized: +@table @option +@item enter +The command is sent when the current frame timestamp enters the +specified interval. In other words, the command is sent when the +previous frame timestamp was not in the given interval, and the +current is. + +@item leave +The command is sent when the current frame timestamp leaves the +specified interval. In other words, the command is sent when the +previous frame timestamp was in the given interval, and the +current is not. +@end table + +If @var{FLAGS} is not specified, a default value of @code{[enter]} is +assumed. + +@var{TARGET} specifies the target of the command, usually the name of +the filter class or a specific filter instance name. + +@var{COMMAND} specifies the name of the command for the target filter. + +@var{ARG} is optional and specifies the optional list of argument for +the given @var{COMMAND}. + +Between one interval specification and another, whitespaces, or +sequences of characters starting with @code{#} until the end of line, +are ignored and can be used to annotate comments. + +A simplified BNF description of the commands specification syntax +follows: +@example +@var{COMMAND_FLAG} ::= "enter" | "leave" +@var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}] +@var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}] +@var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}] +@var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS} +@var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}] +@end example + +@subsection Examples + +@itemize +@item +Specify audio tempo change at second 4: +@example +asendcmd=c='4.0 atempo tempo 1.5',atempo +@end example + +@item +Specify a list of drawtext and hue commands in a file. +@example +# show text in the interval 5-10 +5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world', + [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text='; + +# desaturate the image in the interval 15-20 +15.0-20.0 [enter] hue s 0, + [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor', + [leave] hue s 1, + [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color'; + +# apply an exponential saturation fade-out effect, starting from time 25 +25 [enter] hue s exp(25-t) +@end example + +A filtergraph allowing to read and process the above command list +stored in a file @file{test.cmd}, can be specified with: +@example +sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue +@end example +@end itemize + +@anchor{setpts} +@section setpts, asetpts + +Change the PTS (presentation timestamp) of the input frames. + +@code{setpts} works on video frames, @code{asetpts} on 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 FRAME_RATE +frame rate, only defined for constant frame-rate video + +@item PTS +The presentation timestamp in input + +@item N +The count of the input frame for video or the number of consumed samples, +not including the current frame for audio, starting from 0. + +@item NB_CONSUMED_SAMPLES +The number of consumed samples, not including the current frame (only +audio) + +@item NB_SAMPLES, S +The number of samples in the current frame (only audio) + +@item SAMPLE_RATE, SR +The audio sample rate. + +@item STARTPTS +The PTS of the first frame. + +@item STARTT +the time in seconds of the first frame + +@item INTERLACED +State whether the current frame is interlaced. + +@item T +the time in seconds of the current frame + +@item POS +original position in the file of the frame, or undefined if undefined +for the current frame + +@item PREV_INPTS +The previous input PTS. + +@item PREV_INT +previous input time in seconds + +@item PREV_OUTPTS +The previous output PTS. + +@item PREV_OUTT +previous output time in seconds + +@item RTCTIME +The wallclock (RTC) time in microseconds.. This is deprecated, use time(0) +instead. + +@item RTCSTART +The wallclock (RTC) time at the start of the movie in microseconds. + +@item TB +The timebase of the input timestamps. + +@end table + +@subsection Examples + +@itemize +@item +Start counting PTS from zero +@example +setpts=PTS-STARTPTS +@end example + +@item +Apply fast motion effect: +@example +setpts=0.5*PTS +@end example + +@item +Apply slow motion effect: +@example +setpts=2.0*PTS +@end example + +@item +Set fixed rate of 25 frames per second: +@example +setpts=N/(25*TB) +@end example + +@item +Set fixed rate 25 fps with some jitter: +@example +setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))' +@end example + +@item +Apply an offset of 10 seconds to the input PTS: +@example +setpts=PTS+10/TB +@end example + +@item +Generate timestamps from a "live source" and rebase onto the current timebase: +@example +setpts='(RTCTIME - RTCSTART) / (TB * 1000000)' +@end example + +@item +Generate timestamps by counting samples: +@example +asetpts=N/SR/TB +@end example + +@end itemize + +@section settb, asettb + +Set the timebase to use for the output frames timestamps. +It is mainly useful for testing timebase configuration. + +It accepts the following parameters: + +@table @option + +@item expr, tb +The expression which is evaluated into the output timebase. + +@end table + +The value for @option{tb} is an arithmetic expression representing a +rational. The expression can contain the constants "AVTB" (the default +timebase), "intb" (the input timebase) and "sr" (the sample rate, +audio only). Default value is "intb". + +@subsection Examples + +@itemize +@item +Set the timebase to 1/25: +@example +settb=expr=1/25 +@end example + +@item +Set the timebase to 1/10: +@example +settb=expr=0.1 +@end example + +@item +Set the timebase to 1001/1000: +@example +settb=1+0.001 +@end example + +@item +Set the timebase to 2*intb: +@example +settb=2*intb +@end example + +@item +Set the default timebase value: +@example +settb=AVTB +@end example +@end itemize + +@section showcqt +Convert input audio to a video output representing +frequency spectrum logarithmically (using constant Q transform with +Brown-Puckette algorithm), with musical tone scale, from E0 to D#10 (10 octaves). + +The filter accepts the following options: + +@table @option +@item volume +Specify the transform volume (multiplier). Acceptable value is [1.0, 100.0]. +Default value is @code{16.0}. + +@item timeclamp +Specify the transform timeclamp. At low frequency, there is trade-off between +accuracy in time domain and frequency domain. If timeclamp is lower, +event in time domain is represented more accurately (such as fast bass drum), +otherwise event in frequency domain is represented more accurately +(such as bass guitar). Acceptable value is [0.1, 1.0]. Default value is @code{0.17}. + +@item coeffclamp +Specify the transform coeffclamp. If coeffclamp is lower, transform is +more accurate, otherwise transform is faster. Acceptable value is [0.1, 10.0]. +Default value is @code{1.0}. + +@item gamma +Specify gamma. Lower gamma makes the spectrum more contrast, higher gamma +makes the spectrum having more range. Acceptable value is [1.0, 7.0]. +Default value is @code{3.0}. + +@item fontfile +Specify font file for use with freetype. If not specified, use embedded font. + +@item fullhd +If set to 1 (the default), the video size is 1920x1080 (full HD), +if set to 0, the video size is 960x540. Use this option to make CPU usage lower. + +@item fps +Specify video fps. Default value is @code{25}. + +@item count +Specify number of transform per frame, so there are fps*count transforms +per second. Note that audio data rate must be divisible by fps*count. +Default value is @code{6}. + +@end table + +@subsection Examples + +@itemize +@item +Playing audio while showing the spectrum: +@example +ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]' +@end example + +@item +Same as above, but with frame rate 30 fps: +@example +ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]' +@end example + +@item +Playing at 960x540 and lower CPU usage: +@example +ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fullhd=0:count=3 [out0]' +@end example + +@item +A1 and its harmonics: A1, A2, (near)E3, A3: +@example +ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t), + asplit[a][out1]; [a] showcqt [out0]' +@end example + +@item +Same as above, but with more accuracy in frequency domain (and slower): +@example +ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t), + asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]' +@end example + +@end itemize + +@section showspectrum + +Convert input audio to a video output, representing the audio frequency +spectrum. + +The filter accepts the following options: + +@table @option +@item size, s +Specify the video size for the output. For the syntax of this option, check +the "Video size" section in the ffmpeg-utils manual. Default value is +@code{640x512}. + +@item slide +Specify if the spectrum should slide along the window. Default value is +@code{0}. + +@item mode +Specify display mode. + +It accepts the following values: +@table @samp +@item combined +all channels are displayed in the same row +@item separate +all channels are displayed in separate rows +@end table + +Default value is @samp{combined}. + +@item color +Specify display color mode. + +It accepts the following values: +@table @samp +@item channel +each channel is displayed in a separate color +@item intensity +each channel is is displayed using the same color scheme +@end table + +Default value is @samp{channel}. + +@item scale +Specify scale used for calculating intensity color values. + +It accepts the following values: +@table @samp +@item lin +linear +@item sqrt +square root, default +@item cbrt +cubic root +@item log +logarithmic +@end table + +Default value is @samp{sqrt}. + +@item saturation +Set saturation modifier for displayed colors. Negative values provide +alternative color scheme. @code{0} is no saturation at all. +Saturation must be in [-10.0, 10.0] range. +Default value is @code{1}. + +@item win_func +Set window function. + +It accepts the following values: +@table @samp +@item none +No samples pre-processing (do not expect this to be faster) +@item hann +Hann window +@item hamming +Hamming window +@item blackman +Blackman window +@end table + +Default value is @code{hann}. +@end table + +The usage is very similar to the showwaves filter; see the examples in that +section. + +@subsection Examples + +@itemize +@item +Large window with logarithmic color scaling: +@example +showspectrum=s=1280x480:scale=log +@end example + +@item +Complete example for a colored and sliding spectrum per channel using @command{ffplay}: +@example +ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; + [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]' +@end example +@end itemize + +@section showwaves + +Convert input audio to a video output, representing the samples waves. + +The filter accepts the following options: + +@table @option +@item size, s +Specify the video size for the output. For the syntax of this option, check +the "Video size" section in the ffmpeg-utils manual. Default value +is "600x240". + +@item mode +Set display mode. + +Available values are: +@table @samp +@item point +Draw a point for each sample. + +@item line +Draw a vertical line for each sample. +@end table + +Default value is @code{point}. + +@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". + +@end table + +@subsection Examples + +@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 +frame rate 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 + +@section split, asplit + +Split input into several identical outputs. + +@code{asplit} works with audio input, @code{split} with video. + +The filter accepts a single parameter which specifies the number of outputs. If +unspecified, it defaults to 2. + +@subsection Examples + +@itemize +@item +Create two separate outputs from the same input: +@example +[in] split [out0][out1] +@end example + +@item +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 + +@item +Create two separate outputs from the same input, one cropped and +one padded: +@example +[in] split [splitout1][splitout2]; +[splitout1] crop=100:100:0:0 [cropout]; +[splitout2] pad=200:200:100:100 [padout]; +@end example + +@item +Create 5 copies of the input audio with @command{ffmpeg}: +@example +ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT +@end example +@end itemize + +@section zmq, azmq + +Receive commands sent through a libzmq client, and forward them to +filters in the filtergraph. + +@code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq} +must be inserted between two video filters, @code{azmq} between two +audio filters. + +To enable these filters you need to install the libzmq library and +headers and configure FFmpeg with @code{--enable-libzmq}. + +For more information about libzmq see: +@url{http://www.zeromq.org/} + +The @code{zmq} and @code{azmq} filters work as a libzmq server, which +receives messages sent through a network interface defined by the +@option{bind_address} option. + +The received message must be in the form: +@example +@var{TARGET} @var{COMMAND} [@var{ARG}] +@end example + +@var{TARGET} specifies the target of the command, usually the name of +the filter class or a specific filter instance name. + +@var{COMMAND} specifies the name of the command for the target filter. + +@var{ARG} is optional and specifies the optional argument list for the +given @var{COMMAND}. + +Upon reception, the message is processed and the corresponding command +is injected into the filtergraph. Depending on the result, the filter +will send a reply to the client, adopting the format: +@example +@var{ERROR_CODE} @var{ERROR_REASON} +@var{MESSAGE} +@end example + +@var{MESSAGE} is optional. + +@subsection Examples + +Look at @file{tools/zmqsend} for an example of a zmq client which can +be used to send commands processed by these filters. + +Consider the following filtergraph generated by @command{ffplay} +@example +ffplay -dumpgraph 1 -f lavfi " +color=s=100x100:c=red [l]; +color=s=100x100:c=blue [r]; +nullsrc=s=200x100, zmq [bg]; +[bg][l] overlay [bg+l]; +[bg+l][r] overlay=x=100 " +@end example + +To change the color of the left side of the video, the following +command can be used: +@example +echo Parsed_color_0 c yellow | tools/zmqsend +@end example + +To change the right side: +@example +echo Parsed_color_1 c pink | tools/zmqsend +@end example + +@c man end MULTIMEDIA FILTERS + +@chapter Multimedia Sources +@c man begin MULTIMEDIA SOURCES + +Below is a description of the currently available multimedia sources. + +@section amovie + +This is the same as @ref{movie} source, except it selects an audio +stream by default. + +@anchor{movie} +@section movie + +Read audio and/or video stream(s) from a movie container. + +It accepts the following parameters: + +@table @option +@item filename +The name of the resource to read (not necessarily a file; it can also be 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 +format is guessed from @var{movie_name} or by probing. + +@item seek_point, sp +Specifies the seek point in seconds. The frames will be output +starting from this seek point. The parameter is evaluated with +@code{av_strtod}, so the numerical value may be suffixed by an IS +postfix. The default value is "0". + +@item streams, s +Specifies the streams to read. Several streams can be specified, +separated by "+". The source will then have as many outputs, in the +same order. The syntax is explained in the ``Stream specifiers'' +section in the ffmpeg manual. Two special names, "dv" and "da" specify +respectively the default (best suited) video and audio stream. Default +is "dv", or "da" if the filter is called as "amovie". + +@item stream_index, si +Specifies the index of the video stream to read. If the value is -1, +the most suitable video stream will be automatically selected. The default +value is "-1". Deprecated. If the filter is called "amovie", it will select +audio instead of video. + +@item loop +Specifies how many times to read the stream in sequence. +If the value is less than 1, the stream will be read again and again. +Default value is "1". + +Note that when the movie is looped the source timestamps are not +changed, so it will generate non monotonically increasing timestamps. +@end table + +It allows overlaying a second video on top of the main input of +a filtergraph, as shown in this graph: +@example +input -----------> deltapts0 --> overlay --> output + ^ + | +movie --> scale--> deltapts1 -------+ +@end example +@subsection Examples + +@itemize +@item +Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it +on top of the input labelled "in": +@example +movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over]; +[in] setpts=PTS-STARTPTS [main]; +[main][over] overlay=16:16 [out] +@end example + +@item +Read from a video4linux2 device, and overlay it on top of the input +labelled "in": +@example +movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over]; +[in] setpts=PTS-STARTPTS [main]; +[main][over] overlay=16:16 [out] +@end example + +@item +Read the first video stream and the audio stream with id 0x81 from +dvd.vob; the video is connected to the pad named "video" and the audio is +connected to the pad named "audio": +@example +movie=dvd.vob:s=v:0+#0x81 [video] [audio] +@end example +@end itemize + +@c man end MULTIMEDIA SOURCES |