1 @chapter Filtering Introduction
2 @c man begin FILTERING INTRODUCTION
4 Filtering in FFmpeg is enabled through the libavfilter library.
6 In libavfilter, a filter can have multiple inputs and multiple
8 To illustrate the sorts of things that are possible, we consider the
13 input --> split ---------------------> overlay --> output
16 +-----> crop --> vflip -------+
19 This filtergraph splits the input stream in two streams, then sends one
20 stream through the crop filter and the vflip filter, before merging it
21 back with the other stream by overlaying it on top. You can use the
22 following command to achieve this:
25 ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT
28 The result will be that the top half of the video is mirrored
29 onto the bottom half of the output video.
31 Filters in the same linear chain are separated by commas, and distinct
32 linear chains of filters are separated by semicolons. In our example,
33 @var{crop,vflip} are in one linear chain, @var{split} and
34 @var{overlay} are separately in another. The points where the linear
35 chains join are labelled by names enclosed in square brackets. In the
36 example, the split filter generates two outputs that are associated to
37 the labels @var{[main]} and @var{[tmp]}.
39 The stream sent to the second output of @var{split}, labelled as
40 @var{[tmp]}, is processed through the @var{crop} filter, which crops
41 away the lower half part of the video, and then vertically flipped. The
42 @var{overlay} filter takes in input the first unchanged output of the
43 split filter (which was labelled as @var{[main]}), and overlay on its
44 lower half the output generated by the @var{crop,vflip} filterchain.
46 Some filters take in input a list of parameters: they are specified
47 after the filter name and an equal sign, and are separated from each other
50 There exist so-called @var{source filters} that do not have an
51 audio/video input, and @var{sink filters} that will not have audio/video
54 @c man end FILTERING INTRODUCTION
57 @c man begin GRAPH2DOT
59 The @file{graph2dot} program included in the FFmpeg @file{tools}
60 directory can be used to parse a filtergraph description and issue a
61 corresponding textual representation in the dot language.
68 to see how to use @file{graph2dot}.
70 You can then pass the dot description to the @file{dot} program (from
71 the graphviz suite of programs) and obtain a graphical representation
74 For example the sequence of commands:
76 echo @var{GRAPH_DESCRIPTION} | \
77 tools/graph2dot -o graph.tmp && \
78 dot -Tpng graph.tmp -o graph.png && \
82 can be used to create and display an image representing the graph
83 described by the @var{GRAPH_DESCRIPTION} string. Note that this string must be
84 a complete self-contained graph, with its inputs and outputs explicitly defined.
85 For example if your command line is of the form:
87 ffmpeg -i infile -vf scale=640:360 outfile
89 your @var{GRAPH_DESCRIPTION} string will need to be of the form:
91 nullsrc,scale=640:360,nullsink
93 you may also need to set the @var{nullsrc} parameters and add a @var{format}
94 filter in order to simulate a specific input file.
98 @chapter Filtergraph description
99 @c man begin FILTERGRAPH DESCRIPTION
101 A filtergraph is a directed graph of connected filters. It can contain
102 cycles, and there can be multiple links between a pair of
103 filters. Each link has one input pad on one side connecting it to one
104 filter from which it takes its input, and one output pad on the other
105 side connecting it to one filter accepting its output.
107 Each filter in a filtergraph is an instance of a filter class
108 registered in the application, which defines the features and the
109 number of input and output pads of the filter.
111 A filter with no input pads is called a "source", and a filter with no
112 output pads is called a "sink".
114 @anchor{Filtergraph syntax}
115 @section Filtergraph syntax
117 A filtergraph has a textual representation, which is recognized by the
118 @option{-filter}/@option{-vf}/@option{-af} and
119 @option{-filter_complex} options in @command{ffmpeg} and
120 @option{-vf}/@option{-af} in @command{ffplay}, and by the
121 @code{avfilter_graph_parse_ptr()} function defined in
122 @file{libavfilter/avfilter.h}.
124 A filterchain consists of a sequence of connected filters, each one
125 connected to the previous one in the sequence. A filterchain is
126 represented by a list of ","-separated filter descriptions.
128 A filtergraph consists of a sequence of filterchains. A sequence of
129 filterchains is represented by a list of ";"-separated filterchain
132 A filter is represented by a string of the form:
133 [@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}]
135 @var{filter_name} is the name of the filter class of which the
136 described filter is an instance of, and has to be the name of one of
137 the filter classes registered in the program.
138 The name of the filter class is optionally followed by a string
141 @var{arguments} is a string which contains the parameters used to
142 initialize the filter instance. It may have one of two forms:
146 A ':'-separated list of @var{key=value} pairs.
149 A ':'-separated list of @var{value}. In this case, the keys are assumed to be
150 the option names in the order they are declared. E.g. the @code{fade} filter
151 declares three options in this order -- @option{type}, @option{start_frame} and
152 @option{nb_frames}. Then the parameter list @var{in:0:30} means that the value
153 @var{in} is assigned to the option @option{type}, @var{0} to
154 @option{start_frame} and @var{30} to @option{nb_frames}.
157 A ':'-separated list of mixed direct @var{value} and long @var{key=value}
158 pairs. The direct @var{value} must precede the @var{key=value} pairs, and
159 follow the same constraints order of the previous point. The following
160 @var{key=value} pairs can be set in any preferred order.
164 If the option value itself is a list of items (e.g. the @code{format} filter
165 takes a list of pixel formats), the items in the list are usually separated by
168 The list of arguments can be quoted using the character @samp{'} as initial
169 and ending mark, and the character @samp{\} for escaping the characters
170 within the quoted text; otherwise the argument string is considered
171 terminated when the next special character (belonging to the set
172 @samp{[]=;,}) is encountered.
174 The name and arguments of the filter are optionally preceded and
175 followed by a list of link labels.
176 A link label allows one to name a link and associate it to a filter output
177 or input pad. The preceding labels @var{in_link_1}
178 ... @var{in_link_N}, are associated to the filter input pads,
179 the following labels @var{out_link_1} ... @var{out_link_M}, are
180 associated to the output pads.
182 When two link labels with the same name are found in the
183 filtergraph, a link between the corresponding input and output pad is
186 If an output pad is not labelled, it is linked by default to the first
187 unlabelled input pad of the next filter in the filterchain.
188 For example in the filterchain
190 nullsrc, split[L1], [L2]overlay, nullsink
192 the split filter instance has two output pads, and the overlay filter
193 instance two input pads. The first output pad of split is labelled
194 "L1", the first input pad of overlay is labelled "L2", and the second
195 output pad of split is linked to the second input pad of overlay,
196 which are both unlabelled.
198 In a filter description, if the input label of the first filter is not
199 specified, "in" is assumed; if the output label of the last filter is not
200 specified, "out" is assumed.
202 In a complete filterchain all the unlabelled filter input and output
203 pads must be connected. A filtergraph is considered valid if all the
204 filter input and output pads of all the filterchains are connected.
206 Libavfilter will automatically insert @ref{scale} filters where format
207 conversion is required. It is possible to specify swscale flags
208 for those automatically inserted scalers by prepending
209 @code{sws_flags=@var{flags};}
210 to the filtergraph description.
212 Here is a BNF description of the filtergraph syntax:
214 @var{NAME} ::= sequence of alphanumeric characters and '_'
215 @var{LINKLABEL} ::= "[" @var{NAME} "]"
216 @var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
217 @var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted)
218 @var{FILTER} ::= [@var{LINKLABELS}] @var{NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]
219 @var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]
220 @var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
223 @section Notes on filtergraph escaping
225 Filtergraph description composition entails several levels of
226 escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping"
227 section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more
228 information about the employed escaping procedure.
230 A first level escaping affects the content of each filter option
231 value, which may contain the special character @code{:} used to
232 separate values, or one of the escaping characters @code{\'}.
234 A second level escaping affects the whole filter description, which
235 may contain the escaping characters @code{\'} or the special
236 characters @code{[],;} used by the filtergraph description.
238 Finally, when you specify a filtergraph on a shell commandline, you
239 need to perform a third level escaping for the shell special
240 characters contained within it.
242 For example, consider the following string to be embedded in
243 the @ref{drawtext} filter description @option{text} value:
245 this is a 'string': may contain one, or more, special characters
248 This string contains the @code{'} special escaping character, and the
249 @code{:} special character, so it needs to be escaped in this way:
251 text=this is a \'string\'\: may contain one, or more, special characters
254 A second level of escaping is required when embedding the filter
255 description in a filtergraph description, in order to escape all the
256 filtergraph special characters. Thus the example above becomes:
258 drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
260 (note that in addition to the @code{\'} escaping special characters,
261 also @code{,} needs to be escaped).
263 Finally an additional level of escaping is needed when writing the
264 filtergraph description in a shell command, which depends on the
265 escaping rules of the adopted shell. For example, assuming that
266 @code{\} is special and needs to be escaped with another @code{\}, the
267 previous string will finally result in:
269 -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
272 @chapter Timeline editing
274 Some filters support a generic @option{enable} option. For the filters
275 supporting timeline editing, this option can be set to an expression which is
276 evaluated before sending a frame to the filter. If the evaluation is non-zero,
277 the filter will be enabled, otherwise the frame will be sent unchanged to the
278 next filter in the filtergraph.
280 The expression accepts the following values:
283 timestamp expressed in seconds, NAN if the input timestamp is unknown
286 sequential number of the input frame, starting from 0
289 the position in the file of the input frame, NAN if unknown
293 width and height of the input frame if video
296 Additionally, these filters support an @option{enable} command that can be used
297 to re-define the expression.
299 Like any other filtering option, the @option{enable} option follows the same
302 For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3
303 minutes, and a @ref{curves} filter starting at 3 seconds:
305 smartblur = enable='between(t,10,3*60)',
306 curves = enable='gte(t,3)' : preset=cross_process
309 @c man end FILTERGRAPH DESCRIPTION
311 @chapter Audio Filters
312 @c man begin AUDIO FILTERS
314 When you configure your FFmpeg build, you can disable any of the
315 existing filters using @code{--disable-filters}.
316 The configure output will show the audio filters included in your
319 Below is a description of the currently available audio filters.
323 Delay one or more audio channels.
325 Samples in delayed channel are filled with silence.
327 The filter accepts the following option:
331 Set list of delays in milliseconds for each channel separated by '|'.
332 At least one delay greater than 0 should be provided.
333 Unused delays will be silently ignored. If number of given delays is
334 smaller than number of channels all remaining channels will not be delayed.
341 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
342 the second channel (and any other channels that may be present) unchanged.
350 Apply echoing to the input audio.
352 Echoes are reflected sound and can occur naturally amongst mountains
353 (and sometimes large buildings) when talking or shouting; digital echo
354 effects emulate this behaviour and are often used to help fill out the
355 sound of a single instrument or vocal. The time difference between the
356 original signal and the reflection is the @code{delay}, and the
357 loudness of the reflected signal is the @code{decay}.
358 Multiple echoes can have different delays and decays.
360 A description of the accepted parameters follows.
364 Set input gain of reflected signal. Default is @code{0.6}.
367 Set output gain of reflected signal. Default is @code{0.3}.
370 Set list of time intervals in milliseconds between original signal and reflections
371 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
372 Default is @code{1000}.
375 Set list of loudnesses of reflected signals separated by '|'.
376 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
377 Default is @code{0.5}.
384 Make it sound as if there are twice as many instruments as are actually playing:
386 aecho=0.8:0.88:60:0.4
390 If delay is very short, then it sound like a (metallic) robot playing music:
396 A longer delay will sound like an open air concert in the mountains:
398 aecho=0.8:0.9:1000:0.3
402 Same as above but with one more mountain:
404 aecho=0.8:0.9:1000|1800:0.3|0.25
410 Modify an audio signal according to the specified expressions.
412 This filter accepts one or more expressions (one for each channel),
413 which are evaluated and used to modify a corresponding audio signal.
415 It accepts the following parameters:
419 Set the '|'-separated expressions list for each separate channel. If
420 the number of input channels is greater than the number of
421 expressions, the last specified expression is used for the remaining
424 @item channel_layout, c
425 Set output channel layout. If not specified, the channel layout is
426 specified by the number of expressions. If set to @samp{same}, it will
427 use by default the same input channel layout.
430 Each expression in @var{exprs} can contain the following constants and functions:
434 channel number of the current expression
437 number of the evaluated sample, starting from 0
443 time of the evaluated sample expressed in seconds
446 @item nb_out_channels
447 input and output number of channels
450 the value of input channel with number @var{CH}
453 Note: this filter is slow. For faster processing you should use a
462 aeval=val(ch)/2:c=same
466 Invert phase of the second channel:
474 Apply fade-in/out effect to input audio.
476 A description of the accepted parameters follows.
480 Specify the effect type, can be either @code{in} for fade-in, or
481 @code{out} for a fade-out effect. Default is @code{in}.
483 @item start_sample, ss
484 Specify the number of the start sample for starting to apply the fade
485 effect. Default is 0.
488 Specify the number of samples for which the fade effect has to last. At
489 the end of the fade-in effect the output audio will have the same
490 volume as the input audio, at the end of the fade-out transition
491 the output audio will be silence. Default is 44100.
494 Specify the start time of the fade effect. Default is 0.
495 The value must be specified as a time duration; see
496 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
497 for the accepted syntax.
498 If set this option is used instead of @var{start_sample}.
501 Specify the duration of the fade effect. See
502 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
503 for the accepted syntax.
504 At the end of the fade-in effect the output audio will have the same
505 volume as the input audio, at the end of the fade-out transition
506 the output audio will be silence.
507 By default the duration is determined by @var{nb_samples}.
508 If set this option is used instead of @var{nb_samples}.
511 Set curve for fade transition.
513 It accepts the following values:
516 select triangular, linear slope (default)
518 select quarter of sine wave
520 select half of sine wave
522 select exponential sine wave
526 select inverted parabola
540 select inverted quarter of sine wave
542 select inverted half of sine wave
544 select double-exponential seat
546 select double-exponential sigmoid
554 Fade in first 15 seconds of audio:
560 Fade out last 25 seconds of a 900 seconds audio:
562 afade=t=out:st=875:d=25
569 Set output format constraints for the input audio. The framework will
570 negotiate the most appropriate format to minimize conversions.
572 It accepts the following parameters:
576 A '|'-separated list of requested sample formats.
579 A '|'-separated list of requested sample rates.
581 @item channel_layouts
582 A '|'-separated list of requested channel layouts.
584 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
585 for the required syntax.
588 If a parameter is omitted, all values are allowed.
590 Force the output to either unsigned 8-bit or signed 16-bit stereo
592 aformat=sample_fmts=u8|s16:channel_layouts=stereo
597 Apply a two-pole all-pass filter with central frequency (in Hz)
598 @var{frequency}, and filter-width @var{width}.
599 An all-pass filter changes the audio's frequency to phase relationship
600 without changing its frequency to amplitude relationship.
602 The filter accepts the following options:
609 Set method to specify band-width of filter.
622 Specify the band-width of a filter in width_type units.
627 Merge two or more audio streams into a single multi-channel stream.
629 The filter accepts the following options:
634 Set the number of inputs. Default is 2.
638 If the channel layouts of the inputs are disjoint, and therefore compatible,
639 the channel layout of the output will be set accordingly and the channels
640 will be reordered as necessary. If the channel layouts of the inputs are not
641 disjoint, the output will have all the channels of the first input then all
642 the channels of the second input, in that order, and the channel layout of
643 the output will be the default value corresponding to the total number of
646 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
647 is FC+BL+BR, then the output will be in 5.1, with the channels in the
648 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
649 first input, b1 is the first channel of the second input).
651 On the other hand, if both input are in stereo, the output channels will be
652 in the default order: a1, a2, b1, b2, and the channel layout will be
653 arbitrarily set to 4.0, which may or may not be the expected value.
655 All inputs must have the same sample rate, and format.
657 If inputs do not have the same duration, the output will stop with the
664 Merge two mono files into a stereo stream:
666 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
670 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
672 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
678 Mixes multiple audio inputs into a single output.
680 Note that this filter only supports float samples (the @var{amerge}
681 and @var{pan} audio filters support many formats). If the @var{amix}
682 input has integer samples then @ref{aresample} will be automatically
683 inserted to perform the conversion to float samples.
687 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
689 will mix 3 input audio streams to a single output with the same duration as the
690 first input and a dropout transition time of 3 seconds.
692 It accepts the following parameters:
696 The number of inputs. If unspecified, it defaults to 2.
699 How to determine the end-of-stream.
703 The duration of the longest input. (default)
706 The duration of the shortest input.
709 The duration of the first input.
713 @item dropout_transition
714 The transition time, in seconds, for volume renormalization when an input
715 stream ends. The default value is 2 seconds.
721 Pass the audio source unchanged to the output.
725 Pad the end of an audio stream with silence.
727 This can be used together with @command{ffmpeg} @option{-shortest} to
728 extend audio streams to the same length as the video stream.
730 A description of the accepted options follows.
734 Set silence packet size. Default value is 4096.
737 Set the number of samples of silence to add to the end. After the
738 value is reached, the stream is terminated. This option is mutually
739 exclusive with @option{whole_len}.
742 Set the minimum total number of samples in the output audio stream. If
743 the value is longer than the input audio length, silence is added to
744 the end, until the value is reached. This option is mutually exclusive
745 with @option{pad_len}.
748 If neither the @option{pad_len} nor the @option{whole_len} option is
749 set, the filter will add silence to the end of the input stream
756 Add 1024 samples of silence to the end of the input:
762 Make sure the audio output will contain at least 10000 samples, pad
763 the input with silence if required:
769 Use @command{ffmpeg} to pad the audio input with silence, so that the
770 video stream will always result the shortest and will be converted
771 until the end in the output file when using the @option{shortest}
774 ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
779 Add a phasing effect to the input audio.
781 A phaser filter creates series of peaks and troughs in the frequency spectrum.
782 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
784 A description of the accepted parameters follows.
788 Set input gain. Default is 0.4.
791 Set output gain. Default is 0.74
794 Set delay in milliseconds. Default is 3.0.
797 Set decay. Default is 0.4.
800 Set modulation speed in Hz. Default is 0.5.
803 Set modulation type. Default is triangular.
805 It accepts the following values:
815 Resample the input audio to the specified parameters, using the
816 libswresample library. If none are specified then the filter will
817 automatically convert between its input and output.
819 This filter is also able to stretch/squeeze the audio data to make it match
820 the timestamps or to inject silence / cut out audio to make it match the
821 timestamps, do a combination of both or do neither.
823 The filter accepts the syntax
824 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
825 expresses a sample rate and @var{resampler_options} is a list of
826 @var{key}=@var{value} pairs, separated by ":". See the
827 ffmpeg-resampler manual for the complete list of supported options.
833 Resample the input audio to 44100Hz:
839 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
840 samples per second compensation:
846 @section asetnsamples
848 Set the number of samples per each output audio frame.
850 The last output packet may contain a different number of samples, as
851 the filter will flush all the remaining samples when the input audio
854 The filter accepts the following options:
858 @item nb_out_samples, n
859 Set the number of frames per each output audio frame. The number is
860 intended as the number of samples @emph{per each channel}.
861 Default value is 1024.
864 If set to 1, the filter will pad the last audio frame with zeroes, so
865 that the last frame will contain the same number of samples as the
866 previous ones. Default value is 1.
869 For example, to set the number of per-frame samples to 1234 and
870 disable padding for the last frame, use:
872 asetnsamples=n=1234:p=0
877 Set the sample rate without altering the PCM data.
878 This will result in a change of speed and pitch.
880 The filter accepts the following options:
884 Set the output sample rate. Default is 44100 Hz.
889 Show a line containing various information for each input audio frame.
890 The input audio is not modified.
892 The shown line contains a sequence of key/value pairs of the form
893 @var{key}:@var{value}.
895 The following values are shown in the output:
899 The (sequential) number of the input frame, starting from 0.
902 The presentation timestamp of the input frame, in time base units; the time base
903 depends on the filter input pad, and is usually 1/@var{sample_rate}.
906 The presentation timestamp of the input frame in seconds.
909 position of the frame in the input stream, -1 if this information in
910 unavailable and/or meaningless (for example in case of synthetic audio)
919 The sample rate for the audio frame.
922 The number of samples (per channel) in the frame.
925 The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
926 audio, the data is treated as if all the planes were concatenated.
928 @item plane_checksums
929 A list of Adler-32 checksums for each data plane.
935 Display time domain statistical information about the audio channels.
936 Statistics are calculated and displayed for each audio channel and,
937 where applicable, an overall figure is also given.
939 It accepts the following option:
942 Short window length in seconds, used for peak and trough RMS measurement.
943 Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.1 - 10]}.
947 Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
948 where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
951 Available keys for each channel are:
982 For example full key look like this @code{lavfi.astats.1.DC_offset} or
983 this @code{lavfi.astats.Overall.Peak_count}.
985 For description what each key means read bellow.
988 Set number of frame after which stats are going to be recalculated.
992 A description of each shown parameter follows:
996 Mean amplitude displacement from zero.
999 Minimal sample level.
1002 Maximal sample level.
1004 @item Min difference
1005 Minimal difference between two consecutive samples.
1007 @item Max difference
1008 Maximal difference between two consecutive samples.
1010 @item Mean difference
1011 Mean difference between two consecutive samples.
1012 The average of each difference between two consecutive samples.
1016 Standard peak and RMS level measured in dBFS.
1020 Peak and trough values for RMS level measured over a short window.
1023 Standard ratio of peak to RMS level (note: not in dB).
1026 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
1027 (i.e. either @var{Min level} or @var{Max level}).
1030 Number of occasions (not the number of samples) that the signal attained either
1031 @var{Min level} or @var{Max level}.
1034 Overall bit depth of audio. Number of bits used for each sample.
1037 @section astreamsync
1039 Forward two audio streams and control the order the buffers are forwarded.
1041 The filter accepts the following options:
1045 Set the expression deciding which stream should be
1046 forwarded next: if the result is negative, the first stream is forwarded; if
1047 the result is positive or zero, the second stream is forwarded. It can use
1048 the following variables:
1052 number of buffers forwarded so far on each stream
1054 number of samples forwarded so far on each stream
1056 current timestamp of each stream
1059 The default value is @code{t1-t2}, which means to always forward the stream
1060 that has a smaller timestamp.
1063 @subsection Examples
1065 Stress-test @code{amerge} by randomly sending buffers on the wrong
1066 input, while avoiding too much of a desynchronization:
1068 amovie=file.ogg [a] ; amovie=file.mp3 [b] ;
1069 [a] [b] astreamsync=(2*random(1))-1+tanh(5*(t1-t2)) [a2] [b2] ;
1075 Synchronize audio data with timestamps by squeezing/stretching it and/or
1076 dropping samples/adding silence when needed.
1078 This filter is not built by default, please use @ref{aresample} to do squeezing/stretching.
1080 It accepts the following parameters:
1084 Enable stretching/squeezing the data to make it match the timestamps. Disabled
1085 by default. When disabled, time gaps are covered with silence.
1088 The minimum difference between timestamps and audio data (in seconds) to trigger
1089 adding/dropping samples. The default value is 0.1. If you get an imperfect
1090 sync with this filter, try setting this parameter to 0.
1093 The maximum compensation in samples per second. Only relevant with compensate=1.
1094 The default value is 500.
1097 Assume that the first PTS should be this value. The time base is 1 / sample
1098 rate. This allows for padding/trimming at the start of the stream. By default,
1099 no assumption is made about the first frame's expected PTS, so no padding or
1100 trimming is done. For example, this could be set to 0 to pad the beginning with
1101 silence if an audio stream starts after the video stream or to trim any samples
1102 with a negative PTS due to encoder delay.
1110 The filter accepts exactly one parameter, the audio tempo. If not
1111 specified then the filter will assume nominal 1.0 tempo. Tempo must
1112 be in the [0.5, 2.0] range.
1114 @subsection Examples
1118 Slow down audio to 80% tempo:
1124 To speed up audio to 125% tempo:
1132 Trim the input so that the output contains one continuous subpart of the input.
1134 It accepts the following parameters:
1137 Timestamp (in seconds) of the start of the section to keep. I.e. the audio
1138 sample with the timestamp @var{start} will be the first sample in the output.
1141 Specify time of the first audio sample that will be dropped, i.e. the
1142 audio sample immediately preceding the one with the timestamp @var{end} will be
1143 the last sample in the output.
1146 Same as @var{start}, except this option sets the start timestamp in samples
1150 Same as @var{end}, except this option sets the end timestamp in samples instead
1154 The maximum duration of the output in seconds.
1157 The number of the first sample that should be output.
1160 The number of the first sample that should be dropped.
1163 @option{start}, @option{end}, and @option{duration} are expressed as time
1164 duration specifications; see
1165 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
1167 Note that the first two sets of the start/end options and the @option{duration}
1168 option look at the frame timestamp, while the _sample options simply count the
1169 samples that pass through the filter. So start/end_pts and start/end_sample will
1170 give different results when the timestamps are wrong, inexact or do not start at
1171 zero. Also note that this filter does not modify the timestamps. If you wish
1172 to have the output timestamps start at zero, insert the asetpts filter after the
1175 If multiple start or end options are set, this filter tries to be greedy and
1176 keep all samples that match at least one of the specified constraints. To keep
1177 only the part that matches all the constraints at once, chain multiple atrim
1180 The defaults are such that all the input is kept. So it is possible to set e.g.
1181 just the end values to keep everything before the specified time.
1186 Drop everything except the second minute of input:
1188 ffmpeg -i INPUT -af atrim=60:120
1192 Keep only the first 1000 samples:
1194 ffmpeg -i INPUT -af atrim=end_sample=1000
1201 Apply a two-pole Butterworth band-pass filter with central
1202 frequency @var{frequency}, and (3dB-point) band-width width.
1203 The @var{csg} option selects a constant skirt gain (peak gain = Q)
1204 instead of the default: constant 0dB peak gain.
1205 The filter roll off at 6dB per octave (20dB per decade).
1207 The filter accepts the following options:
1211 Set the filter's central frequency. Default is @code{3000}.
1214 Constant skirt gain if set to 1. Defaults to 0.
1217 Set method to specify band-width of filter.
1230 Specify the band-width of a filter in width_type units.
1235 Apply a two-pole Butterworth band-reject filter with central
1236 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
1237 The filter roll off at 6dB per octave (20dB per decade).
1239 The filter accepts the following options:
1243 Set the filter's central frequency. Default is @code{3000}.
1246 Set method to specify band-width of filter.
1259 Specify the band-width of a filter in width_type units.
1264 Boost or cut the bass (lower) frequencies of the audio using a two-pole
1265 shelving filter with a response similar to that of a standard
1266 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
1268 The filter accepts the following options:
1272 Give the gain at 0 Hz. Its useful range is about -20
1273 (for a large cut) to +20 (for a large boost).
1274 Beware of clipping when using a positive gain.
1277 Set the filter's central frequency and so can be used
1278 to extend or reduce the frequency range to be boosted or cut.
1279 The default value is @code{100} Hz.
1282 Set method to specify band-width of filter.
1295 Determine how steep is the filter's shelf transition.
1300 Apply a biquad IIR filter with the given coefficients.
1301 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
1302 are the numerator and denominator coefficients respectively.
1305 Bauer stereo to binaural transformation, which improves headphone listening of
1306 stereo audio records.
1308 It accepts the following parameters:
1312 Pre-defined crossfeed level.
1316 Default level (fcut=700, feed=50).
1319 Chu Moy circuit (fcut=700, feed=60).
1322 Jan Meier circuit (fcut=650, feed=95).
1327 Cut frequency (in Hz).
1336 Remap input channels to new locations.
1338 It accepts the following parameters:
1340 @item channel_layout
1341 The channel layout of the output stream.
1344 Map channels from input to output. The argument is a '|'-separated list of
1345 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
1346 @var{in_channel} form. @var{in_channel} can be either the name of the input
1347 channel (e.g. FL for front left) or its index in the input channel layout.
1348 @var{out_channel} is the name of the output channel or its index in the output
1349 channel layout. If @var{out_channel} is not given then it is implicitly an
1350 index, starting with zero and increasing by one for each mapping.
1353 If no mapping is present, the filter will implicitly map input channels to
1354 output channels, preserving indices.
1356 For example, assuming a 5.1+downmix input MOV file,
1358 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
1360 will create an output WAV file tagged as stereo from the downmix channels of
1363 To fix a 5.1 WAV improperly encoded in AAC's native channel order
1365 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
1368 @section channelsplit
1370 Split each channel from an input audio stream into a separate output stream.
1372 It accepts the following parameters:
1374 @item channel_layout
1375 The channel layout of the input stream. The default is "stereo".
1378 For example, assuming a stereo input MP3 file,
1380 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
1382 will create an output Matroska file with two audio streams, one containing only
1383 the left channel and the other the right channel.
1385 Split a 5.1 WAV file into per-channel files:
1387 ffmpeg -i in.wav -filter_complex
1388 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
1389 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
1390 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
1395 Add a chorus effect to the audio.
1397 Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
1399 Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
1400 constant, with chorus, it is varied using using sinusoidal or triangular modulation.
1401 The modulation depth defines the range the modulated delay is played before or after
1402 the delay. Hence the delayed sound will sound slower or faster, that is the delayed
1403 sound tuned around the original one, like in a chorus where some vocals are slightly
1406 It accepts the following parameters:
1409 Set input gain. Default is 0.4.
1412 Set output gain. Default is 0.4.
1415 Set delays. A typical delay is around 40ms to 60ms.
1427 @subsection Examples
1433 chorus=0.7:0.9:55:0.4:0.25:2
1439 chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
1443 Fuller sounding chorus with three delays:
1445 chorus=0.5:0.9:50|60|40:0.4|0.32|0.3:0.25|0.4|0.3:2|2.3|1.3
1450 Compress or expand the audio's dynamic range.
1452 It accepts the following parameters:
1458 A list of times in seconds for each channel over which the instantaneous level
1459 of the input signal is averaged to determine its volume. @var{attacks} refers to
1460 increase of volume and @var{decays} refers to decrease of volume. For most
1461 situations, the attack time (response to the audio getting louder) should be
1462 shorter than the decay time, because the human ear is more sensitive to sudden
1463 loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
1464 a typical value for decay is 0.8 seconds.
1465 If specified number of attacks & decays is lower than number of channels, the last
1466 set attack/decay will be used for all remaining channels.
1469 A list of points for the transfer function, specified in dB relative to the
1470 maximum possible signal amplitude. Each key points list must be defined using
1471 the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
1472 @code{x0/y0 x1/y1 x2/y2 ....}
1474 The input values must be in strictly increasing order but the transfer function
1475 does not have to be monotonically rising. The point @code{0/0} is assumed but
1476 may be overridden (by @code{0/out-dBn}). Typical values for the transfer
1477 function are @code{-70/-70|-60/-20}.
1480 Set the curve radius in dB for all joints. It defaults to 0.01.
1483 Set the additional gain in dB to be applied at all points on the transfer
1484 function. This allows for easy adjustment of the overall gain.
1488 Set an initial volume, in dB, to be assumed for each channel when filtering
1489 starts. This permits the user to supply a nominal level initially, so that, for
1490 example, a very large gain is not applied to initial signal levels before the
1491 companding has begun to operate. A typical value for audio which is initially
1492 quiet is -90 dB. It defaults to 0.
1495 Set a delay, in seconds. The input audio is analyzed immediately, but audio is
1496 delayed before being fed to the volume adjuster. Specifying a delay
1497 approximately equal to the attack/decay times allows the filter to effectively
1498 operate in predictive rather than reactive mode. It defaults to 0.
1502 @subsection Examples
1506 Make music with both quiet and loud passages suitable for listening to in a
1509 compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
1512 Another example for audio with whisper and explosion parts:
1514 compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
1518 A noise gate for when the noise is at a lower level than the signal:
1520 compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
1524 Here is another noise gate, this time for when the noise is at a higher level
1525 than the signal (making it, in some ways, similar to squelch):
1527 compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
1532 Apply a DC shift to the audio.
1534 This can be useful to remove a DC offset (caused perhaps by a hardware problem
1535 in the recording chain) from the audio. The effect of a DC offset is reduced
1536 headroom and hence volume. The @ref{astats} filter can be used to determine if
1537 a signal has a DC offset.
1541 Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
1545 Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
1546 used to prevent clipping.
1550 Dynamic Audio Normalizer.
1552 This filter applies a certain amount of gain to the input audio in order
1553 to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
1554 contrast to more "simple" normalization algorithms, the Dynamic Audio
1555 Normalizer *dynamically* re-adjusts the gain factor to the input audio.
1556 This allows for applying extra gain to the "quiet" sections of the audio
1557 while avoiding distortions or clipping the "loud" sections. In other words:
1558 The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
1559 sections, in the sense that the volume of each section is brought to the
1560 same target level. Note, however, that the Dynamic Audio Normalizer achieves
1561 this goal *without* applying "dynamic range compressing". It will retain 100%
1562 of the dynamic range *within* each section of the audio file.
1566 Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
1567 Default is 500 milliseconds.
1568 The Dynamic Audio Normalizer processes the input audio in small chunks,
1569 referred to as frames. This is required, because a peak magnitude has no
1570 meaning for just a single sample value. Instead, we need to determine the
1571 peak magnitude for a contiguous sequence of sample values. While a "standard"
1572 normalizer would simply use the peak magnitude of the complete file, the
1573 Dynamic Audio Normalizer determines the peak magnitude individually for each
1574 frame. The length of a frame is specified in milliseconds. By default, the
1575 Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
1576 been found to give good results with most files.
1577 Note that the exact frame length, in number of samples, will be determined
1578 automatically, based on the sampling rate of the individual input audio file.
1581 Set the Gaussian filter window size. In range from 3 to 301, must be odd
1582 number. Default is 31.
1583 Probably the most important parameter of the Dynamic Audio Normalizer is the
1584 @code{window size} of the Gaussian smoothing filter. The filter's window size
1585 is specified in frames, centered around the current frame. For the sake of
1586 simplicity, this must be an odd number. Consequently, the default value of 31
1587 takes into account the current frame, as well as the 15 preceding frames and
1588 the 15 subsequent frames. Using a larger window results in a stronger
1589 smoothing effect and thus in less gain variation, i.e. slower gain
1590 adaptation. Conversely, using a smaller window results in a weaker smoothing
1591 effect and thus in more gain variation, i.e. faster gain adaptation.
1592 In other words, the more you increase this value, the more the Dynamic Audio
1593 Normalizer will behave like a "traditional" normalization filter. On the
1594 contrary, the more you decrease this value, the more the Dynamic Audio
1595 Normalizer will behave like a dynamic range compressor.
1598 Set the target peak value. This specifies the highest permissible magnitude
1599 level for the normalized audio input. This filter will try to approach the
1600 target peak magnitude as closely as possible, but at the same time it also
1601 makes sure that the normalized signal will never exceed the peak magnitude.
1602 A frame's maximum local gain factor is imposed directly by the target peak
1603 magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
1604 It is not recommended to go above this value.
1607 Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
1608 The Dynamic Audio Normalizer determines the maximum possible (local) gain
1609 factor for each input frame, i.e. the maximum gain factor that does not
1610 result in clipping or distortion. The maximum gain factor is determined by
1611 the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
1612 additionally bounds the frame's maximum gain factor by a predetermined
1613 (global) maximum gain factor. This is done in order to avoid excessive gain
1614 factors in "silent" or almost silent frames. By default, the maximum gain
1615 factor is 10.0, For most inputs the default value should be sufficient and
1616 it usually is not recommended to increase this value. Though, for input
1617 with an extremely low overall volume level, it may be necessary to allow even
1618 higher gain factors. Note, however, that the Dynamic Audio Normalizer does
1619 not simply apply a "hard" threshold (i.e. cut off values above the threshold).
1620 Instead, a "sigmoid" threshold function will be applied. This way, the
1621 gain factors will smoothly approach the threshold value, but never exceed that
1625 Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
1626 By default, the Dynamic Audio Normalizer performs "peak" normalization.
1627 This means that the maximum local gain factor for each frame is defined
1628 (only) by the frame's highest magnitude sample. This way, the samples can
1629 be amplified as much as possible without exceeding the maximum signal
1630 level, i.e. without clipping. Optionally, however, the Dynamic Audio
1631 Normalizer can also take into account the frame's root mean square,
1632 abbreviated RMS. In electrical engineering, the RMS is commonly used to
1633 determine the power of a time-varying signal. It is therefore considered
1634 that the RMS is a better approximation of the "perceived loudness" than
1635 just looking at the signal's peak magnitude. Consequently, by adjusting all
1636 frames to a constant RMS value, a uniform "perceived loudness" can be
1637 established. If a target RMS value has been specified, a frame's local gain
1638 factor is defined as the factor that would result in exactly that RMS value.
1639 Note, however, that the maximum local gain factor is still restricted by the
1640 frame's highest magnitude sample, in order to prevent clipping.
1643 Enable channels coupling. By default is enabled.
1644 By default, the Dynamic Audio Normalizer will amplify all channels by the same
1645 amount. This means the same gain factor will be applied to all channels, i.e.
1646 the maximum possible gain factor is determined by the "loudest" channel.
1647 However, in some recordings, it may happen that the volume of the different
1648 channels is uneven, e.g. one channel may be "quieter" than the other one(s).
1649 In this case, this option can be used to disable the channel coupling. This way,
1650 the gain factor will be determined independently for each channel, depending
1651 only on the individual channel's highest magnitude sample. This allows for
1652 harmonizing the volume of the different channels.
1655 Enable DC bias correction. By default is disabled.
1656 An audio signal (in the time domain) is a sequence of sample values.
1657 In the Dynamic Audio Normalizer these sample values are represented in the
1658 -1.0 to 1.0 range, regardless of the original input format. Normally, the
1659 audio signal, or "waveform", should be centered around the zero point.
1660 That means if we calculate the mean value of all samples in a file, or in a
1661 single frame, then the result should be 0.0 or at least very close to that
1662 value. If, however, there is a significant deviation of the mean value from
1663 0.0, in either positive or negative direction, this is referred to as a
1664 DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
1665 Audio Normalizer provides optional DC bias correction.
1666 With DC bias correction enabled, the Dynamic Audio Normalizer will determine
1667 the mean value, or "DC correction" offset, of each input frame and subtract
1668 that value from all of the frame's sample values which ensures those samples
1669 are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
1670 boundaries, the DC correction offset values will be interpolated smoothly
1671 between neighbouring frames.
1674 Enable alternative boundary mode. By default is disabled.
1675 The Dynamic Audio Normalizer takes into account a certain neighbourhood
1676 around each frame. This includes the preceding frames as well as the
1677 subsequent frames. However, for the "boundary" frames, located at the very
1678 beginning and at the very end of the audio file, not all neighbouring
1679 frames are available. In particular, for the first few frames in the audio
1680 file, the preceding frames are not known. And, similarly, for the last few
1681 frames in the audio file, the subsequent frames are not known. Thus, the
1682 question arises which gain factors should be assumed for the missing frames
1683 in the "boundary" region. The Dynamic Audio Normalizer implements two modes
1684 to deal with this situation. The default boundary mode assumes a gain factor
1685 of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
1686 "fade out" at the beginning and at the end of the input, respectively.
1689 Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
1690 By default, the Dynamic Audio Normalizer does not apply "traditional"
1691 compression. This means that signal peaks will not be pruned and thus the
1692 full dynamic range will be retained within each local neighbourhood. However,
1693 in some cases it may be desirable to combine the Dynamic Audio Normalizer's
1694 normalization algorithm with a more "traditional" compression.
1695 For this purpose, the Dynamic Audio Normalizer provides an optional compression
1696 (thresholding) function. If (and only if) the compression feature is enabled,
1697 all input frames will be processed by a soft knee thresholding function prior
1698 to the actual normalization process. Put simply, the thresholding function is
1699 going to prune all samples whose magnitude exceeds a certain threshold value.
1700 However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
1701 value. Instead, the threshold value will be adjusted for each individual
1703 In general, smaller parameters result in stronger compression, and vice versa.
1704 Values below 3.0 are not recommended, because audible distortion may appear.
1709 Make audio easier to listen to on headphones.
1711 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
1712 so that when listened to on headphones the stereo image is moved from
1713 inside your head (standard for headphones) to outside and in front of
1714 the listener (standard for speakers).
1720 Apply a two-pole peaking equalisation (EQ) filter. With this
1721 filter, the signal-level at and around a selected frequency can
1722 be increased or decreased, whilst (unlike bandpass and bandreject
1723 filters) that at all other frequencies is unchanged.
1725 In order to produce complex equalisation curves, this filter can
1726 be given several times, each with a different central frequency.
1728 The filter accepts the following options:
1732 Set the filter's central frequency in Hz.
1735 Set method to specify band-width of filter.
1748 Specify the band-width of a filter in width_type units.
1751 Set the required gain or attenuation in dB.
1752 Beware of clipping when using a positive gain.
1755 @subsection Examples
1758 Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
1760 equalizer=f=1000:width_type=h:width=200:g=-10
1764 Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
1766 equalizer=f=1000:width_type=q:width=1:g=2,equalizer=f=100:width_type=q:width=2:g=-5
1771 Apply a flanging effect to the audio.
1773 The filter accepts the following options:
1777 Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
1780 Set added swep delay in milliseconds. Range from 0 to 10. Default value is 2.
1783 Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
1787 Set percentage of delayed signal mixed with original. Range from 0 to 100.
1788 Default value is 71.
1791 Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
1794 Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
1795 Default value is @var{sinusoidal}.
1798 Set swept wave percentage-shift for multi channel. Range from 0 to 100.
1799 Default value is 25.
1802 Set delay-line interpolation, @var{linear} or @var{quadratic}.
1803 Default is @var{linear}.
1808 Apply a high-pass filter with 3dB point frequency.
1809 The filter can be either single-pole, or double-pole (the default).
1810 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
1812 The filter accepts the following options:
1816 Set frequency in Hz. Default is 3000.
1819 Set number of poles. Default is 2.
1822 Set method to specify band-width of filter.
1835 Specify the band-width of a filter in width_type units.
1836 Applies only to double-pole filter.
1837 The default is 0.707q and gives a Butterworth response.
1842 Join multiple input streams into one multi-channel stream.
1844 It accepts the following parameters:
1848 The number of input streams. It defaults to 2.
1850 @item channel_layout
1851 The desired output channel layout. It defaults to stereo.
1854 Map channels from inputs to output. The argument is a '|'-separated list of
1855 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
1856 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
1857 can be either the name of the input channel (e.g. FL for front left) or its
1858 index in the specified input stream. @var{out_channel} is the name of the output
1862 The filter will attempt to guess the mappings when they are not specified
1863 explicitly. It does so by first trying to find an unused matching input channel
1864 and if that fails it picks the first unused input channel.
1866 Join 3 inputs (with properly set channel layouts):
1868 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
1871 Build a 5.1 output from 6 single-channel streams:
1873 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
1874 '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'
1880 Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
1882 To enable compilation of this filter you need to configure FFmpeg with
1883 @code{--enable-ladspa}.
1887 Specifies the name of LADSPA plugin library to load. If the environment
1888 variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
1889 each one of the directories specified by the colon separated list in
1890 @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
1891 this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
1892 @file{/usr/lib/ladspa/}.
1895 Specifies the plugin within the library. Some libraries contain only
1896 one plugin, but others contain many of them. If this is not set filter
1897 will list all available plugins within the specified library.
1900 Set the '|' separated list of controls which are zero or more floating point
1901 values that determine the behavior of the loaded plugin (for example delay,
1903 Controls need to be defined using the following syntax:
1904 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
1905 @var{valuei} is the value set on the @var{i}-th control.
1906 If @option{controls} is set to @code{help}, all available controls and
1907 their valid ranges are printed.
1909 @item sample_rate, s
1910 Specify the sample rate, default to 44100. Only used if plugin have
1914 Set the number of samples per channel per each output frame, default
1915 is 1024. Only used if plugin have zero inputs.
1918 Set the minimum duration of the sourced audio. See
1919 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1920 for the accepted syntax.
1921 Note that the resulting duration may be greater than the specified duration,
1922 as the generated audio is always cut at the end of a complete frame.
1923 If not specified, or the expressed duration is negative, the audio is
1924 supposed to be generated forever.
1925 Only used if plugin have zero inputs.
1929 @subsection Examples
1933 List all available plugins within amp (LADSPA example plugin) library:
1939 List all available controls and their valid ranges for @code{vcf_notch}
1940 plugin from @code{VCF} library:
1942 ladspa=f=vcf:p=vcf_notch:c=help
1946 Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
1949 ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
1953 Add reverberation to the audio using TAP-plugins
1954 (Tom's Audio Processing plugins):
1956 ladspa=file=tap_reverb:tap_reverb
1960 Generate white noise, with 0.2 amplitude:
1962 ladspa=file=cmt:noise_source_white:c=c0=.2
1966 Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
1967 @code{C* Audio Plugin Suite} (CAPS) library:
1969 ladspa=file=caps:Click:c=c1=20'
1973 Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
1975 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
1979 @subsection Commands
1981 This filter supports the following commands:
1984 Modify the @var{N}-th control value.
1986 If the specified value is not valid, it is ignored and prior one is kept.
1991 Apply a low-pass filter with 3dB point frequency.
1992 The filter can be either single-pole or double-pole (the default).
1993 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
1995 The filter accepts the following options:
1999 Set frequency in Hz. Default is 500.
2002 Set number of poles. Default is 2.
2005 Set method to specify band-width of filter.
2018 Specify the band-width of a filter in width_type units.
2019 Applies only to double-pole filter.
2020 The default is 0.707q and gives a Butterworth response.
2025 Mix channels with specific gain levels. The filter accepts the output
2026 channel layout followed by a set of channels definitions.
2028 This filter is also designed to efficiently remap the channels of an audio
2031 The filter accepts parameters of the form:
2032 "@var{l}|@var{outdef}|@var{outdef}|..."
2036 output channel layout or number of channels
2039 output channel specification, of the form:
2040 "@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]"
2043 output channel to define, either a channel name (FL, FR, etc.) or a channel
2044 number (c0, c1, etc.)
2047 multiplicative coefficient for the channel, 1 leaving the volume unchanged
2050 input channel to use, see out_name for details; it is not possible to mix
2051 named and numbered input channels
2054 If the `=' in a channel specification is replaced by `<', then the gains for
2055 that specification will be renormalized so that the total is 1, thus
2056 avoiding clipping noise.
2058 @subsection Mixing examples
2060 For example, if you want to down-mix from stereo to mono, but with a bigger
2061 factor for the left channel:
2063 pan=1c|c0=0.9*c0+0.1*c1
2066 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
2067 7-channels surround:
2069 pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
2072 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
2073 that should be preferred (see "-ac" option) unless you have very specific
2076 @subsection Remapping examples
2078 The channel remapping will be effective if, and only if:
2081 @item gain coefficients are zeroes or ones,
2082 @item only one input per channel output,
2085 If all these conditions are satisfied, the filter will notify the user ("Pure
2086 channel mapping detected"), and use an optimized and lossless method to do the
2089 For example, if you have a 5.1 source and want a stereo audio stream by
2090 dropping the extra channels:
2092 pan="stereo| c0=FL | c1=FR"
2095 Given the same source, you can also switch front left and front right channels
2096 and keep the input channel layout:
2098 pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
2101 If the input is a stereo audio stream, you can mute the front left channel (and
2102 still keep the stereo channel layout) with:
2107 Still with a stereo audio stream input, you can copy the right channel in both
2108 front left and right:
2110 pan="stereo| c0=FR | c1=FR"
2115 ReplayGain scanner filter. This filter takes an audio stream as an input and
2116 outputs it unchanged.
2117 At end of filtering it displays @code{track_gain} and @code{track_peak}.
2121 Convert the audio sample format, sample rate and channel layout. It is
2122 not meant to be used directly.
2124 @section silencedetect
2126 Detect silence in an audio stream.
2128 This filter logs a message when it detects that the input audio volume is less
2129 or equal to a noise tolerance value for a duration greater or equal to the
2130 minimum detected noise duration.
2132 The printed times and duration are expressed in seconds.
2134 The filter accepts the following options:
2138 Set silence duration until notification (default is 2 seconds).
2141 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
2142 specified value) or amplitude ratio. Default is -60dB, or 0.001.
2145 @subsection Examples
2149 Detect 5 seconds of silence with -50dB noise tolerance:
2151 silencedetect=n=-50dB:d=5
2155 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
2156 tolerance in @file{silence.mp3}:
2158 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
2162 @section silenceremove
2164 Remove silence from the beginning, middle or end of the audio.
2166 The filter accepts the following options:
2170 This value is used to indicate if audio should be trimmed at beginning of
2171 the audio. A value of zero indicates no silence should be trimmed from the
2172 beginning. When specifying a non-zero value, it trims audio up until it
2173 finds non-silence. Normally, when trimming silence from beginning of audio
2174 the @var{start_periods} will be @code{1} but it can be increased to higher
2175 values to trim all audio up to specific count of non-silence periods.
2176 Default value is @code{0}.
2178 @item start_duration
2179 Specify the amount of time that non-silence must be detected before it stops
2180 trimming audio. By increasing the duration, bursts of noises can be treated
2181 as silence and trimmed off. Default value is @code{0}.
2183 @item start_threshold
2184 This indicates what sample value should be treated as silence. For digital
2185 audio, a value of @code{0} may be fine but for audio recorded from analog,
2186 you may wish to increase the value to account for background noise.
2187 Can be specified in dB (in case "dB" is appended to the specified value)
2188 or amplitude ratio. Default value is @code{0}.
2191 Set the count for trimming silence from the end of audio.
2192 To remove silence from the middle of a file, specify a @var{stop_periods}
2193 that is negative. This value is then treated as a positive value and is
2194 used to indicate the effect should restart processing as specified by
2195 @var{start_periods}, making it suitable for removing periods of silence
2196 in the middle of the audio.
2197 Default value is @code{0}.
2200 Specify a duration of silence that must exist before audio is not copied any
2201 more. By specifying a higher duration, silence that is wanted can be left in
2203 Default value is @code{0}.
2205 @item stop_threshold
2206 This is the same as @option{start_threshold} but for trimming silence from
2208 Can be specified in dB (in case "dB" is appended to the specified value)
2209 or amplitude ratio. Default value is @code{0}.
2212 This indicate that @var{stop_duration} length of audio should be left intact
2213 at the beginning of each period of silence.
2214 For example, if you want to remove long pauses between words but do not want
2215 to remove the pauses completely. Default value is @code{0}.
2219 @subsection Examples
2223 The following example shows how this filter can be used to start a recording
2224 that does not contain the delay at the start which usually occurs between
2225 pressing the record button and the start of the performance:
2227 silenceremove=1:5:0.02
2233 Boost or cut treble (upper) frequencies of the audio using a two-pole
2234 shelving filter with a response similar to that of a standard
2235 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
2237 The filter accepts the following options:
2241 Give the gain at whichever is the lower of ~22 kHz and the
2242 Nyquist frequency. Its useful range is about -20 (for a large cut)
2243 to +20 (for a large boost). Beware of clipping when using a positive gain.
2246 Set the filter's central frequency and so can be used
2247 to extend or reduce the frequency range to be boosted or cut.
2248 The default value is @code{3000} Hz.
2251 Set method to specify band-width of filter.
2264 Determine how steep is the filter's shelf transition.
2269 Adjust the input audio volume.
2271 It accepts the following parameters:
2275 Set audio volume expression.
2277 Output values are clipped to the maximum value.
2279 The output audio volume is given by the relation:
2281 @var{output_volume} = @var{volume} * @var{input_volume}
2284 The default value for @var{volume} is "1.0".
2287 This parameter represents the mathematical precision.
2289 It determines which input sample formats will be allowed, which affects the
2290 precision of the volume scaling.
2294 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
2296 32-bit floating-point; this limits input sample format to FLT. (default)
2298 64-bit floating-point; this limits input sample format to DBL.
2302 Choose the behaviour on encountering ReplayGain side data in input frames.
2306 Remove ReplayGain side data, ignoring its contents (the default).
2309 Ignore ReplayGain side data, but leave it in the frame.
2312 Prefer the track gain, if present.
2315 Prefer the album gain, if present.
2318 @item replaygain_preamp
2319 Pre-amplification gain in dB to apply to the selected replaygain gain.
2321 Default value for @var{replaygain_preamp} is 0.0.
2324 Set when the volume expression is evaluated.
2326 It accepts the following values:
2329 only evaluate expression once during the filter initialization, or
2330 when the @samp{volume} command is sent
2333 evaluate expression for each incoming frame
2336 Default value is @samp{once}.
2339 The volume expression can contain the following parameters.
2343 frame number (starting at zero)
2346 @item nb_consumed_samples
2347 number of samples consumed by the filter
2349 number of samples in the current frame
2351 original frame position in the file
2357 PTS at start of stream
2359 time at start of stream
2365 last set volume value
2368 Note that when @option{eval} is set to @samp{once} only the
2369 @var{sample_rate} and @var{tb} variables are available, all other
2370 variables will evaluate to NAN.
2372 @subsection Commands
2374 This filter supports the following commands:
2377 Modify the volume expression.
2378 The command accepts the same syntax of the corresponding option.
2380 If the specified expression is not valid, it is kept at its current
2382 @item replaygain_noclip
2383 Prevent clipping by limiting the gain applied.
2385 Default value for @var{replaygain_noclip} is 1.
2389 @subsection Examples
2393 Halve the input audio volume:
2397 volume=volume=-6.0206dB
2400 In all the above example the named key for @option{volume} can be
2401 omitted, for example like in:
2407 Increase input audio power by 6 decibels using fixed-point precision:
2409 volume=volume=6dB:precision=fixed
2413 Fade volume after time 10 with an annihilation period of 5 seconds:
2415 volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
2419 @section volumedetect
2421 Detect the volume of the input video.
2423 The filter has no parameters. The input is not modified. Statistics about
2424 the volume will be printed in the log when the input stream end is reached.
2426 In particular it will show the mean volume (root mean square), maximum
2427 volume (on a per-sample basis), and the beginning of a histogram of the
2428 registered volume values (from the maximum value to a cumulated 1/1000 of
2431 All volumes are in decibels relative to the maximum PCM value.
2433 @subsection Examples
2435 Here is an excerpt of the output:
2437 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
2438 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
2439 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
2440 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
2441 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
2442 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
2443 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
2444 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
2445 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
2451 The mean square energy is approximately -27 dB, or 10^-2.7.
2453 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
2455 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
2458 In other words, raising the volume by +4 dB does not cause any clipping,
2459 raising it by +5 dB causes clipping for 6 samples, etc.
2461 @c man end AUDIO FILTERS
2463 @chapter Audio Sources
2464 @c man begin AUDIO SOURCES
2466 Below is a description of the currently available audio sources.
2470 Buffer audio frames, and make them available to the filter chain.
2472 This source is mainly intended for a programmatic use, in particular
2473 through the interface defined in @file{libavfilter/asrc_abuffer.h}.
2475 It accepts the following parameters:
2479 The timebase which will be used for timestamps of submitted frames. It must be
2480 either a floating-point number or in @var{numerator}/@var{denominator} form.
2483 The sample rate of the incoming audio buffers.
2486 The sample format of the incoming audio buffers.
2487 Either a sample format name or its corresponding integer representation from
2488 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
2490 @item channel_layout
2491 The channel layout of the incoming audio buffers.
2492 Either a channel layout name from channel_layout_map in
2493 @file{libavutil/channel_layout.c} or its corresponding integer representation
2494 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
2497 The number of channels of the incoming audio buffers.
2498 If both @var{channels} and @var{channel_layout} are specified, then they
2503 @subsection Examples
2506 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
2509 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
2510 Since the sample format with name "s16p" corresponds to the number
2511 6 and the "stereo" channel layout corresponds to the value 0x3, this is
2514 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
2519 Generate an audio signal specified by an expression.
2521 This source accepts in input one or more expressions (one for each
2522 channel), which are evaluated and used to generate a corresponding
2525 This source accepts the following options:
2529 Set the '|'-separated expressions list for each separate channel. In case the
2530 @option{channel_layout} option is not specified, the selected channel layout
2531 depends on the number of provided expressions. Otherwise the last
2532 specified expression is applied to the remaining output channels.
2534 @item channel_layout, c
2535 Set the channel layout. The number of channels in the specified layout
2536 must be equal to the number of specified expressions.
2539 Set the minimum duration of the sourced audio. See
2540 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
2541 for the accepted syntax.
2542 Note that the resulting duration may be greater than the specified
2543 duration, as the generated audio is always cut at the end of a
2546 If not specified, or the expressed duration is negative, the audio is
2547 supposed to be generated forever.
2550 Set the number of samples per channel per each output frame,
2553 @item sample_rate, s
2554 Specify the sample rate, default to 44100.
2557 Each expression in @var{exprs} can contain the following constants:
2561 number of the evaluated sample, starting from 0
2564 time of the evaluated sample expressed in seconds, starting from 0
2571 @subsection Examples
2581 Generate a sin signal with frequency of 440 Hz, set sample rate to
2584 aevalsrc="sin(440*2*PI*t):s=8000"
2588 Generate a two channels signal, specify the channel layout (Front
2589 Center + Back Center) explicitly:
2591 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
2595 Generate white noise:
2597 aevalsrc="-2+random(0)"
2601 Generate an amplitude modulated signal:
2603 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
2607 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
2609 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
2616 The null audio source, return unprocessed audio frames. It is mainly useful
2617 as a template and to be employed in analysis / debugging tools, or as
2618 the source for filters which ignore the input data (for example the sox
2621 This source accepts the following options:
2625 @item channel_layout, cl
2627 Specifies the channel layout, and can be either an integer or a string
2628 representing a channel layout. The default value of @var{channel_layout}
2631 Check the channel_layout_map definition in
2632 @file{libavutil/channel_layout.c} for the mapping between strings and
2633 channel layout values.
2635 @item sample_rate, r
2636 Specifies the sample rate, and defaults to 44100.
2639 Set the number of samples per requested frames.
2643 @subsection Examples
2647 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
2649 anullsrc=r=48000:cl=4
2653 Do the same operation with a more obvious syntax:
2655 anullsrc=r=48000:cl=mono
2659 All the parameters need to be explicitly defined.
2663 Synthesize a voice utterance using the libflite library.
2665 To enable compilation of this filter you need to configure FFmpeg with
2666 @code{--enable-libflite}.
2668 Note that the flite library is not thread-safe.
2670 The filter accepts the following options:
2675 If set to 1, list the names of the available voices and exit
2676 immediately. Default value is 0.
2679 Set the maximum number of samples per frame. Default value is 512.
2682 Set the filename containing the text to speak.
2685 Set the text to speak.
2688 Set the voice to use for the speech synthesis. Default value is
2689 @code{kal}. See also the @var{list_voices} option.
2692 @subsection Examples
2696 Read from file @file{speech.txt}, and synthesize the text using the
2697 standard flite voice:
2699 flite=textfile=speech.txt
2703 Read the specified text selecting the @code{slt} voice:
2705 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
2709 Input text to ffmpeg:
2711 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
2715 Make @file{ffplay} speak the specified text, using @code{flite} and
2716 the @code{lavfi} device:
2718 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
2722 For more information about libflite, check:
2723 @url{http://www.speech.cs.cmu.edu/flite/}
2727 Generate an audio signal made of a sine wave with amplitude 1/8.
2729 The audio signal is bit-exact.
2731 The filter accepts the following options:
2736 Set the carrier frequency. Default is 440 Hz.
2738 @item beep_factor, b
2739 Enable a periodic beep every second with frequency @var{beep_factor} times
2740 the carrier frequency. Default is 0, meaning the beep is disabled.
2742 @item sample_rate, r
2743 Specify the sample rate, default is 44100.
2746 Specify the duration of the generated audio stream.
2748 @item samples_per_frame
2749 Set the number of samples per output frame, default is 1024.
2752 @subsection Examples
2757 Generate a simple 440 Hz sine wave:
2763 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
2767 sine=frequency=220:beep_factor=4:duration=5
2772 @c man end AUDIO SOURCES
2774 @chapter Audio Sinks
2775 @c man begin AUDIO SINKS
2777 Below is a description of the currently available audio sinks.
2779 @section abuffersink
2781 Buffer audio frames, and make them available to the end of filter chain.
2783 This sink is mainly intended for programmatic use, in particular
2784 through the interface defined in @file{libavfilter/buffersink.h}
2785 or the options system.
2787 It accepts a pointer to an AVABufferSinkContext structure, which
2788 defines the incoming buffers' formats, to be passed as the opaque
2789 parameter to @code{avfilter_init_filter} for initialization.
2792 Null audio sink; do absolutely nothing with the input audio. It is
2793 mainly useful as a template and for use in analysis / debugging
2796 @c man end AUDIO SINKS
2798 @chapter Video Filters
2799 @c man begin VIDEO FILTERS
2801 When you configure your FFmpeg build, you can disable any of the
2802 existing filters using @code{--disable-filters}.
2803 The configure output will show the video filters included in your
2806 Below is a description of the currently available video filters.
2808 @section alphaextract
2810 Extract the alpha component from the input as a grayscale video. This
2811 is especially useful with the @var{alphamerge} filter.
2815 Add or replace the alpha component of the primary input with the
2816 grayscale value of a second input. This is intended for use with
2817 @var{alphaextract} to allow the transmission or storage of frame
2818 sequences that have alpha in a format that doesn't support an alpha
2821 For example, to reconstruct full frames from a normal YUV-encoded video
2822 and a separate video created with @var{alphaextract}, you might use:
2824 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
2827 Since this filter is designed for reconstruction, it operates on frame
2828 sequences without considering timestamps, and terminates when either
2829 input reaches end of stream. This will cause problems if your encoding
2830 pipeline drops frames. If you're trying to apply an image as an
2831 overlay to a video stream, consider the @var{overlay} filter instead.
2835 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
2836 and libavformat to work. On the other hand, it is limited to ASS (Advanced
2837 Substation Alpha) subtitles files.
2839 This filter accepts the following option in addition to the common options from
2840 the @ref{subtitles} filter:
2844 Set the shaping engine
2846 Available values are:
2849 The default libass shaping engine, which is the best available.
2851 Fast, font-agnostic shaper that can do only substitutions
2853 Slower shaper using OpenType for substitutions and positioning
2856 The default is @code{auto}.
2861 Compute the bounding box for the non-black pixels in the input frame
2864 This filter computes the bounding box containing all the pixels with a
2865 luminance value greater than the minimum allowed value.
2866 The parameters describing the bounding box are printed on the filter
2869 The filter accepts the following option:
2873 Set the minimal luminance value. Default is @code{16}.
2876 @section blackdetect
2878 Detect video intervals that are (almost) completely black. Can be
2879 useful to detect chapter transitions, commercials, or invalid
2880 recordings. Output lines contains the time for the start, end and
2881 duration of the detected black interval expressed in seconds.
2883 In order to display the output lines, you need to set the loglevel at
2884 least to the AV_LOG_INFO value.
2886 The filter accepts the following options:
2889 @item black_min_duration, d
2890 Set the minimum detected black duration expressed in seconds. It must
2891 be a non-negative floating point number.
2893 Default value is 2.0.
2895 @item picture_black_ratio_th, pic_th
2896 Set the threshold for considering a picture "black".
2897 Express the minimum value for the ratio:
2899 @var{nb_black_pixels} / @var{nb_pixels}
2902 for which a picture is considered black.
2903 Default value is 0.98.
2905 @item pixel_black_th, pix_th
2906 Set the threshold for considering a pixel "black".
2908 The threshold expresses the maximum pixel luminance value for which a
2909 pixel is considered "black". The provided value is scaled according to
2910 the following equation:
2912 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
2915 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
2916 the input video format, the range is [0-255] for YUV full-range
2917 formats and [16-235] for YUV non full-range formats.
2919 Default value is 0.10.
2922 The following example sets the maximum pixel threshold to the minimum
2923 value, and detects only black intervals of 2 or more seconds:
2925 blackdetect=d=2:pix_th=0.00
2930 Detect frames that are (almost) completely black. Can be useful to
2931 detect chapter transitions or commercials. Output lines consist of
2932 the frame number of the detected frame, the percentage of blackness,
2933 the position in the file if known or -1 and the timestamp in seconds.
2935 In order to display the output lines, you need to set the loglevel at
2936 least to the AV_LOG_INFO value.
2938 It accepts the following parameters:
2943 The percentage of the pixels that have to be below the threshold; it defaults to
2946 @item threshold, thresh
2947 The threshold below which a pixel value is considered black; it defaults to
2952 @section blend, tblend
2954 Blend two video frames into each other.
2956 The @code{blend} filter takes two input streams and outputs one
2957 stream, the first input is the "top" layer and second input is
2958 "bottom" layer. Output terminates when shortest input terminates.
2960 The @code{tblend} (time blend) filter takes two consecutive frames
2961 from one single stream, and outputs the result obtained by blending
2962 the new frame on top of the old frame.
2964 A description of the accepted options follows.
2972 Set blend mode for specific pixel component or all pixel components in case
2973 of @var{all_mode}. Default value is @code{normal}.
2975 Available values for component modes are:
3012 Set blend opacity for specific pixel component or all pixel components in case
3013 of @var{all_opacity}. Only used in combination with pixel component blend modes.
3020 Set blend expression for specific pixel component or all pixel components in case
3021 of @var{all_expr}. Note that related mode options will be ignored if those are set.
3023 The expressions can use the following variables:
3027 The sequential number of the filtered frame, starting from @code{0}.
3031 the coordinates of the current sample
3035 the width and height of currently filtered plane
3039 Width and height scale depending on the currently filtered plane. It is the
3040 ratio between the corresponding luma plane number of pixels and the current
3041 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
3042 @code{0.5,0.5} for chroma planes.
3045 Time of the current frame, expressed in seconds.
3048 Value of pixel component at current location for first video frame (top layer).
3051 Value of pixel component at current location for second video frame (bottom layer).
3055 Force termination when the shortest input terminates. Default is
3056 @code{0}. This option is only defined for the @code{blend} filter.
3059 Continue applying the last bottom frame after the end of the stream. A value of
3060 @code{0} disable the filter after the last frame of the bottom layer is reached.
3061 Default is @code{1}. This option is only defined for the @code{blend} filter.
3064 @subsection Examples
3068 Apply transition from bottom layer to top layer in first 10 seconds:
3070 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
3074 Apply 1x1 checkerboard effect:
3076 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
3080 Apply uncover left effect:
3082 blend=all_expr='if(gte(N*SW+X,W),A,B)'
3086 Apply uncover down effect:
3088 blend=all_expr='if(gte(Y-N*SH,0),A,B)'
3092 Apply uncover up-left effect:
3094 blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
3098 Display differences between the current and the previous frame:
3100 tblend=all_mode=difference128
3106 Apply a boxblur algorithm to the input video.
3108 It accepts the following parameters:
3112 @item luma_radius, lr
3113 @item luma_power, lp
3114 @item chroma_radius, cr
3115 @item chroma_power, cp
3116 @item alpha_radius, ar
3117 @item alpha_power, ap
3121 A description of the accepted options follows.
3124 @item luma_radius, lr
3125 @item chroma_radius, cr
3126 @item alpha_radius, ar
3127 Set an expression for the box radius in pixels used for blurring the
3128 corresponding input plane.
3130 The radius value must be a non-negative number, and must not be
3131 greater than the value of the expression @code{min(w,h)/2} for the
3132 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
3135 Default value for @option{luma_radius} is "2". If not specified,
3136 @option{chroma_radius} and @option{alpha_radius} default to the
3137 corresponding value set for @option{luma_radius}.
3139 The expressions can contain the following constants:
3143 The input width and height in pixels.
3147 The input chroma image width and height in pixels.
3151 The horizontal and vertical chroma subsample values. For example, for the
3152 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
3155 @item luma_power, lp
3156 @item chroma_power, cp
3157 @item alpha_power, ap
3158 Specify how many times the boxblur filter is applied to the
3159 corresponding plane.
3161 Default value for @option{luma_power} is 2. If not specified,
3162 @option{chroma_power} and @option{alpha_power} default to the
3163 corresponding value set for @option{luma_power}.
3165 A value of 0 will disable the effect.
3168 @subsection Examples
3172 Apply a boxblur filter with the luma, chroma, and alpha radii
3175 boxblur=luma_radius=2:luma_power=1
3180 Set the luma radius to 2, and alpha and chroma radius to 0:
3182 boxblur=2:1:cr=0:ar=0
3186 Set the luma and chroma radii to a fraction of the video dimension:
3188 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
3194 Visualize information exported by some codecs.
3196 Some codecs can export information through frames using side-data or other
3197 means. For example, some MPEG based codecs export motion vectors through the
3198 @var{export_mvs} flag in the codec @option{flags2} option.
3200 The filter accepts the following option:
3204 Set motion vectors to visualize.
3206 Available flags for @var{mv} are:
3210 forward predicted MVs of P-frames
3212 forward predicted MVs of B-frames
3214 backward predicted MVs of B-frames
3218 @subsection Examples
3222 Visualizes multi-directionals MVs from P and B-Frames using @command{ffplay}:
3224 ffplay -flags2 +export_mvs input.mpg -vf codecview=mv=pf+bf+bb
3228 @section colorbalance
3229 Modify intensity of primary colors (red, green and blue) of input frames.
3231 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
3232 regions for the red-cyan, green-magenta or blue-yellow balance.
3234 A positive adjustment value shifts the balance towards the primary color, a negative
3235 value towards the complementary color.
3237 The filter accepts the following options:
3243 Adjust red, green and blue shadows (darkest pixels).
3248 Adjust red, green and blue midtones (medium pixels).
3253 Adjust red, green and blue highlights (brightest pixels).
3255 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
3258 @subsection Examples
3262 Add red color cast to shadows:
3269 RGB colorspace color keying.
3271 The filter accepts the following options:
3275 The color which will be replaced with transparency.
3278 Similarity percentage with the key color.
3280 0.01 matches only the exact key color, while 1.0 matches everything.
3285 0.0 makes pixels either fully transparent, or not transparent at all.
3287 Higher values result in semi-transparent pixels, with a higher transparency
3288 the more similar the pixels color is to the key color.
3291 @subsection Examples
3295 Make every green pixel in the input image transparent:
3297 ffmpeg -i input.png -vf colorkey=green out.png
3301 Overlay a greenscreen-video on top of a static background image.
3303 ffmpeg -i background.png -i video.mp4 -filter_complex "[1:v]colorkey=0x3BBD1E:0.3:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.flv
3307 @section colorlevels
3309 Adjust video input frames using levels.
3311 The filter accepts the following options:
3318 Adjust red, green, blue and alpha input black point.
3319 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
3325 Adjust red, green, blue and alpha input white point.
3326 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
3328 Input levels are used to lighten highlights (bright tones), darken shadows
3329 (dark tones), change the balance of bright and dark tones.
3335 Adjust red, green, blue and alpha output black point.
3336 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
3342 Adjust red, green, blue and alpha output white point.
3343 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
3345 Output levels allows manual selection of a constrained output level range.
3348 @subsection Examples
3352 Make video output darker:
3354 colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
3360 colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
3364 Make video output lighter:
3366 colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
3370 Increase brightness:
3372 colorlevels=romin=0.5:gomin=0.5:bomin=0.5
3376 @section colorchannelmixer
3378 Adjust video input frames by re-mixing color channels.
3380 This filter modifies a color channel by adding the values associated to
3381 the other channels of the same pixels. For example if the value to
3382 modify is red, the output value will be:
3384 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
3387 The filter accepts the following options:
3394 Adjust contribution of input red, green, blue and alpha channels for output red channel.
3395 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
3401 Adjust contribution of input red, green, blue and alpha channels for output green channel.
3402 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
3408 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
3409 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
3415 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
3416 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
3418 Allowed ranges for options are @code{[-2.0, 2.0]}.
3421 @subsection Examples
3425 Convert source to grayscale:
3427 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
3430 Simulate sepia tones:
3432 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
3436 @section colormatrix
3438 Convert color matrix.
3440 The filter accepts the following options:
3445 Specify the source and destination color matrix. Both values must be
3448 The accepted values are:
3464 For example to convert from BT.601 to SMPTE-240M, use the command:
3466 colormatrix=bt601:smpte240m
3471 Copy the input source unchanged to the output. This is mainly useful for
3476 Crop the input video to given dimensions.
3478 It accepts the following parameters:
3482 The width of the output video. It defaults to @code{iw}.
3483 This expression is evaluated only once during the filter
3484 configuration, or when the @samp{w} or @samp{out_w} command is sent.
3487 The height of the output video. It defaults to @code{ih}.
3488 This expression is evaluated only once during the filter
3489 configuration, or when the @samp{h} or @samp{out_h} command is sent.
3492 The horizontal position, in the input video, of the left edge of the output
3493 video. It defaults to @code{(in_w-out_w)/2}.
3494 This expression is evaluated per-frame.
3497 The vertical position, in the input video, of the top edge of the output video.
3498 It defaults to @code{(in_h-out_h)/2}.
3499 This expression is evaluated per-frame.
3502 If set to 1 will force the output display aspect ratio
3503 to be the same of the input, by changing the output sample aspect
3504 ratio. It defaults to 0.
3507 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
3508 expressions containing the following constants:
3513 The computed values for @var{x} and @var{y}. They are evaluated for
3518 The input width and height.
3522 These are the same as @var{in_w} and @var{in_h}.
3526 The output (cropped) width and height.
3530 These are the same as @var{out_w} and @var{out_h}.
3533 same as @var{iw} / @var{ih}
3536 input sample aspect ratio
3539 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
3543 horizontal and vertical chroma subsample values. For example for the
3544 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
3547 The number of the input frame, starting from 0.
3550 the position in the file of the input frame, NAN if unknown
3553 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
3557 The expression for @var{out_w} may depend on the value of @var{out_h},
3558 and the expression for @var{out_h} may depend on @var{out_w}, but they
3559 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
3560 evaluated after @var{out_w} and @var{out_h}.
3562 The @var{x} and @var{y} parameters specify the expressions for the
3563 position of the top-left corner of the output (non-cropped) area. They
3564 are evaluated for each frame. If the evaluated value is not valid, it
3565 is approximated to the nearest valid value.
3567 The expression for @var{x} may depend on @var{y}, and the expression
3568 for @var{y} may depend on @var{x}.
3570 @subsection Examples
3574 Crop area with size 100x100 at position (12,34).
3579 Using named options, the example above becomes:
3581 crop=w=100:h=100:x=12:y=34
3585 Crop the central input area with size 100x100:
3591 Crop the central input area with size 2/3 of the input video:
3593 crop=2/3*in_w:2/3*in_h
3597 Crop the input video central square:
3604 Delimit the rectangle with the top-left corner placed at position
3605 100:100 and the right-bottom corner corresponding to the right-bottom
3606 corner of the input image.
3608 crop=in_w-100:in_h-100:100:100
3612 Crop 10 pixels from the left and right borders, and 20 pixels from
3613 the top and bottom borders
3615 crop=in_w-2*10:in_h-2*20
3619 Keep only the bottom right quarter of the input image:
3621 crop=in_w/2:in_h/2:in_w/2:in_h/2
3625 Crop height for getting Greek harmony:
3627 crop=in_w:1/PHI*in_w
3631 Apply trembling effect:
3633 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)
3637 Apply erratic camera effect depending on timestamp:
3639 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)"
3643 Set x depending on the value of y:
3645 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
3649 @subsection Commands
3651 This filter supports the following commands:
3657 Set width/height of the output video and the horizontal/vertical position
3659 The command accepts the same syntax of the corresponding option.
3661 If the specified expression is not valid, it is kept at its current
3667 Auto-detect the crop size.
3669 It calculates the necessary cropping parameters and prints the
3670 recommended parameters via the logging system. The detected dimensions
3671 correspond to the non-black area of the input video.
3673 It accepts the following parameters:
3678 Set higher black value threshold, which can be optionally specified
3679 from nothing (0) to everything (255 for 8bit based formats). An intensity
3680 value greater to the set value is considered non-black. It defaults to 24.
3681 You can also specify a value between 0.0 and 1.0 which will be scaled depending
3682 on the bitdepth of the pixel format.
3685 The value which the width/height should be divisible by. It defaults to
3686 16. The offset is automatically adjusted to center the video. Use 2 to
3687 get only even dimensions (needed for 4:2:2 video). 16 is best when
3688 encoding to most video codecs.
3690 @item reset_count, reset
3691 Set the counter that determines after how many frames cropdetect will
3692 reset the previously detected largest video area and start over to
3693 detect the current optimal crop area. Default value is 0.
3695 This can be useful when channel logos distort the video area. 0
3696 indicates 'never reset', and returns the largest area encountered during
3703 Apply color adjustments using curves.
3705 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
3706 component (red, green and blue) has its values defined by @var{N} key points
3707 tied from each other using a smooth curve. The x-axis represents the pixel
3708 values from the input frame, and the y-axis the new pixel values to be set for
3711 By default, a component curve is defined by the two points @var{(0;0)} and
3712 @var{(1;1)}. This creates a straight line where each original pixel value is
3713 "adjusted" to its own value, which means no change to the image.
3715 The filter allows you to redefine these two points and add some more. A new
3716 curve (using a natural cubic spline interpolation) will be define to pass
3717 smoothly through all these new coordinates. The new defined points needs to be
3718 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
3719 be in the @var{[0;1]} interval. If the computed curves happened to go outside
3720 the vector spaces, the values will be clipped accordingly.
3722 If there is no key point defined in @code{x=0}, the filter will automatically
3723 insert a @var{(0;0)} point. In the same way, if there is no key point defined
3724 in @code{x=1}, the filter will automatically insert a @var{(1;1)} point.
3726 The filter accepts the following options:
3730 Select one of the available color presets. This option can be used in addition
3731 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
3732 options takes priority on the preset values.
3733 Available presets are:
3736 @item color_negative
3739 @item increase_contrast
3741 @item linear_contrast
3742 @item medium_contrast
3744 @item strong_contrast
3747 Default is @code{none}.
3749 Set the master key points. These points will define a second pass mapping. It
3750 is sometimes called a "luminance" or "value" mapping. It can be used with
3751 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
3752 post-processing LUT.
3754 Set the key points for the red component.
3756 Set the key points for the green component.
3758 Set the key points for the blue component.
3760 Set the key points for all components (not including master).
3761 Can be used in addition to the other key points component
3762 options. In this case, the unset component(s) will fallback on this
3763 @option{all} setting.
3765 Specify a Photoshop curves file (@code{.asv}) to import the settings from.
3768 To avoid some filtergraph syntax conflicts, each key points list need to be
3769 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
3771 @subsection Examples
3775 Increase slightly the middle level of blue:
3777 curves=blue='0.5/0.58'
3783 curves=r='0/0.11 .42/.51 1/0.95':g='0.50/0.48':b='0/0.22 .49/.44 1/0.8'
3785 Here we obtain the following coordinates for each components:
3788 @code{(0;0.11) (0.42;0.51) (1;0.95)}
3790 @code{(0;0) (0.50;0.48) (1;1)}
3792 @code{(0;0.22) (0.49;0.44) (1;0.80)}
3796 The previous example can also be achieved with the associated built-in preset:
3798 curves=preset=vintage
3808 Use a Photoshop preset and redefine the points of the green component:
3810 curves=psfile='MyCurvesPresets/purple.asv':green='0.45/0.53'
3816 Denoise frames using 2D DCT (frequency domain filtering).
3818 This filter is not designed for real time.
3820 The filter accepts the following options:
3824 Set the noise sigma constant.
3826 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
3827 coefficient (absolute value) below this threshold with be dropped.
3829 If you need a more advanced filtering, see @option{expr}.
3831 Default is @code{0}.
3834 Set number overlapping pixels for each block. Since the filter can be slow, you
3835 may want to reduce this value, at the cost of a less effective filter and the
3836 risk of various artefacts.
3838 If the overlapping value doesn't permit processing the whole input width or
3839 height, a warning will be displayed and according borders won't be denoised.
3841 Default value is @var{blocksize}-1, which is the best possible setting.
3844 Set the coefficient factor expression.
3846 For each coefficient of a DCT block, this expression will be evaluated as a
3847 multiplier value for the coefficient.
3849 If this is option is set, the @option{sigma} option will be ignored.
3851 The absolute value of the coefficient can be accessed through the @var{c}
3855 Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
3856 @var{blocksize}, which is the width and height of the processed blocks.
3858 The default value is @var{3} (8x8) and can be raised to @var{4} for a
3859 @var{blocksize} of 16x16. Note that changing this setting has huge consequences
3860 on the speed processing. Also, a larger block size does not necessarily means a
3864 @subsection Examples
3866 Apply a denoise with a @option{sigma} of @code{4.5}:
3871 The same operation can be achieved using the expression system:
3873 dctdnoiz=e='gte(c, 4.5*3)'
3876 Violent denoise using a block size of @code{16x16}:
3883 Remove banding artifacts from input video.
3884 It works by replacing banded pixels with average value of referenced pixels.
3886 The filter accepts the following options:
3893 Set banding detection threshold for each plane. Default is 0.02.
3894 Valid range is 0.00003 to 0.5.
3895 If difference between current pixel and reference pixel is less than threshold,
3896 it will be considered as banded.
3899 Banding detection range in pixels. Default is 16. If positive, random number
3900 in range 0 to set value will be used. If negative, exact absolute value
3902 The range defines square of four pixels around current pixel.
3905 Set direction in radians from which four pixel will be compared. If positive,
3906 random direction from 0 to set direction will be picked. If negative, exact of
3907 absolute value will be picked. For example direction 0, -PI or -2*PI radians
3908 will pick only pixels on same row and -PI/2 will pick only pixels on same
3912 If enabled, current pixel is compared with average value of all four
3913 surrounding pixels. The default is enabled. If disabled current pixel is
3914 compared with all four surrounding pixels. The pixel is considered banded
3915 if only all four differences with surrounding pixels are less than threshold.
3921 Drop duplicated frames at regular intervals.
3923 The filter accepts the following options:
3927 Set the number of frames from which one will be dropped. Setting this to
3928 @var{N} means one frame in every batch of @var{N} frames will be dropped.
3929 Default is @code{5}.
3932 Set the threshold for duplicate detection. If the difference metric for a frame
3933 is less than or equal to this value, then it is declared as duplicate. Default
3937 Set scene change threshold. Default is @code{15}.
3941 Set the size of the x and y-axis blocks used during metric calculations.
3942 Larger blocks give better noise suppression, but also give worse detection of
3943 small movements. Must be a power of two. Default is @code{32}.
3946 Mark main input as a pre-processed input and activate clean source input
3947 stream. This allows the input to be pre-processed with various filters to help
3948 the metrics calculation while keeping the frame selection lossless. When set to
3949 @code{1}, the first stream is for the pre-processed input, and the second
3950 stream is the clean source from where the kept frames are chosen. Default is
3954 Set whether or not chroma is considered in the metric calculations. Default is
3960 Apply deflate effect to the video.
3962 This filter replaces the pixel by the local(3x3) average by taking into account
3963 only values lower than the pixel.
3965 It accepts the following options:
3972 Allows to limit the maximum change for each plane, default is 65535.
3973 If 0, plane will remain unchanged.
3978 Remove judder produced by partially interlaced telecined content.
3980 Judder can be introduced, for instance, by @ref{pullup} filter. If the original
3981 source was partially telecined content then the output of @code{pullup,dejudder}
3982 will have a variable frame rate. May change the recorded frame rate of the
3983 container. Aside from that change, this filter will not affect constant frame
3986 The option available in this filter is:
3990 Specify the length of the window over which the judder repeats.
3992 Accepts any integer greater than 1. Useful values are:
3996 If the original was telecined from 24 to 30 fps (Film to NTSC).
3999 If the original was telecined from 25 to 30 fps (PAL to NTSC).
4002 If a mixture of the two.
4005 The default is @samp{4}.
4010 Suppress a TV station logo by a simple interpolation of the surrounding
4011 pixels. Just set a rectangle covering the logo and watch it disappear
4012 (and sometimes something even uglier appear - your mileage may vary).
4014 It accepts the following parameters:
4019 Specify the top left corner coordinates of the logo. They must be
4024 Specify the width and height of the logo to clear. They must be
4028 Specify the thickness of the fuzzy edge of the rectangle (added to
4029 @var{w} and @var{h}). The default value is 4.
4032 When set to 1, a green rectangle is drawn on the screen to simplify
4033 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
4034 The default value is 0.
4036 The rectangle is drawn on the outermost pixels which will be (partly)
4037 replaced with interpolated values. The values of the next pixels
4038 immediately outside this rectangle in each direction will be used to
4039 compute the interpolated pixel values inside the rectangle.
4043 @subsection Examples
4047 Set a rectangle covering the area with top left corner coordinates 0,0
4048 and size 100x77, and a band of size 10:
4050 delogo=x=0:y=0:w=100:h=77:band=10
4057 Attempt to fix small changes in horizontal and/or vertical shift. This
4058 filter helps remove camera shake from hand-holding a camera, bumping a
4059 tripod, moving on a vehicle, etc.
4061 The filter accepts the following options:
4069 Specify a rectangular area where to limit the search for motion
4071 If desired the search for motion vectors can be limited to a
4072 rectangular area of the frame defined by its top left corner, width
4073 and height. These parameters have the same meaning as the drawbox
4074 filter which can be used to visualise the position of the bounding
4077 This is useful when simultaneous movement of subjects within the frame
4078 might be confused for camera motion by the motion vector search.
4080 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
4081 then the full frame is used. This allows later options to be set
4082 without specifying the bounding box for the motion vector search.
4084 Default - search the whole frame.
4088 Specify the maximum extent of movement in x and y directions in the
4089 range 0-64 pixels. Default 16.
4092 Specify how to generate pixels to fill blanks at the edge of the
4093 frame. Available values are:
4096 Fill zeroes at blank locations
4098 Original image at blank locations
4100 Extruded edge value at blank locations
4102 Mirrored edge at blank locations
4104 Default value is @samp{mirror}.
4107 Specify the blocksize to use for motion search. Range 4-128 pixels,
4111 Specify the contrast threshold for blocks. Only blocks with more than
4112 the specified contrast (difference between darkest and lightest
4113 pixels) will be considered. Range 1-255, default 125.
4116 Specify the search strategy. Available values are:
4119 Set exhaustive search
4121 Set less exhaustive search.
4123 Default value is @samp{exhaustive}.
4126 If set then a detailed log of the motion search is written to the
4130 If set to 1, specify using OpenCL capabilities, only available if
4131 FFmpeg was configured with @code{--enable-opencl}. Default value is 0.
4137 Apply an exact inverse of the telecine operation. It requires a predefined
4138 pattern specified using the pattern option which must be the same as that passed
4139 to the telecine filter.
4141 This filter accepts the following options:
4150 The default value is @code{top}.
4154 A string of numbers representing the pulldown pattern you wish to apply.
4155 The default value is @code{23}.
4158 A number representing position of the first frame with respect to the telecine
4159 pattern. This is to be used if the stream is cut. The default value is @code{0}.
4164 Apply dilation effect to the video.
4166 This filter replaces the pixel by the local(3x3) maximum.
4168 It accepts the following options:
4175 Allows to limit the maximum change for each plane, default is 65535.
4176 If 0, plane will remain unchanged.
4179 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
4182 Flags to local 3x3 coordinates maps like this:
4191 Draw a colored box on the input image.
4193 It accepts the following parameters:
4198 The expressions which specify the top left corner coordinates of the box. It defaults to 0.
4202 The expressions which specify the width and height of the box; if 0 they are interpreted as
4203 the input width and height. It defaults to 0.
4206 Specify the color of the box to write. For the general syntax of this option,
4207 check the "Color" section in the ffmpeg-utils manual. If the special
4208 value @code{invert} is used, the box edge color is the same as the
4209 video with inverted luma.
4212 The expression which sets the thickness of the box edge. Default value is @code{3}.
4214 See below for the list of accepted constants.
4217 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
4218 following constants:
4222 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
4226 horizontal and vertical chroma subsample values. For example for the
4227 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
4231 The input width and height.
4234 The input sample aspect ratio.
4238 The x and y offset coordinates where the box is drawn.
4242 The width and height of the drawn box.
4245 The thickness of the drawn box.
4247 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
4248 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
4252 @subsection Examples
4256 Draw a black box around the edge of the input image:
4262 Draw a box with color red and an opacity of 50%:
4264 drawbox=10:20:200:60:red@@0.5
4267 The previous example can be specified as:
4269 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
4273 Fill the box with pink color:
4275 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max
4279 Draw a 2-pixel red 2.40:1 mask:
4281 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
4285 @section drawgraph, adrawgraph
4287 Draw a graph using input video or audio metadata.
4289 It accepts the following parameters:
4293 Set 1st frame metadata key from which metadata values will be used to draw a graph.
4296 Set 1st foreground color expression.
4299 Set 2nd frame metadata key from which metadata values will be used to draw a graph.
4302 Set 2nd foreground color expression.
4305 Set 3rd frame metadata key from which metadata values will be used to draw a graph.
4308 Set 3rd foreground color expression.
4311 Set 4th frame metadata key from which metadata values will be used to draw a graph.
4314 Set 4th foreground color expression.
4317 Set minimal value of metadata value.
4320 Set maximal value of metadata value.
4323 Set graph background color. Default is white.
4328 Available values for mode is:
4335 Default is @code{line}.
4340 Available values for slide is:
4343 Draw new frame when right border is reached.
4346 Replace old columns with new ones.
4349 Scroll from right to left.
4352 Default is @code{frame}.
4355 Set size of graph video. For the syntax of this option, check the
4356 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
4357 The default value is @code{900x256}.
4359 The foreground color expressions can use the following variables:
4362 Minimal value of metadata value.
4365 Maximal value of metadata value.
4368 Current metadata key value.
4371 The color is defined as 0xAABBGGRR.
4374 Example using metadata from @ref{signalstats} filter:
4376 signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
4379 Example using metadata from @ref{ebur128} filter:
4381 ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
4386 Draw a grid on the input image.
4388 It accepts the following parameters:
4393 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
4397 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
4398 input width and height, respectively, minus @code{thickness}, so image gets
4399 framed. Default to 0.
4402 Specify the color of the grid. For the general syntax of this option,
4403 check the "Color" section in the ffmpeg-utils manual. If the special
4404 value @code{invert} is used, the grid color is the same as the
4405 video with inverted luma.
4408 The expression which sets the thickness of the grid line. Default value is @code{1}.
4410 See below for the list of accepted constants.
4413 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
4414 following constants:
4418 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
4422 horizontal and vertical chroma subsample values. For example for the
4423 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
4427 The input grid cell width and height.
4430 The input sample aspect ratio.
4434 The x and y coordinates of some point of grid intersection (meant to configure offset).
4438 The width and height of the drawn cell.
4441 The thickness of the drawn cell.
4443 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
4444 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
4448 @subsection Examples
4452 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
4454 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
4458 Draw a white 3x3 grid with an opacity of 50%:
4460 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
4467 Draw a text string or text from a specified file on top of a video, using the
4468 libfreetype library.
4470 To enable compilation of this filter, you need to configure FFmpeg with
4471 @code{--enable-libfreetype}.
4472 To enable default font fallback and the @var{font} option you need to
4473 configure FFmpeg with @code{--enable-libfontconfig}.
4474 To enable the @var{text_shaping} option, you need to configure FFmpeg with
4475 @code{--enable-libfribidi}.
4479 It accepts the following parameters:
4484 Used to draw a box around text using the background color.
4485 The value must be either 1 (enable) or 0 (disable).
4486 The default value of @var{box} is 0.
4489 Set the width of the border to be drawn around the box using @var{boxcolor}.
4490 The default value of @var{boxborderw} is 0.
4493 The color to be used for drawing box around text. For the syntax of this
4494 option, check the "Color" section in the ffmpeg-utils manual.
4496 The default value of @var{boxcolor} is "white".
4499 Set the width of the border to be drawn around the text using @var{bordercolor}.
4500 The default value of @var{borderw} is 0.
4503 Set the color to be used for drawing border around text. For the syntax of this
4504 option, check the "Color" section in the ffmpeg-utils manual.
4506 The default value of @var{bordercolor} is "black".
4509 Select how the @var{text} is expanded. Can be either @code{none},
4510 @code{strftime} (deprecated) or
4511 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
4515 If true, check and fix text coords to avoid clipping.
4518 The color to be used for drawing fonts. For the syntax of this option, check
4519 the "Color" section in the ffmpeg-utils manual.
4521 The default value of @var{fontcolor} is "black".
4523 @item fontcolor_expr
4524 String which is expanded the same way as @var{text} to obtain dynamic
4525 @var{fontcolor} value. By default this option has empty value and is not
4526 processed. When this option is set, it overrides @var{fontcolor} option.
4529 The font family to be used for drawing text. By default Sans.
4532 The font file to be used for drawing text. The path must be included.
4533 This parameter is mandatory if the fontconfig support is disabled.
4536 This option does not exist, please see the timeline system
4539 Draw the text applying alpha blending. The value can
4540 be either a number between 0.0 and 1.0
4541 The expression accepts the same variables @var{x, y} do.
4542 The default value is 1.
4543 Please see fontcolor_expr
4546 The font size to be used for drawing text.
4547 The default value of @var{fontsize} is 16.
4550 If set to 1, attempt to shape the text (for example, reverse the order of
4551 right-to-left text and join Arabic characters) before drawing it.
4552 Otherwise, just draw the text exactly as given.
4553 By default 1 (if supported).
4556 The flags to be used for loading the fonts.
4558 The flags map the corresponding flags supported by libfreetype, and are
4559 a combination of the following values:
4566 @item vertical_layout
4567 @item force_autohint
4570 @item ignore_global_advance_width
4572 @item ignore_transform
4578 Default value is "default".
4580 For more information consult the documentation for the FT_LOAD_*
4584 The color to be used for drawing a shadow behind the drawn text. For the
4585 syntax of this option, check the "Color" section in the ffmpeg-utils manual.
4587 The default value of @var{shadowcolor} is "black".
4591 The x and y offsets for the text shadow position with respect to the
4592 position of the text. They can be either positive or negative
4593 values. The default value for both is "0".
4596 The starting frame number for the n/frame_num variable. The default value
4600 The size in number of spaces to use for rendering the tab.
4604 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
4605 format. It can be used with or without text parameter. @var{timecode_rate}
4606 option must be specified.
4608 @item timecode_rate, rate, r
4609 Set the timecode frame rate (timecode only).
4612 The text string to be drawn. The text must be a sequence of UTF-8
4614 This parameter is mandatory if no file is specified with the parameter
4618 A text file containing text to be drawn. The text must be a sequence
4619 of UTF-8 encoded characters.
4621 This parameter is mandatory if no text string is specified with the
4622 parameter @var{text}.
4624 If both @var{text} and @var{textfile} are specified, an error is thrown.
4627 If set to 1, the @var{textfile} will be reloaded before each frame.
4628 Be sure to update it atomically, or it may be read partially, or even fail.
4632 The expressions which specify the offsets where text will be drawn
4633 within the video frame. They are relative to the top/left border of the
4636 The default value of @var{x} and @var{y} is "0".
4638 See below for the list of accepted constants and functions.
4641 The parameters for @var{x} and @var{y} are expressions containing the
4642 following constants and functions:
4646 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
4650 horizontal and vertical chroma subsample values. For example for the
4651 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
4654 the height of each text line
4662 @item max_glyph_a, ascent
4663 the maximum distance from the baseline to the highest/upper grid
4664 coordinate used to place a glyph outline point, for all the rendered
4666 It is a positive value, due to the grid's orientation with the Y axis
4669 @item max_glyph_d, descent
4670 the maximum distance from the baseline to the lowest grid coordinate
4671 used to place a glyph outline point, for all the rendered glyphs.
4672 This is a negative value, due to the grid's orientation, with the Y axis
4676 maximum glyph height, that is the maximum height for all the glyphs
4677 contained in the rendered text, it is equivalent to @var{ascent} -
4681 maximum glyph width, that is the maximum width for all the glyphs
4682 contained in the rendered text
4685 the number of input frame, starting from 0
4687 @item rand(min, max)
4688 return a random number included between @var{min} and @var{max}
4691 The input sample aspect ratio.
4694 timestamp expressed in seconds, NAN if the input timestamp is unknown
4697 the height of the rendered text
4700 the width of the rendered text
4704 the x and y offset coordinates where the text is drawn.
4706 These parameters allow the @var{x} and @var{y} expressions to refer
4707 each other, so you can for example specify @code{y=x/dar}.
4710 @anchor{drawtext_expansion}
4711 @subsection Text expansion
4713 If @option{expansion} is set to @code{strftime},
4714 the filter recognizes strftime() sequences in the provided text and
4715 expands them accordingly. Check the documentation of strftime(). This
4716 feature is deprecated.
4718 If @option{expansion} is set to @code{none}, the text is printed verbatim.
4720 If @option{expansion} is set to @code{normal} (which is the default),
4721 the following expansion mechanism is used.
4723 The backslash character @samp{\}, followed by any character, always expands to
4724 the second character.
4726 Sequence of the form @code{%@{...@}} are expanded. The text between the
4727 braces is a function name, possibly followed by arguments separated by ':'.
4728 If the arguments contain special characters or delimiters (':' or '@}'),
4729 they should be escaped.
4731 Note that they probably must also be escaped as the value for the
4732 @option{text} option in the filter argument string and as the filter
4733 argument in the filtergraph description, and possibly also for the shell,
4734 that makes up to four levels of escaping; using a text file avoids these
4737 The following functions are available:
4742 The expression evaluation result.
4744 It must take one argument specifying the expression to be evaluated,
4745 which accepts the same constants and functions as the @var{x} and
4746 @var{y} values. Note that not all constants should be used, for
4747 example the text size is not known when evaluating the expression, so
4748 the constants @var{text_w} and @var{text_h} will have an undefined
4751 @item expr_int_format, eif
4752 Evaluate the expression's value and output as formatted integer.
4754 The first argument is the expression to be evaluated, just as for the @var{expr} function.
4755 The second argument specifies the output format. Allowed values are @samp{x},
4756 @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
4757 @code{printf} function.
4758 The third parameter is optional and sets the number of positions taken by the output.
4759 It can be used to add padding with zeros from the left.
4762 The time at which the filter is running, expressed in UTC.
4763 It can accept an argument: a strftime() format string.
4766 The time at which the filter is running, expressed in the local time zone.
4767 It can accept an argument: a strftime() format string.
4770 Frame metadata. It must take one argument specifying metadata key.
4773 The frame number, starting from 0.
4776 A 1 character description of the current picture type.
4779 The timestamp of the current frame.
4780 It can take up to two arguments.
4782 The first argument is the format of the timestamp; it defaults to @code{flt}
4783 for seconds as a decimal number with microsecond accuracy; @code{hms} stands
4784 for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
4786 The second argument is an offset added to the timestamp.
4790 @subsection Examples
4794 Draw "Test Text" with font FreeSerif, using the default values for the
4795 optional parameters.
4798 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
4802 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
4803 and y=50 (counting from the top-left corner of the screen), text is
4804 yellow with a red box around it. Both the text and the box have an
4808 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
4809 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
4812 Note that the double quotes are not necessary if spaces are not used
4813 within the parameter list.
4816 Show the text at the center of the video frame:
4818 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2"
4822 Show a text line sliding from right to left in the last row of the video
4823 frame. The file @file{LONG_LINE} is assumed to contain a single line
4826 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
4830 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
4832 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
4836 Draw a single green letter "g", at the center of the input video.
4837 The glyph baseline is placed at half screen height.
4839 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
4843 Show text for 1 second every 3 seconds:
4845 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
4849 Use fontconfig to set the font. Note that the colons need to be escaped.
4851 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
4855 Print the date of a real-time encoding (see strftime(3)):
4857 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
4861 Show text fading in and out (appearing/disappearing):
4864 DS=1.0 # display start
4865 DE=10.0 # display end
4866 FID=1.5 # fade in duration
4867 FOD=5 # fade out duration
4868 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 @}"
4873 For more information about libfreetype, check:
4874 @url{http://www.freetype.org/}.
4876 For more information about fontconfig, check:
4877 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
4879 For more information about libfribidi, check:
4880 @url{http://fribidi.org/}.
4884 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
4886 The filter accepts the following options:
4891 Set low and high threshold values used by the Canny thresholding
4894 The high threshold selects the "strong" edge pixels, which are then
4895 connected through 8-connectivity with the "weak" edge pixels selected
4896 by the low threshold.
4898 @var{low} and @var{high} threshold values must be chosen in the range
4899 [0,1], and @var{low} should be lesser or equal to @var{high}.
4901 Default value for @var{low} is @code{20/255}, and default value for @var{high}
4905 Define the drawing mode.
4909 Draw white/gray wires on black background.
4912 Mix the colors to create a paint/cartoon effect.
4915 Default value is @var{wires}.
4918 @subsection Examples
4922 Standard edge detection with custom values for the hysteresis thresholding:
4924 edgedetect=low=0.1:high=0.4
4928 Painting effect without thresholding:
4930 edgedetect=mode=colormix:high=0
4935 Set brightness, contrast, saturation and approximate gamma adjustment.
4937 The filter accepts the following options:
4941 Set the contrast expression. The value must be a float value in range
4942 @code{-2.0} to @code{2.0}. The default value is "0".
4945 Set the brightness expression. The value must be a float value in
4946 range @code{-1.0} to @code{1.0}. The default value is "0".
4949 Set the saturation expression. The value must be a float in
4950 range @code{0.0} to @code{3.0}. The default value is "1".
4953 Set the gamma expression. The value must be a float in range
4954 @code{0.1} to @code{10.0}. The default value is "1".
4957 Set the gamma expression for red. The value must be a float in
4958 range @code{0.1} to @code{10.0}. The default value is "1".
4961 Set the gamma expression for green. The value must be a float in range
4962 @code{0.1} to @code{10.0}. The default value is "1".
4965 Set the gamma expression for blue. The value must be a float in range
4966 @code{0.1} to @code{10.0}. The default value is "1".
4969 Set the gamma weight expression. It can be used to reduce the effect
4970 of a high gamma value on bright image areas, e.g. keep them from
4971 getting overamplified and just plain white. The value must be a float
4972 in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
4973 gamma correction all the way down while @code{1.0} leaves it at its
4974 full strength. Default is "1".
4977 Set when the expressions for brightness, contrast, saturation and
4978 gamma expressions are evaluated.
4980 It accepts the following values:
4983 only evaluate expressions once during the filter initialization or
4984 when a command is processed
4987 evaluate expressions for each incoming frame
4990 Default value is @samp{init}.
4993 The expressions accept the following parameters:
4996 frame count of the input frame starting from 0
4999 byte position of the corresponding packet in the input file, NAN if
5003 frame rate of the input video, NAN if the input frame rate is unknown
5006 timestamp expressed in seconds, NAN if the input timestamp is unknown
5009 @subsection Commands
5010 The filter supports the following commands:
5014 Set the contrast expression.
5017 Set the brightness expression.
5020 Set the saturation expression.
5023 Set the gamma expression.
5026 Set the gamma_r expression.
5029 Set gamma_g expression.
5032 Set gamma_b expression.
5035 Set gamma_weight expression.
5037 The command accepts the same syntax of the corresponding option.
5039 If the specified expression is not valid, it is kept at its current
5046 Apply erosion effect to the video.
5048 This filter replaces the pixel by the local(3x3) minimum.
5050 It accepts the following options:
5057 Allows to limit the maximum change for each plane, default is 65535.
5058 If 0, plane will remain unchanged.
5061 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
5064 Flags to local 3x3 coordinates maps like this:
5071 @section extractplanes
5073 Extract color channel components from input video stream into
5074 separate grayscale video streams.
5076 The filter accepts the following option:
5080 Set plane(s) to extract.
5082 Available values for planes are:
5093 Choosing planes not available in the input will result in an error.
5094 That means you cannot select @code{r}, @code{g}, @code{b} planes
5095 with @code{y}, @code{u}, @code{v} planes at same time.
5098 @subsection Examples
5102 Extract luma, u and v color channel component from input video frame
5103 into 3 grayscale outputs:
5105 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
5111 Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
5113 For each input image, the filter will compute the optimal mapping from
5114 the input to the output given the codebook length, that is the number
5115 of distinct output colors.
5117 This filter accepts the following options.
5120 @item codebook_length, l
5121 Set codebook length. The value must be a positive integer, and
5122 represents the number of distinct output colors. Default value is 256.
5125 Set the maximum number of iterations to apply for computing the optimal
5126 mapping. The higher the value the better the result and the higher the
5127 computation time. Default value is 1.
5130 Set a random seed, must be an integer included between 0 and
5131 UINT32_MAX. If not specified, or if explicitly set to -1, the filter
5132 will try to use a good random seed on a best effort basis.
5137 Apply a fade-in/out effect to the input video.
5139 It accepts the following parameters:
5143 The effect type can be either "in" for a fade-in, or "out" for a fade-out
5145 Default is @code{in}.
5147 @item start_frame, s
5148 Specify the number of the frame to start applying the fade
5149 effect at. Default is 0.
5152 The number of frames that the fade effect lasts. At the end of the
5153 fade-in effect, the output video will have the same intensity as the input video.
5154 At the end of the fade-out transition, the output video will be filled with the
5155 selected @option{color}.
5159 If set to 1, fade only alpha channel, if one exists on the input.
5162 @item start_time, st
5163 Specify the timestamp (in seconds) of the frame to start to apply the fade
5164 effect. If both start_frame and start_time are specified, the fade will start at
5165 whichever comes last. Default is 0.
5168 The number of seconds for which the fade effect has to last. At the end of the
5169 fade-in effect the output video will have the same intensity as the input video,
5170 at the end of the fade-out transition the output video will be filled with the
5171 selected @option{color}.
5172 If both duration and nb_frames are specified, duration is used. Default is 0
5173 (nb_frames is used by default).
5176 Specify the color of the fade. Default is "black".
5179 @subsection Examples
5183 Fade in the first 30 frames of video:
5188 The command above is equivalent to:
5194 Fade out the last 45 frames of a 200-frame video:
5197 fade=type=out:start_frame=155:nb_frames=45
5201 Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
5203 fade=in:0:25, fade=out:975:25
5207 Make the first 5 frames yellow, then fade in from frame 5-24:
5209 fade=in:5:20:color=yellow
5213 Fade in alpha over first 25 frames of video:
5215 fade=in:0:25:alpha=1
5219 Make the first 5.5 seconds black, then fade in for 0.5 seconds:
5221 fade=t=in:st=5.5:d=0.5
5227 Apply arbitrary expressions to samples in frequency domain
5231 Adjust the dc value (gain) of the luma plane of the image. The filter
5232 accepts an integer value in range @code{0} to @code{1000}. The default
5233 value is set to @code{0}.
5236 Adjust the dc value (gain) of the 1st chroma plane of the image. The
5237 filter accepts an integer value in range @code{0} to @code{1000}. The
5238 default value is set to @code{0}.
5241 Adjust the dc value (gain) of the 2nd chroma plane of the image. The
5242 filter accepts an integer value in range @code{0} to @code{1000}. The
5243 default value is set to @code{0}.
5246 Set the frequency domain weight expression for the luma plane.
5249 Set the frequency domain weight expression for the 1st chroma plane.
5252 Set the frequency domain weight expression for the 2nd chroma plane.
5254 The filter accepts the following variables:
5257 The coordinates of the current sample.
5261 The width and height of the image.
5264 @subsection Examples
5270 fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
5276 fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
5282 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
5289 Extract a single field from an interlaced image using stride
5290 arithmetic to avoid wasting CPU time. The output frames are marked as
5293 The filter accepts the following options:
5297 Specify whether to extract the top (if the value is @code{0} or
5298 @code{top}) or the bottom field (if the value is @code{1} or
5304 Field matching filter for inverse telecine. It is meant to reconstruct the
5305 progressive frames from a telecined stream. The filter does not drop duplicated
5306 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
5307 followed by a decimation filter such as @ref{decimate} in the filtergraph.
5309 The separation of the field matching and the decimation is notably motivated by
5310 the possibility of inserting a de-interlacing filter fallback between the two.
5311 If the source has mixed telecined and real interlaced content,
5312 @code{fieldmatch} will not be able to match fields for the interlaced parts.
5313 But these remaining combed frames will be marked as interlaced, and thus can be
5314 de-interlaced by a later filter such as @ref{yadif} before decimation.
5316 In addition to the various configuration options, @code{fieldmatch} can take an
5317 optional second stream, activated through the @option{ppsrc} option. If
5318 enabled, the frames reconstruction will be based on the fields and frames from
5319 this second stream. This allows the first input to be pre-processed in order to
5320 help the various algorithms of the filter, while keeping the output lossless
5321 (assuming the fields are matched properly). Typically, a field-aware denoiser,
5322 or brightness/contrast adjustments can help.
5324 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
5325 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
5326 which @code{fieldmatch} is based on. While the semantic and usage are very
5327 close, some behaviour and options names can differ.
5329 The @ref{decimate} filter currently only works for constant frame rate input.
5330 Do not use @code{fieldmatch} and @ref{decimate} if your input has mixed
5331 telecined and progressive content with changing framerate.
5333 The filter accepts the following options:
5337 Specify the assumed field order of the input stream. Available values are:
5341 Auto detect parity (use FFmpeg's internal parity value).
5343 Assume bottom field first.
5345 Assume top field first.
5348 Note that it is sometimes recommended not to trust the parity announced by the
5351 Default value is @var{auto}.
5354 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
5355 sense that it won't risk creating jerkiness due to duplicate frames when
5356 possible, but if there are bad edits or blended fields it will end up
5357 outputting combed frames when a good match might actually exist. On the other
5358 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
5359 but will almost always find a good frame if there is one. The other values are
5360 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
5361 jerkiness and creating duplicate frames versus finding good matches in sections
5362 with bad edits, orphaned fields, blended fields, etc.
5364 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
5366 Available values are:
5370 2-way matching (p/c)
5372 2-way matching, and trying 3rd match if still combed (p/c + n)
5374 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
5376 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
5377 still combed (p/c + n + u/b)
5379 3-way matching (p/c/n)
5381 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
5382 detected as combed (p/c/n + u/b)
5385 The parenthesis at the end indicate the matches that would be used for that
5386 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
5389 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
5392 Default value is @var{pc_n}.
5395 Mark the main input stream as a pre-processed input, and enable the secondary
5396 input stream as the clean source to pick the fields from. See the filter
5397 introduction for more details. It is similar to the @option{clip2} feature from
5400 Default value is @code{0} (disabled).
5403 Set the field to match from. It is recommended to set this to the same value as
5404 @option{order} unless you experience matching failures with that setting. In
5405 certain circumstances changing the field that is used to match from can have a
5406 large impact on matching performance. Available values are:
5410 Automatic (same value as @option{order}).
5412 Match from the bottom field.
5414 Match from the top field.
5417 Default value is @var{auto}.
5420 Set whether or not chroma is included during the match comparisons. In most
5421 cases it is recommended to leave this enabled. You should set this to @code{0}
5422 only if your clip has bad chroma problems such as heavy rainbowing or other
5423 artifacts. Setting this to @code{0} could also be used to speed things up at
5424 the cost of some accuracy.
5426 Default value is @code{1}.
5430 These define an exclusion band which excludes the lines between @option{y0} and
5431 @option{y1} from being included in the field matching decision. An exclusion
5432 band can be used to ignore subtitles, a logo, or other things that may
5433 interfere with the matching. @option{y0} sets the starting scan line and
5434 @option{y1} sets the ending line; all lines in between @option{y0} and
5435 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
5436 @option{y0} and @option{y1} to the same value will disable the feature.
5437 @option{y0} and @option{y1} defaults to @code{0}.
5440 Set the scene change detection threshold as a percentage of maximum change on
5441 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
5442 detection is only relevant in case @option{combmatch}=@var{sc}. The range for
5443 @option{scthresh} is @code{[0.0, 100.0]}.
5445 Default value is @code{12.0}.
5448 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
5449 account the combed scores of matches when deciding what match to use as the
5450 final match. Available values are:
5454 No final matching based on combed scores.
5456 Combed scores are only used when a scene change is detected.
5458 Use combed scores all the time.
5461 Default is @var{sc}.
5464 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
5465 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
5466 Available values are:
5470 No forced calculation.
5472 Force p/c/n calculations.
5474 Force p/c/n/u/b calculations.
5477 Default value is @var{none}.
5480 This is the area combing threshold used for combed frame detection. This
5481 essentially controls how "strong" or "visible" combing must be to be detected.
5482 Larger values mean combing must be more visible and smaller values mean combing
5483 can be less visible or strong and still be detected. Valid settings are from
5484 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
5485 be detected as combed). This is basically a pixel difference value. A good
5486 range is @code{[8, 12]}.
5488 Default value is @code{9}.
5491 Sets whether or not chroma is considered in the combed frame decision. Only
5492 disable this if your source has chroma problems (rainbowing, etc.) that are
5493 causing problems for the combed frame detection with chroma enabled. Actually,
5494 using @option{chroma}=@var{0} is usually more reliable, except for the case
5495 where there is chroma only combing in the source.
5497 Default value is @code{0}.
5501 Respectively set the x-axis and y-axis size of the window used during combed
5502 frame detection. This has to do with the size of the area in which
5503 @option{combpel} pixels are required to be detected as combed for a frame to be
5504 declared combed. See the @option{combpel} parameter description for more info.
5505 Possible values are any number that is a power of 2 starting at 4 and going up
5508 Default value is @code{16}.
5511 The number of combed pixels inside any of the @option{blocky} by
5512 @option{blockx} size blocks on the frame for the frame to be detected as
5513 combed. While @option{cthresh} controls how "visible" the combing must be, this
5514 setting controls "how much" combing there must be in any localized area (a
5515 window defined by the @option{blockx} and @option{blocky} settings) on the
5516 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
5517 which point no frames will ever be detected as combed). This setting is known
5518 as @option{MI} in TFM/VFM vocabulary.
5520 Default value is @code{80}.
5523 @anchor{p/c/n/u/b meaning}
5524 @subsection p/c/n/u/b meaning
5526 @subsubsection p/c/n
5528 We assume the following telecined stream:
5531 Top fields: 1 2 2 3 4
5532 Bottom fields: 1 2 3 4 4
5535 The numbers correspond to the progressive frame the fields relate to. Here, the
5536 first two frames are progressive, the 3rd and 4th are combed, and so on.
5538 When @code{fieldmatch} is configured to run a matching from bottom
5539 (@option{field}=@var{bottom}) this is how this input stream get transformed:
5544 B 1 2 3 4 4 <-- matching reference
5553 As a result of the field matching, we can see that some frames get duplicated.
5554 To perform a complete inverse telecine, you need to rely on a decimation filter
5555 after this operation. See for instance the @ref{decimate} filter.
5557 The same operation now matching from top fields (@option{field}=@var{top})
5562 T 1 2 2 3 4 <-- matching reference
5572 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
5573 basically, they refer to the frame and field of the opposite parity:
5576 @item @var{p} matches the field of the opposite parity in the previous frame
5577 @item @var{c} matches the field of the opposite parity in the current frame
5578 @item @var{n} matches the field of the opposite parity in the next frame
5583 The @var{u} and @var{b} matching are a bit special in the sense that they match
5584 from the opposite parity flag. In the following examples, we assume that we are
5585 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
5586 'x' is placed above and below each matched fields.
5588 With bottom matching (@option{field}=@var{bottom}):
5593 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
5594 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
5602 With top matching (@option{field}=@var{top}):
5607 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
5608 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
5616 @subsection Examples
5618 Simple IVTC of a top field first telecined stream:
5620 fieldmatch=order=tff:combmatch=none, decimate
5623 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
5625 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
5630 Transform the field order of the input video.
5632 It accepts the following parameters:
5637 The output field order. Valid values are @var{tff} for top field first or @var{bff}
5638 for bottom field first.
5641 The default value is @samp{tff}.
5643 The transformation is done by shifting the picture content up or down
5644 by one line, and filling the remaining line with appropriate picture content.
5645 This method is consistent with most broadcast field order converters.
5647 If the input video is not flagged as being interlaced, or it is already
5648 flagged as being of the required output field order, then this filter does
5649 not alter the incoming video.
5651 It is very useful when converting to or from PAL DV material,
5652 which is bottom field first.
5656 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
5661 Buffer input images and send them when they are requested.
5663 It is mainly useful when auto-inserted by the libavfilter
5666 It does not take parameters.
5670 Find a rectangular object
5672 It accepts the following options:
5676 Filepath of the object image, needs to be in gray8.
5679 Detection threshold, default is 0.5.
5682 Number of mipmaps, default is 3.
5684 @item xmin, ymin, xmax, ymax
5685 Specifies the rectangle in which to search.
5688 @subsection Examples
5692 Generate a representative palette of a given video using @command{ffmpeg}:
5694 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
5700 Cover a rectangular object
5702 It accepts the following options:
5706 Filepath of the optional cover image, needs to be in yuv420.
5711 It accepts the following values:
5714 cover it by the supplied image
5716 cover it by interpolating the surrounding pixels
5719 Default value is @var{blur}.
5722 @subsection Examples
5726 Generate a representative palette of a given video using @command{ffmpeg}:
5728 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
5735 Convert the input video to one of the specified pixel formats.
5736 Libavfilter will try to pick one that is suitable as input to
5739 It accepts the following parameters:
5743 A '|'-separated list of pixel format names, such as
5744 "pix_fmts=yuv420p|monow|rgb24".
5748 @subsection Examples
5752 Convert the input video to the @var{yuv420p} format
5754 format=pix_fmts=yuv420p
5757 Convert the input video to any of the formats in the list
5759 format=pix_fmts=yuv420p|yuv444p|yuv410p
5766 Convert the video to specified constant frame rate by duplicating or dropping
5767 frames as necessary.
5769 It accepts the following parameters:
5773 The desired output frame rate. The default is @code{25}.
5778 Possible values are:
5781 zero round towards 0
5785 round towards -infinity
5787 round towards +infinity
5791 The default is @code{near}.
5794 Assume the first PTS should be the given value, in seconds. This allows for
5795 padding/trimming at the start of stream. By default, no assumption is made
5796 about the first frame's expected PTS, so no padding or trimming is done.
5797 For example, this could be set to 0 to pad the beginning with duplicates of
5798 the first frame if a video stream starts after the audio stream or to trim any
5799 frames with a negative PTS.
5803 Alternatively, the options can be specified as a flat string:
5804 @var{fps}[:@var{round}].
5806 See also the @ref{setpts} filter.
5808 @subsection Examples
5812 A typical usage in order to set the fps to 25:
5818 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
5820 fps=fps=film:round=near
5826 Pack two different video streams into a stereoscopic video, setting proper
5827 metadata on supported codecs. The two views should have the same size and
5828 framerate and processing will stop when the shorter video ends. Please note
5829 that you may conveniently adjust view properties with the @ref{scale} and
5832 It accepts the following parameters:
5836 The desired packing format. Supported values are:
5841 The views are next to each other (default).
5844 The views are on top of each other.
5847 The views are packed by line.
5850 The views are packed by column.
5853 The views are temporally interleaved.
5862 # Convert left and right views into a frame-sequential video
5863 ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
5865 # Convert views into a side-by-side video with the same output resolution as the input
5866 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
5871 Select one frame every N-th frame.
5873 This filter accepts the following option:
5876 Select frame after every @code{step} frames.
5877 Allowed values are positive integers higher than 0. Default value is @code{1}.
5883 Apply a frei0r effect to the input video.
5885 To enable the compilation of this filter, you need to install the frei0r
5886 header and configure FFmpeg with @code{--enable-frei0r}.
5888 It accepts the following parameters:
5893 The name of the frei0r effect to load. If the environment variable
5894 @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
5895 directories specified by the colon-separated list in @env{FREIOR_PATH}.
5896 Otherwise, the standard frei0r paths are searched, in this order:
5897 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
5898 @file{/usr/lib/frei0r-1/}.
5901 A '|'-separated list of parameters to pass to the frei0r effect.
5905 A frei0r effect parameter can be a boolean (its value is either
5906 "y" or "n"), a double, a color (specified as
5907 @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
5908 numbers between 0.0 and 1.0, inclusive) or by a color description specified in the "Color"
5909 section in the ffmpeg-utils manual), a position (specified as @var{X}/@var{Y}, where
5910 @var{X} and @var{Y} are floating point numbers) and/or a string.
5912 The number and types of parameters depend on the loaded effect. If an
5913 effect parameter is not specified, the default value is set.
5915 @subsection Examples
5919 Apply the distort0r effect, setting the first two double parameters:
5921 frei0r=filter_name=distort0r:filter_params=0.5|0.01
5925 Apply the colordistance effect, taking a color as the first parameter:
5927 frei0r=colordistance:0.2/0.3/0.4
5928 frei0r=colordistance:violet
5929 frei0r=colordistance:0x112233
5933 Apply the perspective effect, specifying the top left and top right image
5936 frei0r=perspective:0.2/0.2|0.8/0.2
5940 For more information, see
5941 @url{http://frei0r.dyne.org}
5945 Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
5947 It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
5948 processing filter, one of them is performed once per block, not per pixel.
5949 This allows for much higher speed.
5951 The filter accepts the following options:
5955 Set quality. This option defines the number of levels for averaging. It accepts
5956 an integer in the range 4-5. Default value is @code{4}.
5959 Force a constant quantization parameter. It accepts an integer in range 0-63.
5960 If not set, the filter will use the QP from the video stream (if available).
5963 Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
5964 more details but also more artifacts, while higher values make the image smoother
5965 but also blurrier. Default value is @code{0} − PSNR optimal.
5968 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
5969 option may cause flicker since the B-Frames have often larger QP. Default is
5970 @code{0} (not enabled).
5976 The filter accepts the following options:
5980 Set the luminance expression.
5982 Set the chrominance blue expression.
5984 Set the chrominance red expression.
5986 Set the alpha expression.
5988 Set the red expression.
5990 Set the green expression.
5992 Set the blue expression.
5995 The colorspace is selected according to the specified options. If one
5996 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
5997 options is specified, the filter will automatically select a YCbCr
5998 colorspace. If one of the @option{red_expr}, @option{green_expr}, or
5999 @option{blue_expr} options is specified, it will select an RGB
6002 If one of the chrominance expression is not defined, it falls back on the other
6003 one. If no alpha expression is specified it will evaluate to opaque value.
6004 If none of chrominance expressions are specified, they will evaluate
6005 to the luminance expression.
6007 The expressions can use the following variables and functions:
6011 The sequential number of the filtered frame, starting from @code{0}.
6015 The coordinates of the current sample.
6019 The width and height of the image.
6023 Width and height scale depending on the currently filtered plane. It is the
6024 ratio between the corresponding luma plane number of pixels and the current
6025 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
6026 @code{0.5,0.5} for chroma planes.
6029 Time of the current frame, expressed in seconds.
6032 Return the value of the pixel at location (@var{x},@var{y}) of the current
6036 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
6040 Return the value of the pixel at location (@var{x},@var{y}) of the
6041 blue-difference chroma plane. Return 0 if there is no such plane.
6044 Return the value of the pixel at location (@var{x},@var{y}) of the
6045 red-difference chroma plane. Return 0 if there is no such plane.
6050 Return the value of the pixel at location (@var{x},@var{y}) of the
6051 red/green/blue component. Return 0 if there is no such component.
6054 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
6055 plane. Return 0 if there is no such plane.
6058 For functions, if @var{x} and @var{y} are outside the area, the value will be
6059 automatically clipped to the closer edge.
6061 @subsection Examples
6065 Flip the image horizontally:
6071 Generate a bidimensional sine wave, with angle @code{PI/3} and a
6072 wavelength of 100 pixels:
6074 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
6078 Generate a fancy enigmatic moving light:
6080 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
6084 Generate a quick emboss effect:
6086 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
6090 Modify RGB components depending on pixel position:
6092 geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
6096 Create a radial gradient that is the same size as the input (also see
6097 the @ref{vignette} filter):
6099 geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
6103 Create a linear gradient to use as a mask for another filter, then
6104 compose with @ref{overlay}. In this example the video will gradually
6105 become more blurry from the top to the bottom of the y-axis as defined
6106 by the linear gradient:
6108 ffmpeg -i input.mp4 -filter_complex "geq=lum=255*(Y/H),format=gray[grad];[0:v]boxblur=4[blur];[blur][grad]alphamerge[alpha];[0:v][alpha]overlay" output.mp4
6114 Fix the banding artifacts that are sometimes introduced into nearly flat
6115 regions by truncation to 8bit color depth.
6116 Interpolate the gradients that should go where the bands are, and
6119 It is designed for playback only. Do not use it prior to
6120 lossy compression, because compression tends to lose the dither and
6121 bring back the bands.
6123 It accepts the following parameters:
6128 The maximum amount by which the filter will change any one pixel. This is also
6129 the threshold for detecting nearly flat regions. Acceptable values range from
6130 .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
6134 The neighborhood to fit the gradient to. A larger radius makes for smoother
6135 gradients, but also prevents the filter from modifying the pixels near detailed
6136 regions. Acceptable values are 8-32; the default value is 16. Out-of-range
6137 values will be clipped to the valid range.
6141 Alternatively, the options can be specified as a flat string:
6142 @var{strength}[:@var{radius}]
6144 @subsection Examples
6148 Apply the filter with a @code{3.5} strength and radius of @code{8}:
6154 Specify radius, omitting the strength (which will fall-back to the default
6165 Apply a Hald CLUT to a video stream.
6167 First input is the video stream to process, and second one is the Hald CLUT.
6168 The Hald CLUT input can be a simple picture or a complete video stream.
6170 The filter accepts the following options:
6174 Force termination when the shortest input terminates. Default is @code{0}.
6176 Continue applying the last CLUT after the end of the stream. A value of
6177 @code{0} disable the filter after the last frame of the CLUT is reached.
6178 Default is @code{1}.
6181 @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
6182 filters share the same internals).
6184 More information about the Hald CLUT can be found on Eskil Steenberg's website
6185 (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
6187 @subsection Workflow examples
6189 @subsubsection Hald CLUT video stream
6191 Generate an identity Hald CLUT stream altered with various effects:
6193 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
6196 Note: make sure you use a lossless codec.
6198 Then use it with @code{haldclut} to apply it on some random stream:
6200 ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
6203 The Hald CLUT will be applied to the 10 first seconds (duration of
6204 @file{clut.nut}), then the latest picture of that CLUT stream will be applied
6205 to the remaining frames of the @code{mandelbrot} stream.
6207 @subsubsection Hald CLUT with preview
6209 A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
6210 @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
6211 biggest possible square starting at the top left of the picture. The remaining
6212 padding pixels (bottom or right) will be ignored. This area can be used to add
6213 a preview of the Hald CLUT.
6215 Typically, the following generated Hald CLUT will be supported by the
6216 @code{haldclut} filter:
6219 ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
6220 pad=iw+320 [padded_clut];
6221 smptebars=s=320x256, split [a][b];
6222 [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
6223 [main][b] overlay=W-320" -frames:v 1 clut.png
6226 It contains the original and a preview of the effect of the CLUT: SMPTE color
6227 bars are displayed on the right-top, and below the same color bars processed by
6230 Then, the effect of this Hald CLUT can be visualized with:
6232 ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
6237 Flip the input video horizontally.
6239 For example, to horizontally flip the input video with @command{ffmpeg}:
6241 ffmpeg -i in.avi -vf "hflip" out.avi
6245 This filter applies a global color histogram equalization on a
6248 It can be used to correct video that has a compressed range of pixel
6249 intensities. The filter redistributes the pixel intensities to
6250 equalize their distribution across the intensity range. It may be
6251 viewed as an "automatically adjusting contrast filter". This filter is
6252 useful only for correcting degraded or poorly captured source
6255 The filter accepts the following options:
6259 Determine the amount of equalization to be applied. As the strength
6260 is reduced, the distribution of pixel intensities more-and-more
6261 approaches that of the input frame. The value must be a float number
6262 in the range [0,1] and defaults to 0.200.
6265 Set the maximum intensity that can generated and scale the output
6266 values appropriately. The strength should be set as desired and then
6267 the intensity can be limited if needed to avoid washing-out. The value
6268 must be a float number in the range [0,1] and defaults to 0.210.
6271 Set the antibanding level. If enabled the filter will randomly vary
6272 the luminance of output pixels by a small amount to avoid banding of
6273 the histogram. Possible values are @code{none}, @code{weak} or
6274 @code{strong}. It defaults to @code{none}.
6279 Compute and draw a color distribution histogram for the input video.
6281 The computed histogram is a representation of the color component
6282 distribution in an image.
6284 The filter accepts the following options:
6290 It accepts the following values:
6293 Standard histogram that displays the color components distribution in an
6294 image. Displays color graph for each color component. Shows distribution of
6295 the Y, U, V, A or R, G, B components, depending on input format, in the
6296 current frame. Below each graph a color component scale meter is shown.
6299 Displays chroma values (U/V color placement) in a two dimensional
6300 graph (which is called a vectorscope). The brighter a pixel in the
6301 vectorscope, the more pixels of the input frame correspond to that pixel
6302 (i.e., more pixels have this chroma value). The V component is displayed on
6303 the horizontal (X) axis, with the leftmost side being V = 0 and the rightmost
6304 side being V = 255. The U component is displayed on the vertical (Y) axis,
6305 with the top representing U = 0 and the bottom representing U = 255.
6307 The position of a white pixel in the graph corresponds to the chroma value of
6308 a pixel of the input clip. The graph can therefore be used to read the hue
6309 (color flavor) and the saturation (the dominance of the hue in the color). As
6310 the hue of a color changes, it moves around the square. At the center of the
6311 square the saturation is zero, which means that the corresponding pixel has no
6312 color. If the amount of a specific color is increased (while leaving the other
6313 colors unchanged) the saturation increases, and the indicator moves towards
6314 the edge of the square.
6317 Chroma values in vectorscope, similar as @code{color} but actual chroma values
6321 Per row/column color component graph. In row mode, the graph on the left side
6322 represents color component value 0 and the right side represents value = 255.
6323 In column mode, the top side represents color component value = 0 and bottom
6324 side represents value = 255.
6326 Default value is @code{levels}.
6329 Set height of level in @code{levels}. Default value is @code{200}.
6330 Allowed range is [50, 2048].
6333 Set height of color scale in @code{levels}. Default value is @code{12}.
6334 Allowed range is [0, 40].
6337 Set step for @code{waveform} mode. Smaller values are useful to find out how
6338 many values of the same luminance are distributed across input rows/columns.
6339 Default value is @code{10}. Allowed range is [1, 255].
6342 Set mode for @code{waveform}. Can be either @code{row}, or @code{column}.
6343 Default is @code{row}.
6345 @item waveform_mirror
6346 Set mirroring mode for @code{waveform}. @code{0} means unmirrored, @code{1}
6347 means mirrored. In mirrored mode, higher values will be represented on the left
6348 side for @code{row} mode and at the top for @code{column} mode. Default is
6349 @code{0} (unmirrored).
6352 Set display mode for @code{waveform} and @code{levels}.
6353 It accepts the following values:
6356 Display separate graph for the color components side by side in
6357 @code{row} waveform mode or one below the other in @code{column} waveform mode
6358 for @code{waveform} histogram mode. For @code{levels} histogram mode,
6359 per color component graphs are placed below each other.
6361 Using this display mode in @code{waveform} histogram mode makes it easy to
6362 spot color casts in the highlights and shadows of an image, by comparing the
6363 contours of the top and the bottom graphs of each waveform. Since whites,
6364 grays, and blacks are characterized by exactly equal amounts of red, green,
6365 and blue, neutral areas of the picture should display three waveforms of
6366 roughly equal width/height. If not, the correction is easy to perform by
6367 making level adjustments the three waveforms.
6370 Presents information identical to that in the @code{parade}, except
6371 that the graphs representing color components are superimposed directly
6374 This display mode in @code{waveform} histogram mode makes it easier to spot
6375 relative differences or similarities in overlapping areas of the color
6376 components that are supposed to be identical, such as neutral whites, grays,
6379 Default is @code{parade}.
6382 Set mode for @code{levels}. Can be either @code{linear}, or @code{logarithmic}.
6383 Default is @code{linear}.
6386 @subsection Examples
6391 Calculate and draw histogram:
6393 ffplay -i input -vf histogram
6401 This is a high precision/quality 3d denoise filter. It aims to reduce
6402 image noise, producing smooth images and making still images really
6403 still. It should enhance compressibility.
6405 It accepts the following optional parameters:
6409 A non-negative floating point number which specifies spatial luma strength.
6412 @item chroma_spatial
6413 A non-negative floating point number which specifies spatial chroma strength.
6414 It defaults to 3.0*@var{luma_spatial}/4.0.
6417 A floating point number which specifies luma temporal strength. It defaults to
6418 6.0*@var{luma_spatial}/4.0.
6421 A floating point number which specifies chroma temporal strength. It defaults to
6422 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
6427 Apply a high-quality magnification filter designed for pixel art. This filter
6428 was originally created by Maxim Stepin.
6430 It accepts the following option:
6434 Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
6435 @code{hq3x} and @code{4} for @code{hq4x}.
6436 Default is @code{3}.
6441 Modify the hue and/or the saturation of the input.
6443 It accepts the following parameters:
6447 Specify the hue angle as a number of degrees. It accepts an expression,
6448 and defaults to "0".
6451 Specify the saturation in the [-10,10] range. It accepts an expression and
6455 Specify the hue angle as a number of radians. It accepts an
6456 expression, and defaults to "0".
6459 Specify the brightness in the [-10,10] range. It accepts an expression and
6463 @option{h} and @option{H} are mutually exclusive, and can't be
6464 specified at the same time.
6466 The @option{b}, @option{h}, @option{H} and @option{s} option values are
6467 expressions containing the following constants:
6471 frame count of the input frame starting from 0
6474 presentation timestamp of the input frame expressed in time base units
6477 frame rate of the input video, NAN if the input frame rate is unknown
6480 timestamp expressed in seconds, NAN if the input timestamp is unknown
6483 time base of the input video
6486 @subsection Examples
6490 Set the hue to 90 degrees and the saturation to 1.0:
6496 Same command but expressing the hue in radians:
6502 Rotate hue and make the saturation swing between 0
6503 and 2 over a period of 1 second:
6505 hue="H=2*PI*t: s=sin(2*PI*t)+1"
6509 Apply a 3 seconds saturation fade-in effect starting at 0:
6514 The general fade-in expression can be written as:
6516 hue="s=min(0\, max((t-START)/DURATION\, 1))"
6520 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
6522 hue="s=max(0\, min(1\, (8-t)/3))"
6525 The general fade-out expression can be written as:
6527 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
6532 @subsection Commands
6534 This filter supports the following commands:
6540 Modify the hue and/or the saturation and/or brightness of the input video.
6541 The command accepts the same syntax of the corresponding option.
6543 If the specified expression is not valid, it is kept at its current
6549 Detect video interlacing type.
6551 This filter tries to detect if the input frames as interlaced, progressive,
6552 top or bottom field first. It will also try and detect fields that are
6553 repeated between adjacent frames (a sign of telecine).
6555 Single frame detection considers only immediately adjacent frames when classifying each frame.
6556 Multiple frame detection incorporates the classification history of previous frames.
6558 The filter will log these metadata values:
6561 @item single.current_frame
6562 Detected type of current frame using single-frame detection. One of:
6563 ``tff'' (top field first), ``bff'' (bottom field first),
6564 ``progressive'', or ``undetermined''
6567 Cumulative number of frames detected as top field first using single-frame detection.
6570 Cumulative number of frames detected as top field first using multiple-frame detection.
6573 Cumulative number of frames detected as bottom field first using single-frame detection.
6575 @item multiple.current_frame
6576 Detected type of current frame using multiple-frame detection. One of:
6577 ``tff'' (top field first), ``bff'' (bottom field first),
6578 ``progressive'', or ``undetermined''
6581 Cumulative number of frames detected as bottom field first using multiple-frame detection.
6583 @item single.progressive
6584 Cumulative number of frames detected as progressive using single-frame detection.
6586 @item multiple.progressive
6587 Cumulative number of frames detected as progressive using multiple-frame detection.
6589 @item single.undetermined
6590 Cumulative number of frames that could not be classified using single-frame detection.
6592 @item multiple.undetermined
6593 Cumulative number of frames that could not be classified using multiple-frame detection.
6595 @item repeated.current_frame
6596 Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
6598 @item repeated.neither
6599 Cumulative number of frames with no repeated field.
6602 Cumulative number of frames with the top field repeated from the previous frame's top field.
6604 @item repeated.bottom
6605 Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
6608 The filter accepts the following options:
6612 Set interlacing threshold.
6614 Set progressive threshold.
6616 Threshold for repeated field detection.
6618 Number of frames after which a given frame's contribution to the
6619 statistics is halved (i.e., it contributes only 0.5 to it's
6620 classification). The default of 0 means that all frames seen are given
6621 full weight of 1.0 forever.
6622 @item analyze_interlaced_flag
6623 When this is not 0 then idet will use the specified number of frames to determine
6624 if the interlaced flag is accurate, it will not count undetermined frames.
6625 If the flag is found to be accurate it will be used without any further
6626 computations, if it is found to be inaccurate it will be cleared without any
6627 further computations. This allows inserting the idet filter as a low computational
6628 method to clean up the interlaced flag
6633 Deinterleave or interleave fields.
6635 This filter allows one to process interlaced images fields without
6636 deinterlacing them. Deinterleaving splits the input frame into 2
6637 fields (so called half pictures). Odd lines are moved to the top
6638 half of the output image, even lines to the bottom half.
6639 You can process (filter) them independently and then re-interleave them.
6641 The filter accepts the following options:
6645 @item chroma_mode, c
6647 Available values for @var{luma_mode}, @var{chroma_mode} and
6648 @var{alpha_mode} are:
6654 @item deinterleave, d
6655 Deinterleave fields, placing one above the other.
6658 Interleave fields. Reverse the effect of deinterleaving.
6660 Default value is @code{none}.
6663 @item chroma_swap, cs
6664 @item alpha_swap, as
6665 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
6670 Apply inflate effect to the video.
6672 This filter replaces the pixel by the local(3x3) average by taking into account
6673 only values higher than the pixel.
6675 It accepts the following options:
6682 Allows to limit the maximum change for each plane, default is 65535.
6683 If 0, plane will remain unchanged.
6688 Simple interlacing filter from progressive contents. This interleaves upper (or
6689 lower) lines from odd frames with lower (or upper) lines from even frames,
6690 halving the frame rate and preserving image height.
6693 Original Original New Frame
6694 Frame 'j' Frame 'j+1' (tff)
6695 ========== =========== ==================
6696 Line 0 --------------------> Frame 'j' Line 0
6697 Line 1 Line 1 ----> Frame 'j+1' Line 1
6698 Line 2 ---------------------> Frame 'j' Line 2
6699 Line 3 Line 3 ----> Frame 'j+1' Line 3
6701 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
6704 It accepts the following optional parameters:
6708 This determines whether the interlaced frame is taken from the even
6709 (tff - default) or odd (bff) lines of the progressive frame.
6712 Enable (default) or disable the vertical lowpass filter to avoid twitter
6713 interlacing and reduce moire patterns.
6718 Deinterlace input video by applying Donald Graft's adaptive kernel
6719 deinterling. Work on interlaced parts of a video to produce
6722 The description of the accepted parameters follows.
6726 Set the threshold which affects the filter's tolerance when
6727 determining if a pixel line must be processed. It must be an integer
6728 in the range [0,255] and defaults to 10. A value of 0 will result in
6729 applying the process on every pixels.
6732 Paint pixels exceeding the threshold value to white if set to 1.
6736 Set the fields order. Swap fields if set to 1, leave fields alone if
6740 Enable additional sharpening if set to 1. Default is 0.
6743 Enable twoway sharpening if set to 1. Default is 0.
6746 @subsection Examples
6750 Apply default values:
6752 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
6756 Enable additional sharpening:
6762 Paint processed pixels in white:
6768 @section lenscorrection
6770 Correct radial lens distortion
6772 This filter can be used to correct for radial distortion as can result from the use
6773 of wide angle lenses, and thereby re-rectify the image. To find the right parameters
6774 one can use tools available for example as part of opencv or simply trial-and-error.
6775 To use opencv use the calibration sample (under samples/cpp) from the opencv sources
6776 and extract the k1 and k2 coefficients from the resulting matrix.
6778 Note that effectively the same filter is available in the open-source tools Krita and
6779 Digikam from the KDE project.
6781 In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
6782 this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
6783 brightness distribution, so you may want to use both filters together in certain
6784 cases, though you will have to take care of ordering, i.e. whether vignetting should
6785 be applied before or after lens correction.
6789 The filter accepts the following options:
6793 Relative x-coordinate of the focal point of the image, and thereby the center of the
6794 distortion. This value has a range [0,1] and is expressed as fractions of the image
6797 Relative y-coordinate of the focal point of the image, and thereby the center of the
6798 distortion. This value has a range [0,1] and is expressed as fractions of the image
6801 Coefficient of the quadratic correction term. 0.5 means no correction.
6803 Coefficient of the double quadratic correction term. 0.5 means no correction.
6806 The formula that generates the correction is:
6808 @var{r_src} = @var{r_tgt} * (1 + @var{k1} * (@var{r_tgt} / @var{r_0})^2 + @var{k2} * (@var{r_tgt} / @var{r_0})^4)
6810 where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
6811 distances from the focal point in the source and target images, respectively.
6816 Apply a 3D LUT to an input video.
6818 The filter accepts the following options:
6822 Set the 3D LUT file name.
6824 Currently supported formats:
6836 Select interpolation mode.
6838 Available values are:
6842 Use values from the nearest defined point.
6844 Interpolate values using the 8 points defining a cube.
6846 Interpolate values using a tetrahedron.
6850 @section lut, lutrgb, lutyuv
6852 Compute a look-up table for binding each pixel component input value
6853 to an output value, and apply it to the input video.
6855 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
6856 to an RGB input video.
6858 These filters accept the following parameters:
6861 set first pixel component expression
6863 set second pixel component expression
6865 set third pixel component expression
6867 set fourth pixel component expression, corresponds to the alpha component
6870 set red component expression
6872 set green component expression
6874 set blue component expression
6876 alpha component expression
6879 set Y/luminance component expression
6881 set U/Cb component expression
6883 set V/Cr component expression
6886 Each of them specifies the expression to use for computing the lookup table for
6887 the corresponding pixel component values.
6889 The exact component associated to each of the @var{c*} options depends on the
6892 The @var{lut} filter requires either YUV or RGB pixel formats in input,
6893 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
6895 The expressions can contain the following constants and functions:
6900 The input width and height.
6903 The input value for the pixel component.
6906 The input value, clipped to the @var{minval}-@var{maxval} range.
6909 The maximum value for the pixel component.
6912 The minimum value for the pixel component.
6915 The negated value for the pixel component value, clipped to the
6916 @var{minval}-@var{maxval} range; it corresponds to the expression
6917 "maxval-clipval+minval".
6920 The computed value in @var{val}, clipped to the
6921 @var{minval}-@var{maxval} range.
6923 @item gammaval(gamma)
6924 The computed gamma correction value of the pixel component value,
6925 clipped to the @var{minval}-@var{maxval} range. It corresponds to the
6927 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
6931 All expressions default to "val".
6933 @subsection Examples
6939 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
6940 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
6943 The above is the same as:
6945 lutrgb="r=negval:g=negval:b=negval"
6946 lutyuv="y=negval:u=negval:v=negval"
6956 Remove chroma components, turning the video into a graytone image:
6958 lutyuv="u=128:v=128"
6962 Apply a luma burning effect:
6968 Remove green and blue components:
6974 Set a constant alpha channel value on input:
6976 format=rgba,lutrgb=a="maxval-minval/2"
6980 Correct luminance gamma by a factor of 0.5:
6982 lutyuv=y=gammaval(0.5)
6986 Discard least significant bits of luma:
6988 lutyuv=y='bitand(val, 128+64+32)'
6992 @section mergeplanes
6994 Merge color channel components from several video streams.
6996 The filter accepts up to 4 input streams, and merge selected input
6997 planes to the output video.
6999 This filter accepts the following options:
7002 Set input to output plane mapping. Default is @code{0}.
7004 The mappings is specified as a bitmap. It should be specified as a
7005 hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
7006 mapping for the first plane of the output stream. 'A' sets the number of
7007 the input stream to use (from 0 to 3), and 'a' the plane number of the
7008 corresponding input to use (from 0 to 3). The rest of the mappings is
7009 similar, 'Bb' describes the mapping for the output stream second
7010 plane, 'Cc' describes the mapping for the output stream third plane and
7011 'Dd' describes the mapping for the output stream fourth plane.
7014 Set output pixel format. Default is @code{yuva444p}.
7017 @subsection Examples
7021 Merge three gray video streams of same width and height into single video stream:
7023 [a0][a1][a2]mergeplanes=0x001020:yuv444p
7027 Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
7029 [a0][a1]mergeplanes=0x00010210:yuva444p
7033 Swap Y and A plane in yuva444p stream:
7035 format=yuva444p,mergeplanes=0x03010200:yuva444p
7039 Swap U and V plane in yuv420p stream:
7041 format=yuv420p,mergeplanes=0x000201:yuv420p
7045 Cast a rgb24 clip to yuv444p:
7047 format=rgb24,mergeplanes=0x000102:yuv444p
7053 Apply motion-compensation deinterlacing.
7055 It needs one field per frame as input and must thus be used together
7056 with yadif=1/3 or equivalent.
7058 This filter accepts the following options:
7061 Set the deinterlacing mode.
7063 It accepts one of the following values:
7068 use iterative motion estimation
7070 like @samp{slow}, but use multiple reference frames.
7072 Default value is @samp{fast}.
7075 Set the picture field parity assumed for the input video. It must be
7076 one of the following values:
7080 assume top field first
7082 assume bottom field first
7085 Default value is @samp{bff}.
7088 Set per-block quantization parameter (QP) used by the internal
7091 Higher values should result in a smoother motion vector field but less
7092 optimal individual vectors. Default value is 1.
7097 Drop frames that do not differ greatly from the previous frame in
7098 order to reduce frame rate.
7100 The main use of this filter is for very-low-bitrate encoding
7101 (e.g. streaming over dialup modem), but it could in theory be used for
7102 fixing movies that were inverse-telecined incorrectly.
7104 A description of the accepted options follows.
7108 Set the maximum number of consecutive frames which can be dropped (if
7109 positive), or the minimum interval between dropped frames (if
7110 negative). If the value is 0, the frame is dropped unregarding the
7111 number of previous sequentially dropped frames.
7118 Set the dropping threshold values.
7120 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
7121 represent actual pixel value differences, so a threshold of 64
7122 corresponds to 1 unit of difference for each pixel, or the same spread
7123 out differently over the block.
7125 A frame is a candidate for dropping if no 8x8 blocks differ by more
7126 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
7127 meaning the whole image) differ by more than a threshold of @option{lo}.
7129 Default value for @option{hi} is 64*12, default value for @option{lo} is
7130 64*5, and default value for @option{frac} is 0.33.
7138 It accepts an integer in input; if non-zero it negates the
7139 alpha component (if available). The default value in input is 0.
7143 Force libavfilter not to use any of the specified pixel formats for the
7144 input to the next filter.
7146 It accepts the following parameters:
7150 A '|'-separated list of pixel format names, such as
7151 apix_fmts=yuv420p|monow|rgb24".
7155 @subsection Examples
7159 Force libavfilter to use a format different from @var{yuv420p} for the
7160 input to the vflip filter:
7162 noformat=pix_fmts=yuv420p,vflip
7166 Convert the input video to any of the formats not contained in the list:
7168 noformat=yuv420p|yuv444p|yuv410p
7174 Add noise on video input frame.
7176 The filter accepts the following options:
7184 Set noise seed for specific pixel component or all pixel components in case
7185 of @var{all_seed}. Default value is @code{123457}.
7187 @item all_strength, alls
7188 @item c0_strength, c0s
7189 @item c1_strength, c1s
7190 @item c2_strength, c2s
7191 @item c3_strength, c3s
7192 Set noise strength for specific pixel component or all pixel components in case
7193 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
7195 @item all_flags, allf
7200 Set pixel component flags or set flags for all components if @var{all_flags}.
7201 Available values for component flags are:
7204 averaged temporal noise (smoother)
7206 mix random noise with a (semi)regular pattern
7208 temporal noise (noise pattern changes between frames)
7210 uniform noise (gaussian otherwise)
7214 @subsection Examples
7216 Add temporal and uniform noise to input video:
7218 noise=alls=20:allf=t+u
7223 Pass the video source unchanged to the output.
7227 Apply a video transform using libopencv.
7229 To enable this filter, install the libopencv library and headers and
7230 configure FFmpeg with @code{--enable-libopencv}.
7232 It accepts the following parameters:
7237 The name of the libopencv filter to apply.
7240 The parameters to pass to the libopencv filter. If not specified, the default
7245 Refer to the official libopencv documentation for more precise
7247 @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
7249 Several libopencv filters are supported; see the following subsections.
7254 Dilate an image by using a specific structuring element.
7255 It corresponds to the libopencv function @code{cvDilate}.
7257 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
7259 @var{struct_el} represents a structuring element, and has the syntax:
7260 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
7262 @var{cols} and @var{rows} represent the number of columns and rows of
7263 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
7264 point, and @var{shape} the shape for the structuring element. @var{shape}
7265 must be "rect", "cross", "ellipse", or "custom".
7267 If the value for @var{shape} is "custom", it must be followed by a
7268 string of the form "=@var{filename}". The file with name
7269 @var{filename} is assumed to represent a binary image, with each
7270 printable character corresponding to a bright pixel. When a custom
7271 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
7272 or columns and rows of the read file are assumed instead.
7274 The default value for @var{struct_el} is "3x3+0x0/rect".
7276 @var{nb_iterations} specifies the number of times the transform is
7277 applied to the image, and defaults to 1.
7281 # Use the default values
7284 # Dilate using a structuring element with a 5x5 cross, iterating two times
7285 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
7287 # Read the shape from the file diamond.shape, iterating two times.
7288 # The file diamond.shape may contain a pattern of characters like this
7294 # The specified columns and rows are ignored
7295 # but the anchor point coordinates are not
7296 ocv=dilate:0x0+2x2/custom=diamond.shape|2
7301 Erode an image by using a specific structuring element.
7302 It corresponds to the libopencv function @code{cvErode}.
7304 It accepts the parameters: @var{struct_el}:@var{nb_iterations},
7305 with the same syntax and semantics as the @ref{dilate} filter.
7309 Smooth the input video.
7311 The filter takes the following parameters:
7312 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
7314 @var{type} is the type of smooth filter to apply, and must be one of
7315 the following values: "blur", "blur_no_scale", "median", "gaussian",
7316 or "bilateral". The default value is "gaussian".
7318 The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
7319 depend on the smooth type. @var{param1} and
7320 @var{param2} accept integer positive values or 0. @var{param3} and
7321 @var{param4} accept floating point values.
7323 The default value for @var{param1} is 3. The default value for the
7324 other parameters is 0.
7326 These parameters correspond to the parameters assigned to the
7327 libopencv function @code{cvSmooth}.
7332 Overlay one video on top of another.
7334 It takes two inputs and has one output. The first input is the "main"
7335 video on which the second input is overlaid.
7337 It accepts the following parameters:
7339 A description of the accepted options follows.
7344 Set the expression for the x and y coordinates of the overlaid video
7345 on the main video. Default value is "0" for both expressions. In case
7346 the expression is invalid, it is set to a huge value (meaning that the
7347 overlay will not be displayed within the output visible area).
7350 The action to take when EOF is encountered on the secondary input; it accepts
7351 one of the following values:
7355 Repeat the last frame (the default).
7359 Pass the main input through.
7363 Set when the expressions for @option{x}, and @option{y} are evaluated.
7365 It accepts the following values:
7368 only evaluate expressions once during the filter initialization or
7369 when a command is processed
7372 evaluate expressions for each incoming frame
7375 Default value is @samp{frame}.
7378 If set to 1, force the output to terminate when the shortest input
7379 terminates. Default value is 0.
7382 Set the format for the output video.
7384 It accepts the following values:
7399 Default value is @samp{yuv420}.
7401 @item rgb @emph{(deprecated)}
7402 If set to 1, force the filter to accept inputs in the RGB
7403 color space. Default value is 0. This option is deprecated, use
7404 @option{format} instead.
7407 If set to 1, force the filter to draw the last overlay frame over the
7408 main input until the end of the stream. A value of 0 disables this
7409 behavior. Default value is 1.
7412 The @option{x}, and @option{y} expressions can contain the following
7418 The main input width and height.
7422 The overlay input width and height.
7426 The computed values for @var{x} and @var{y}. They are evaluated for
7431 horizontal and vertical chroma subsample values of the output
7432 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
7436 the number of input frame, starting from 0
7439 the position in the file of the input frame, NAN if unknown
7442 The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
7446 Note that the @var{n}, @var{pos}, @var{t} variables are available only
7447 when evaluation is done @emph{per frame}, and will evaluate to NAN
7448 when @option{eval} is set to @samp{init}.
7450 Be aware that frames are taken from each input video in timestamp
7451 order, hence, if their initial timestamps differ, it is a good idea
7452 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
7453 have them begin in the same zero timestamp, as the example for
7454 the @var{movie} filter does.
7456 You can chain together more overlays but you should test the
7457 efficiency of such approach.
7459 @subsection Commands
7461 This filter supports the following commands:
7465 Modify the x and y of the overlay input.
7466 The command accepts the same syntax of the corresponding option.
7468 If the specified expression is not valid, it is kept at its current
7472 @subsection Examples
7476 Draw the overlay at 10 pixels from the bottom right corner of the main
7479 overlay=main_w-overlay_w-10:main_h-overlay_h-10
7482 Using named options the example above becomes:
7484 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
7488 Insert a transparent PNG logo in the bottom left corner of the input,
7489 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
7491 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
7495 Insert 2 different transparent PNG logos (second logo on bottom
7496 right corner) using the @command{ffmpeg} tool:
7498 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
7502 Add a transparent color layer on top of the main video; @code{WxH}
7503 must specify the size of the main input to the overlay filter:
7505 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
7509 Play an original video and a filtered version (here with the deshake
7510 filter) side by side using the @command{ffplay} tool:
7512 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
7515 The above command is the same as:
7517 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
7521 Make a sliding overlay appearing from the left to the right top part of the
7522 screen starting since time 2:
7524 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
7528 Compose output by putting two input videos side to side:
7530 ffmpeg -i left.avi -i right.avi -filter_complex "
7531 nullsrc=size=200x100 [background];
7532 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
7533 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
7534 [background][left] overlay=shortest=1 [background+left];
7535 [background+left][right] overlay=shortest=1:x=100 [left+right]
7540 Mask 10-20 seconds of a video by applying the delogo filter to a section
7542 ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
7543 -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]'
7548 Chain several overlays in cascade:
7550 nullsrc=s=200x200 [bg];
7551 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
7552 [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
7553 [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
7554 [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
7555 [in3] null, [mid2] overlay=100:100 [out0]
7562 Apply Overcomplete Wavelet denoiser.
7564 The filter accepts the following options:
7570 Larger depth values will denoise lower frequency components more, but
7571 slow down filtering.
7573 Must be an int in the range 8-16, default is @code{8}.
7575 @item luma_strength, ls
7578 Must be a double value in the range 0-1000, default is @code{1.0}.
7580 @item chroma_strength, cs
7581 Set chroma strength.
7583 Must be a double value in the range 0-1000, default is @code{1.0}.
7588 Add paddings to the input image, and place the original input at the
7589 provided @var{x}, @var{y} coordinates.
7591 It accepts the following parameters:
7596 Specify an expression for the size of the output image with the
7597 paddings added. If the value for @var{width} or @var{height} is 0, the
7598 corresponding input size is used for the output.
7600 The @var{width} expression can reference the value set by the
7601 @var{height} expression, and vice versa.
7603 The default value of @var{width} and @var{height} is 0.
7607 Specify the offsets to place the input image at within the padded area,
7608 with respect to the top/left border of the output image.
7610 The @var{x} expression can reference the value set by the @var{y}
7611 expression, and vice versa.
7613 The default value of @var{x} and @var{y} is 0.
7616 Specify the color of the padded area. For the syntax of this option,
7617 check the "Color" section in the ffmpeg-utils manual.
7619 The default value of @var{color} is "black".
7622 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
7623 options are expressions containing the following constants:
7628 The input video width and height.
7632 These are the same as @var{in_w} and @var{in_h}.
7636 The output width and height (the size of the padded area), as
7637 specified by the @var{width} and @var{height} expressions.
7641 These are the same as @var{out_w} and @var{out_h}.
7645 The x and y offsets as specified by the @var{x} and @var{y}
7646 expressions, or NAN if not yet specified.
7649 same as @var{iw} / @var{ih}
7652 input sample aspect ratio
7655 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
7659 The horizontal and vertical chroma subsample values. For example for the
7660 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
7663 @subsection Examples
7667 Add paddings with the color "violet" to the input video. The output video
7668 size is 640x480, and the top-left corner of the input video is placed at
7671 pad=640:480:0:40:violet
7674 The example above is equivalent to the following command:
7676 pad=width=640:height=480:x=0:y=40:color=violet
7680 Pad the input to get an output with dimensions increased by 3/2,
7681 and put the input video at the center of the padded area:
7683 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
7687 Pad the input to get a squared output with size equal to the maximum
7688 value between the input width and height, and put the input video at
7689 the center of the padded area:
7691 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
7695 Pad the input to get a final w/h ratio of 16:9:
7697 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
7701 In case of anamorphic video, in order to set the output display aspect
7702 correctly, it is necessary to use @var{sar} in the expression,
7703 according to the relation:
7705 (ih * X / ih) * sar = output_dar
7706 X = output_dar / sar
7709 Thus the previous example needs to be modified to:
7711 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
7715 Double the output size and put the input video in the bottom-right
7716 corner of the output padded area:
7718 pad="2*iw:2*ih:ow-iw:oh-ih"
7725 Generate one palette for a whole video stream.
7727 It accepts the following options:
7731 Set the maximum number of colors to quantize in the palette.
7732 Note: the palette will still contain 256 colors; the unused palette entries
7735 @item reserve_transparent
7736 Create a palette of 255 colors maximum and reserve the last one for
7737 transparency. Reserving the transparency color is useful for GIF optimization.
7738 If not set, the maximum of colors in the palette will be 256. You probably want
7739 to disable this option for a standalone image.
7743 Set statistics mode.
7745 It accepts the following values:
7748 Compute full frame histograms.
7750 Compute histograms only for the part that differs from previous frame. This
7751 might be relevant to give more importance to the moving part of your input if
7752 the background is static.
7755 Default value is @var{full}.
7758 The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
7759 (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
7760 color quantization of the palette. This information is also visible at
7761 @var{info} logging level.
7763 @subsection Examples
7767 Generate a representative palette of a given video using @command{ffmpeg}:
7769 ffmpeg -i input.mkv -vf palettegen palette.png
7775 Use a palette to downsample an input video stream.
7777 The filter takes two inputs: one video stream and a palette. The palette must
7778 be a 256 pixels image.
7780 It accepts the following options:
7784 Select dithering mode. Available algorithms are:
7787 Ordered 8x8 bayer dithering (deterministic)
7789 Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
7790 Note: this dithering is sometimes considered "wrong" and is included as a
7792 @item floyd_steinberg
7793 Floyd and Steingberg dithering (error diffusion)
7795 Frankie Sierra dithering v2 (error diffusion)
7797 Frankie Sierra dithering v2 "Lite" (error diffusion)
7800 Default is @var{sierra2_4a}.
7803 When @var{bayer} dithering is selected, this option defines the scale of the
7804 pattern (how much the crosshatch pattern is visible). A low value means more
7805 visible pattern for less banding, and higher value means less visible pattern
7806 at the cost of more banding.
7808 The option must be an integer value in the range [0,5]. Default is @var{2}.
7811 If set, define the zone to process
7815 Only the changing rectangle will be reprocessed. This is similar to GIF
7816 cropping/offsetting compression mechanism. This option can be useful for speed
7817 if only a part of the image is changing, and has use cases such as limiting the
7818 scope of the error diffusal @option{dither} to the rectangle that bounds the
7819 moving scene (it leads to more deterministic output if the scene doesn't change
7820 much, and as a result less moving noise and better GIF compression).
7823 Default is @var{none}.
7826 @subsection Examples
7830 Use a palette (generated for example with @ref{palettegen}) to encode a GIF
7831 using @command{ffmpeg}:
7833 ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
7837 @section perspective
7839 Correct perspective of video not recorded perpendicular to the screen.
7841 A description of the accepted parameters follows.
7852 Set coordinates expression for top left, top right, bottom left and bottom right corners.
7853 Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
7854 If the @code{sense} option is set to @code{source}, then the specified points will be sent
7855 to the corners of the destination. If the @code{sense} option is set to @code{destination},
7856 then the corners of the source will be sent to the specified coordinates.
7858 The expressions can use the following variables:
7863 the width and height of video frame.
7867 Set interpolation for perspective correction.
7869 It accepts the following values:
7875 Default value is @samp{linear}.
7878 Set interpretation of coordinate options.
7880 It accepts the following values:
7884 Send point in the source specified by the given coordinates to
7885 the corners of the destination.
7887 @item 1, destination
7889 Send the corners of the source to the point in the destination specified
7890 by the given coordinates.
7892 Default value is @samp{source}.
7898 Delay interlaced video by one field time so that the field order changes.
7900 The intended use is to fix PAL movies that have been captured with the
7901 opposite field order to the film-to-video transfer.
7903 A description of the accepted parameters follows.
7909 It accepts the following values:
7912 Capture field order top-first, transfer bottom-first.
7913 Filter will delay the bottom field.
7916 Capture field order bottom-first, transfer top-first.
7917 Filter will delay the top field.
7920 Capture and transfer with the same field order. This mode only exists
7921 for the documentation of the other options to refer to, but if you
7922 actually select it, the filter will faithfully do nothing.
7925 Capture field order determined automatically by field flags, transfer
7927 Filter selects among @samp{t} and @samp{b} modes on a frame by frame
7928 basis using field flags. If no field information is available,
7929 then this works just like @samp{u}.
7932 Capture unknown or varying, transfer opposite.
7933 Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
7934 analyzing the images and selecting the alternative that produces best
7935 match between the fields.
7938 Capture top-first, transfer unknown or varying.
7939 Filter selects among @samp{t} and @samp{p} using image analysis.
7942 Capture bottom-first, transfer unknown or varying.
7943 Filter selects among @samp{b} and @samp{p} using image analysis.
7946 Capture determined by field flags, transfer unknown or varying.
7947 Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
7948 image analysis. If no field information is available, then this works just
7949 like @samp{U}. This is the default mode.
7952 Both capture and transfer unknown or varying.
7953 Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
7957 @section pixdesctest
7959 Pixel format descriptor test filter, mainly useful for internal
7960 testing. The output video should be equal to the input video.
7964 format=monow, pixdesctest
7967 can be used to test the monowhite pixel format descriptor definition.
7971 Enable the specified chain of postprocessing subfilters using libpostproc. This
7972 library should be automatically selected with a GPL build (@code{--enable-gpl}).
7973 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
7974 Each subfilter and some options have a short and a long name that can be used
7975 interchangeably, i.e. dr/dering are the same.
7977 The filters accept the following options:
7981 Set postprocessing subfilters string.
7984 All subfilters share common options to determine their scope:
7988 Honor the quality commands for this subfilter.
7991 Do chrominance filtering, too (default).
7994 Do luminance filtering only (no chrominance).
7997 Do chrominance filtering only (no luminance).
8000 These options can be appended after the subfilter name, separated by a '|'.
8002 Available subfilters are:
8005 @item hb/hdeblock[|difference[|flatness]]
8006 Horizontal deblocking filter
8009 Difference factor where higher values mean more deblocking (default: @code{32}).
8011 Flatness threshold where lower values mean more deblocking (default: @code{39}).
8014 @item vb/vdeblock[|difference[|flatness]]
8015 Vertical deblocking filter
8018 Difference factor where higher values mean more deblocking (default: @code{32}).
8020 Flatness threshold where lower values mean more deblocking (default: @code{39}).
8023 @item ha/hadeblock[|difference[|flatness]]
8024 Accurate horizontal deblocking filter
8027 Difference factor where higher values mean more deblocking (default: @code{32}).
8029 Flatness threshold where lower values mean more deblocking (default: @code{39}).
8032 @item va/vadeblock[|difference[|flatness]]
8033 Accurate vertical deblocking filter
8036 Difference factor where higher values mean more deblocking (default: @code{32}).
8038 Flatness threshold where lower values mean more deblocking (default: @code{39}).
8042 The horizontal and vertical deblocking filters share the difference and
8043 flatness values so you cannot set different horizontal and vertical
8048 Experimental horizontal deblocking filter
8051 Experimental vertical deblocking filter
8056 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
8059 larger -> stronger filtering
8061 larger -> stronger filtering
8063 larger -> stronger filtering
8066 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
8069 Stretch luminance to @code{0-255}.
8072 @item lb/linblenddeint
8073 Linear blend deinterlacing filter that deinterlaces the given block by
8074 filtering all lines with a @code{(1 2 1)} filter.
8076 @item li/linipoldeint
8077 Linear interpolating deinterlacing filter that deinterlaces the given block by
8078 linearly interpolating every second line.
8080 @item ci/cubicipoldeint
8081 Cubic interpolating deinterlacing filter deinterlaces the given block by
8082 cubically interpolating every second line.
8084 @item md/mediandeint
8085 Median deinterlacing filter that deinterlaces the given block by applying a
8086 median filter to every second line.
8088 @item fd/ffmpegdeint
8089 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
8090 second line with a @code{(-1 4 2 4 -1)} filter.
8093 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
8094 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
8096 @item fq/forceQuant[|quantizer]
8097 Overrides the quantizer table from the input with the constant quantizer you
8105 Default pp filter combination (@code{hb|a,vb|a,dr|a})
8108 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
8111 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
8114 @subsection Examples
8118 Apply horizontal and vertical deblocking, deringing and automatic
8119 brightness/contrast:
8125 Apply default filters without brightness/contrast correction:
8131 Apply default filters and temporal denoiser:
8133 pp=default/tmpnoise|1|2|3
8137 Apply deblocking on luminance only, and switch vertical deblocking on or off
8138 automatically depending on available CPU time:
8145 Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
8146 similar to spp = 6 with 7 point DCT, where only the center sample is
8149 The filter accepts the following options:
8153 Force a constant quantization parameter. It accepts an integer in range
8154 0 to 63. If not set, the filter will use the QP from the video stream
8158 Set thresholding mode. Available modes are:
8162 Set hard thresholding.
8164 Set soft thresholding (better de-ringing effect, but likely blurrier).
8166 Set medium thresholding (good results, default).
8172 Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
8173 Ratio) between two input videos.
8175 This filter takes in input two input videos, the first input is
8176 considered the "main" source and is passed unchanged to the
8177 output. The second input is used as a "reference" video for computing
8180 Both video inputs must have the same resolution and pixel format for
8181 this filter to work correctly. Also it assumes that both inputs
8182 have the same number of frames, which are compared one by one.
8184 The obtained average PSNR is printed through the logging system.
8186 The filter stores the accumulated MSE (mean squared error) of each
8187 frame, and at the end of the processing it is averaged across all frames
8188 equally, and the following formula is applied to obtain the PSNR:
8191 PSNR = 10*log10(MAX^2/MSE)
8194 Where MAX is the average of the maximum values of each component of the
8197 The description of the accepted parameters follows.
8201 If specified the filter will use the named file to save the PSNR of
8202 each individual frame.
8205 The file printed if @var{stats_file} is selected, contains a sequence of
8206 key/value pairs of the form @var{key}:@var{value} for each compared
8209 A description of each shown parameter follows:
8213 sequential number of the input frame, starting from 1
8216 Mean Square Error pixel-by-pixel average difference of the compared
8217 frames, averaged over all the image components.
8219 @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_g, mse_a
8220 Mean Square Error pixel-by-pixel average difference of the compared
8221 frames for the component specified by the suffix.
8223 @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
8224 Peak Signal to Noise ratio of the compared frames for the component
8225 specified by the suffix.
8230 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
8231 [main][ref] psnr="stats_file=stats.log" [out]
8234 On this example the input file being processed is compared with the
8235 reference file @file{ref_movie.mpg}. The PSNR of each individual frame
8236 is stored in @file{stats.log}.
8241 Pulldown reversal (inverse telecine) filter, capable of handling mixed
8242 hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
8245 The pullup filter is designed to take advantage of future context in making
8246 its decisions. This filter is stateless in the sense that it does not lock
8247 onto a pattern to follow, but it instead looks forward to the following
8248 fields in order to identify matches and rebuild progressive frames.
8250 To produce content with an even framerate, insert the fps filter after
8251 pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
8252 @code{fps=24} for 30fps and the (rare) telecined 25fps input.
8254 The filter accepts the following options:
8261 These options set the amount of "junk" to ignore at the left, right, top, and
8262 bottom of the image, respectively. Left and right are in units of 8 pixels,
8263 while top and bottom are in units of 2 lines.
8264 The default is 8 pixels on each side.
8267 Set the strict breaks. Setting this option to 1 will reduce the chances of
8268 filter generating an occasional mismatched frame, but it may also cause an
8269 excessive number of frames to be dropped during high motion sequences.
8270 Conversely, setting it to -1 will make filter match fields more easily.
8271 This may help processing of video where there is slight blurring between
8272 the fields, but may also cause there to be interlaced frames in the output.
8273 Default value is @code{0}.
8276 Set the metric plane to use. It accepts the following values:
8282 Use chroma blue plane.
8285 Use chroma red plane.
8288 This option may be set to use chroma plane instead of the default luma plane
8289 for doing filter's computations. This may improve accuracy on very clean
8290 source material, but more likely will decrease accuracy, especially if there
8291 is chroma noise (rainbow effect) or any grayscale video.
8292 The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
8293 load and make pullup usable in realtime on slow machines.
8296 For best results (without duplicated frames in the output file) it is
8297 necessary to change the output frame rate. For example, to inverse
8298 telecine NTSC input:
8300 ffmpeg -i input -vf pullup -r 24000/1001 ...
8305 Change video quantization parameters (QP).
8307 The filter accepts the following option:
8311 Set expression for quantization parameter.
8314 The expression is evaluated through the eval API and can contain, among others,
8315 the following constants:
8319 1 if index is not 129, 0 otherwise.
8322 Sequentional index starting from -129 to 128.
8325 @subsection Examples
8337 Flush video frames from internal cache of frames into a random order.
8338 No frame is discarded.
8339 Inspired by @ref{frei0r} nervous filter.
8343 Set size in number of frames of internal cache, in range from @code{2} to
8344 @code{512}. Default is @code{30}.
8347 Set seed for random number generator, must be an integer included between
8348 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
8349 less than @code{0}, the filter will try to use a good random seed on a
8353 @section removegrain
8355 The removegrain filter is a spatial denoiser for progressive video.
8359 Set mode for the first plane.
8362 Set mode for the second plane.
8365 Set mode for the third plane.
8368 Set mode for the fourth plane.
8371 Range of mode is from 0 to 24. Description of each mode follows:
8375 Leave input plane unchanged. Default.
8378 Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
8381 Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
8384 Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
8387 Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
8388 This is equivalent to a median filter.
8391 Line-sensitive clipping giving the minimal change.
8394 Line-sensitive clipping, intermediate.
8397 Line-sensitive clipping, intermediate.
8400 Line-sensitive clipping, intermediate.
8403 Line-sensitive clipping on a line where the neighbours pixels are the closest.
8406 Replaces the target pixel with the closest neighbour.
8409 [1 2 1] horizontal and vertical kernel blur.
8415 Bob mode, interpolates top field from the line where the neighbours
8416 pixels are the closest.
8419 Bob mode, interpolates bottom field from the line where the neighbours
8420 pixels are the closest.
8423 Bob mode, interpolates top field. Same as 13 but with a more complicated
8424 interpolation formula.
8427 Bob mode, interpolates bottom field. Same as 14 but with a more complicated
8428 interpolation formula.
8431 Clips the pixel with the minimum and maximum of respectively the maximum and
8432 minimum of each pair of opposite neighbour pixels.
8435 Line-sensitive clipping using opposite neighbours whose greatest distance from
8436 the current pixel is minimal.
8439 Replaces the pixel with the average of its 8 neighbours.
8442 Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
8445 Clips pixels using the averages of opposite neighbour.
8448 Same as mode 21 but simpler and faster.
8451 Small edge and halo removal, but reputed useless.
8459 Suppress a TV station logo, using an image file to determine which
8460 pixels comprise the logo. It works by filling in the pixels that
8461 comprise the logo with neighboring pixels.
8463 The filter accepts the following options:
8467 Set the filter bitmap file, which can be any image format supported by
8468 libavformat. The width and height of the image file must match those of the
8469 video stream being processed.
8472 Pixels in the provided bitmap image with a value of zero are not
8473 considered part of the logo, non-zero pixels are considered part of
8474 the logo. If you use white (255) for the logo and black (0) for the
8475 rest, you will be safe. For making the filter bitmap, it is
8476 recommended to take a screen capture of a black frame with the logo
8477 visible, and then using a threshold filter followed by the erode
8478 filter once or twice.
8480 If needed, little splotches can be fixed manually. Remember that if
8481 logo pixels are not covered, the filter quality will be much
8482 reduced. Marking too many pixels as part of the logo does not hurt as
8483 much, but it will increase the amount of blurring needed to cover over
8484 the image and will destroy more information than necessary, and extra
8485 pixels will slow things down on a large logo.
8487 @section repeatfields
8489 This filter uses the repeat_field flag from the Video ES headers and hard repeats
8490 fields based on its value.
8496 Warning: This iflter qequires memory to buffer the entire clip, so trimming is suggested.
8498 @subsection Examples
8502 Take the first 5 seconds of a clip, and reverse it.
8510 Rotate video by an arbitrary angle expressed in radians.
8512 The filter accepts the following options:
8514 A description of the optional parameters follows.
8517 Set an expression for the angle by which to rotate the input video
8518 clockwise, expressed as a number of radians. A negative value will
8519 result in a counter-clockwise rotation. By default it is set to "0".
8521 This expression is evaluated for each frame.
8524 Set the output width expression, default value is "iw".
8525 This expression is evaluated just once during configuration.
8528 Set the output height expression, default value is "ih".
8529 This expression is evaluated just once during configuration.
8532 Enable bilinear interpolation if set to 1, a value of 0 disables
8533 it. Default value is 1.
8536 Set the color used to fill the output area not covered by the rotated
8537 image. For the general syntax of this option, check the "Color" section in the
8538 ffmpeg-utils manual. If the special value "none" is selected then no
8539 background is printed (useful for example if the background is never shown).
8541 Default value is "black".
8544 The expressions for the angle and the output size can contain the
8545 following constants and functions:
8549 sequential number of the input frame, starting from 0. It is always NAN
8550 before the first frame is filtered.
8553 time in seconds of the input frame, it is set to 0 when the filter is
8554 configured. It is always NAN before the first frame is filtered.
8558 horizontal and vertical chroma subsample values. For example for the
8559 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8563 the input video width and height
8567 the output width and height, that is the size of the padded area as
8568 specified by the @var{width} and @var{height} expressions
8572 the minimal width/height required for completely containing the input
8573 video rotated by @var{a} radians.
8575 These are only available when computing the @option{out_w} and
8576 @option{out_h} expressions.
8579 @subsection Examples
8583 Rotate the input by PI/6 radians clockwise:
8589 Rotate the input by PI/6 radians counter-clockwise:
8595 Rotate the input by 45 degrees clockwise:
8601 Apply a constant rotation with period T, starting from an angle of PI/3:
8603 rotate=PI/3+2*PI*t/T
8607 Make the input video rotation oscillating with a period of T
8608 seconds and an amplitude of A radians:
8610 rotate=A*sin(2*PI/T*t)
8614 Rotate the video, output size is chosen so that the whole rotating
8615 input video is always completely contained in the output:
8617 rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
8621 Rotate the video, reduce the output size so that no background is ever
8624 rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
8628 @subsection Commands
8630 The filter supports the following commands:
8634 Set the angle expression.
8635 The command accepts the same syntax of the corresponding option.
8637 If the specified expression is not valid, it is kept at its current
8643 Apply Shape Adaptive Blur.
8645 The filter accepts the following options:
8648 @item luma_radius, lr
8649 Set luma blur filter strength, must be a value in range 0.1-4.0, default
8650 value is 1.0. A greater value will result in a more blurred image, and
8651 in slower processing.
8653 @item luma_pre_filter_radius, lpfr
8654 Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
8657 @item luma_strength, ls
8658 Set luma maximum difference between pixels to still be considered, must
8659 be a value in the 0.1-100.0 range, default value is 1.0.
8661 @item chroma_radius, cr
8662 Set chroma blur filter strength, must be a value in range 0.1-4.0. A
8663 greater value will result in a more blurred image, and in slower
8666 @item chroma_pre_filter_radius, cpfr
8667 Set chroma pre-filter radius, must be a value in the 0.1-2.0 range.
8669 @item chroma_strength, cs
8670 Set chroma maximum difference between pixels to still be considered,
8671 must be a value in the 0.1-100.0 range.
8674 Each chroma option value, if not explicitly specified, is set to the
8675 corresponding luma option value.
8680 Scale (resize) the input video, using the libswscale library.
8682 The scale filter forces the output display aspect ratio to be the same
8683 of the input, by changing the output sample aspect ratio.
8685 If the input image format is different from the format requested by
8686 the next filter, the scale filter will convert the input to the
8690 The filter accepts the following options, or any of the options
8691 supported by the libswscale scaler.
8693 See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
8694 the complete list of scaler options.
8699 Set the output video dimension expression. Default value is the input
8702 If the value is 0, the input width is used for the output.
8704 If one of the values is -1, the scale filter will use a value that
8705 maintains the aspect ratio of the input image, calculated from the
8706 other specified dimension. If both of them are -1, the input size is
8709 If one of the values is -n with n > 1, the scale filter will also use a value
8710 that maintains the aspect ratio of the input image, calculated from the other
8711 specified dimension. After that it will, however, make sure that the calculated
8712 dimension is divisible by n and adjust the value if necessary.
8714 See below for the list of accepted constants for use in the dimension
8718 Set the interlacing mode. It accepts the following values:
8722 Force interlaced aware scaling.
8725 Do not apply interlaced scaling.
8728 Select interlaced aware scaling depending on whether the source frames
8729 are flagged as interlaced or not.
8732 Default value is @samp{0}.
8735 Set libswscale scaling flags. See
8736 @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
8737 complete list of values. If not explicitly specified the filter applies
8741 Set the video size. For the syntax of this option, check the
8742 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
8744 @item in_color_matrix
8745 @item out_color_matrix
8746 Set in/output YCbCr color space type.
8748 This allows the autodetected value to be overridden as well as allows forcing
8749 a specific value used for the output and encoder.
8751 If not specified, the color space type depends on the pixel format.
8757 Choose automatically.
8760 Format conforming to International Telecommunication Union (ITU)
8761 Recommendation BT.709.
8764 Set color space conforming to the United States Federal Communications
8765 Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
8768 Set color space conforming to:
8772 ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
8775 ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
8778 Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
8783 Set color space conforming to SMPTE ST 240:1999.
8788 Set in/output YCbCr sample range.
8790 This allows the autodetected value to be overridden as well as allows forcing
8791 a specific value used for the output and encoder. If not specified, the
8792 range depends on the pixel format. Possible values:
8796 Choose automatically.
8799 Set full range (0-255 in case of 8-bit luma).
8802 Set "MPEG" range (16-235 in case of 8-bit luma).
8805 @item force_original_aspect_ratio
8806 Enable decreasing or increasing output video width or height if necessary to
8807 keep the original aspect ratio. Possible values:
8811 Scale the video as specified and disable this feature.
8814 The output video dimensions will automatically be decreased if needed.
8817 The output video dimensions will automatically be increased if needed.
8821 One useful instance of this option is that when you know a specific device's
8822 maximum allowed resolution, you can use this to limit the output video to
8823 that, while retaining the aspect ratio. For example, device A allows
8824 1280x720 playback, and your video is 1920x800. Using this option (set it to
8825 decrease) and specifying 1280x720 to the command line makes the output
8828 Please note that this is a different thing than specifying -1 for @option{w}
8829 or @option{h}, you still need to specify the output resolution for this option
8834 The values of the @option{w} and @option{h} options are expressions
8835 containing the following constants:
8840 The input width and height
8844 These are the same as @var{in_w} and @var{in_h}.
8848 The output (scaled) width and height
8852 These are the same as @var{out_w} and @var{out_h}
8855 The same as @var{iw} / @var{ih}
8858 input sample aspect ratio
8861 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
8865 horizontal and vertical input chroma subsample values. For example for the
8866 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8870 horizontal and vertical output chroma subsample values. For example for the
8871 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8874 @subsection Examples
8878 Scale the input video to a size of 200x100
8883 This is equivalent to:
8894 Specify a size abbreviation for the output size:
8899 which can also be written as:
8905 Scale the input to 2x:
8911 The above is the same as:
8917 Scale the input to 2x with forced interlaced scaling:
8919 scale=2*iw:2*ih:interl=1
8923 Scale the input to half size:
8929 Increase the width, and set the height to the same size:
8942 Increase the height, and set the width to 3/2 of the height:
8944 scale=w=3/2*oh:h=3/5*ih
8948 Increase the size, making the size a multiple of the chroma
8951 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
8955 Increase the width to a maximum of 500 pixels,
8956 keeping the same aspect ratio as the input:
8958 scale=w='min(500\, iw*3/2):h=-1'
8962 @subsection Commands
8964 This filter supports the following commands:
8968 Set the output video dimension expression.
8969 The command accepts the same syntax of the corresponding option.
8971 If the specified expression is not valid, it is kept at its current
8975 @section separatefields
8977 The @code{separatefields} takes a frame-based video input and splits
8978 each frame into its components fields, producing a new half height clip
8979 with twice the frame rate and twice the frame count.
8981 This filter use field-dominance information in frame to decide which
8982 of each pair of fields to place first in the output.
8983 If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
8985 @section setdar, setsar
8987 The @code{setdar} filter sets the Display Aspect Ratio for the filter
8990 This is done by changing the specified Sample (aka Pixel) Aspect
8991 Ratio, according to the following equation:
8993 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
8996 Keep in mind that the @code{setdar} filter does not modify the pixel
8997 dimensions of the video frame. Also, the display aspect ratio set by
8998 this filter may be changed by later filters in the filterchain,
8999 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
9002 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
9003 the filter output video.
9005 Note that as a consequence of the application of this filter, the
9006 output display aspect ratio will change according to the equation
9009 Keep in mind that the sample aspect ratio set by the @code{setsar}
9010 filter may be changed by later filters in the filterchain, e.g. if
9011 another "setsar" or a "setdar" filter is applied.
9013 It accepts the following parameters:
9016 @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
9017 Set the aspect ratio used by the filter.
9019 The parameter can be a floating point number string, an expression, or
9020 a string of the form @var{num}:@var{den}, where @var{num} and
9021 @var{den} are the numerator and denominator of the aspect ratio. If
9022 the parameter is not specified, it is assumed the value "0".
9023 In case the form "@var{num}:@var{den}" is used, the @code{:} character
9027 Set the maximum integer value to use for expressing numerator and
9028 denominator when reducing the expressed aspect ratio to a rational.
9029 Default value is @code{100}.
9033 The parameter @var{sar} is an expression containing
9034 the following constants:
9038 These are approximated values for the mathematical constants e
9039 (Euler's number), pi (Greek pi), and phi (the golden ratio).
9042 The input width and height.
9045 These are the same as @var{w} / @var{h}.
9048 The input sample aspect ratio.
9051 The input display aspect ratio. It is the same as
9052 (@var{w} / @var{h}) * @var{sar}.
9055 Horizontal and vertical chroma subsample values. For example, for the
9056 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9059 @subsection Examples
9064 To change the display aspect ratio to 16:9, specify one of the following:
9072 To change the sample aspect ratio to 10:11, specify:
9078 To set a display aspect ratio of 16:9, and specify a maximum integer value of
9079 1000 in the aspect ratio reduction, use the command:
9081 setdar=ratio=16/9:max=1000
9089 Force field for the output video frame.
9091 The @code{setfield} filter marks the interlace type field for the
9092 output frames. It does not change the input frame, but only sets the
9093 corresponding property, which affects how the frame is treated by
9094 following filters (e.g. @code{fieldorder} or @code{yadif}).
9096 The filter accepts the following options:
9101 Available values are:
9105 Keep the same field property.
9108 Mark the frame as bottom-field-first.
9111 Mark the frame as top-field-first.
9114 Mark the frame as progressive.
9120 Show a line containing various information for each input video frame.
9121 The input video is not modified.
9123 The shown line contains a sequence of key/value pairs of the form
9124 @var{key}:@var{value}.
9126 The following values are shown in the output:
9130 The (sequential) number of the input frame, starting from 0.
9133 The Presentation TimeStamp of the input frame, expressed as a number of
9134 time base units. The time base unit depends on the filter input pad.
9137 The Presentation TimeStamp of the input frame, expressed as a number of
9141 The position of the frame in the input stream, or -1 if this information is
9142 unavailable and/or meaningless (for example in case of synthetic video).
9145 The pixel format name.
9148 The sample aspect ratio of the input frame, expressed in the form
9149 @var{num}/@var{den}.
9152 The size of the input frame. For the syntax of this option, check the
9153 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
9156 The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
9157 for bottom field first).
9160 This is 1 if the frame is a key frame, 0 otherwise.
9163 The picture type of the input frame ("I" for an I-frame, "P" for a
9164 P-frame, "B" for a B-frame, or "?" for an unknown type).
9165 Also refer to the documentation of the @code{AVPictureType} enum and of
9166 the @code{av_get_picture_type_char} function defined in
9167 @file{libavutil/avutil.h}.
9170 The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
9172 @item plane_checksum
9173 The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
9174 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
9177 @section showpalette
9179 Displays the 256 colors palette of each frame. This filter is only relevant for
9180 @var{pal8} pixel format frames.
9182 It accepts the following option:
9186 Set the size of the box used to represent one palette color entry. Default is
9187 @code{30} (for a @code{30x30} pixel box).
9190 @section shuffleplanes
9192 Reorder and/or duplicate video planes.
9194 It accepts the following parameters:
9199 The index of the input plane to be used as the first output plane.
9202 The index of the input plane to be used as the second output plane.
9205 The index of the input plane to be used as the third output plane.
9208 The index of the input plane to be used as the fourth output plane.
9212 The first plane has the index 0. The default is to keep the input unchanged.
9214 Swap the second and third planes of the input:
9216 ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
9219 @anchor{signalstats}
9220 @section signalstats
9221 Evaluate various visual metrics that assist in determining issues associated
9222 with the digitization of analog video media.
9224 By default the filter will log these metadata values:
9228 Display the minimal Y value contained within the input frame. Expressed in
9232 Display the Y value at the 10% percentile within the input frame. Expressed in
9236 Display the average Y value within the input frame. Expressed in range of
9240 Display the Y value at the 90% percentile within the input frame. Expressed in
9244 Display the maximum Y value contained within the input frame. Expressed in
9248 Display the minimal U value contained within the input frame. Expressed in
9252 Display the U value at the 10% percentile within the input frame. Expressed in
9256 Display the average U value within the input frame. Expressed in range of
9260 Display the U value at the 90% percentile within the input frame. Expressed in
9264 Display the maximum U value contained within the input frame. Expressed in
9268 Display the minimal V value contained within the input frame. Expressed in
9272 Display the V value at the 10% percentile within the input frame. Expressed in
9276 Display the average V value within the input frame. Expressed in range of
9280 Display the V value at the 90% percentile within the input frame. Expressed in
9284 Display the maximum V value contained within the input frame. Expressed in
9288 Display the minimal saturation value contained within the input frame.
9289 Expressed in range of [0-~181.02].
9292 Display the saturation value at the 10% percentile within the input frame.
9293 Expressed in range of [0-~181.02].
9296 Display the average saturation value within the input frame. Expressed in range
9300 Display the saturation value at the 90% percentile within the input frame.
9301 Expressed in range of [0-~181.02].
9304 Display the maximum saturation value contained within the input frame.
9305 Expressed in range of [0-~181.02].
9308 Display the median value for hue within the input frame. Expressed in range of
9312 Display the average value for hue within the input frame. Expressed in range of
9316 Display the average of sample value difference between all values of the Y
9317 plane in the current frame and corresponding values of the previous input frame.
9318 Expressed in range of [0-255].
9321 Display the average of sample value difference between all values of the U
9322 plane in the current frame and corresponding values of the previous input frame.
9323 Expressed in range of [0-255].
9326 Display the average of sample value difference between all values of the V
9327 plane in the current frame and corresponding values of the previous input frame.
9328 Expressed in range of [0-255].
9331 The filter accepts the following options:
9337 @option{stat} specify an additional form of image analysis.
9338 @option{out} output video with the specified type of pixel highlighted.
9340 Both options accept the following values:
9344 Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
9345 unlike the neighboring pixels of the same field. Examples of temporal outliers
9346 include the results of video dropouts, head clogs, or tape tracking issues.
9349 Identify @var{vertical line repetition}. Vertical line repetition includes
9350 similar rows of pixels within a frame. In born-digital video vertical line
9351 repetition is common, but this pattern is uncommon in video digitized from an
9352 analog source. When it occurs in video that results from the digitization of an
9353 analog source it can indicate concealment from a dropout compensator.
9356 Identify pixels that fall outside of legal broadcast range.
9360 Set the highlight color for the @option{out} option. The default color is
9364 @subsection Examples
9368 Output data of various video metrics:
9370 ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
9374 Output specific data about the minimum and maximum values of the Y plane per frame:
9376 ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
9380 Playback video while highlighting pixels that are outside of broadcast range in red.
9382 ffplay example.mov -vf signalstats="out=brng:color=red"
9386 Playback video with signalstats metadata drawn over the frame.
9388 ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
9391 The contents of signalstat_drawtext.txt used in the command are:
9394 Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
9395 U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
9396 V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
9397 saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
9405 Blur the input video without impacting the outlines.
9407 It accepts the following options:
9410 @item luma_radius, lr
9411 Set the luma radius. The option value must be a float number in
9412 the range [0.1,5.0] that specifies the variance of the gaussian filter
9413 used to blur the image (slower if larger). Default value is 1.0.
9415 @item luma_strength, ls
9416 Set the luma strength. The option value must be a float number
9417 in the range [-1.0,1.0] that configures the blurring. A value included
9418 in [0.0,1.0] will blur the image whereas a value included in
9419 [-1.0,0.0] will sharpen the image. Default value is 1.0.
9421 @item luma_threshold, lt
9422 Set the luma threshold used as a coefficient to determine
9423 whether a pixel should be blurred or not. The option value must be an
9424 integer in the range [-30,30]. A value of 0 will filter all the image,
9425 a value included in [0,30] will filter flat areas and a value included
9426 in [-30,0] will filter edges. Default value is 0.
9428 @item chroma_radius, cr
9429 Set the chroma radius. The option value must be a float number in
9430 the range [0.1,5.0] that specifies the variance of the gaussian filter
9431 used to blur the image (slower if larger). Default value is 1.0.
9433 @item chroma_strength, cs
9434 Set the chroma strength. The option value must be a float number
9435 in the range [-1.0,1.0] that configures the blurring. A value included
9436 in [0.0,1.0] will blur the image whereas a value included in
9437 [-1.0,0.0] will sharpen the image. Default value is 1.0.
9439 @item chroma_threshold, ct
9440 Set the chroma threshold used as a coefficient to determine
9441 whether a pixel should be blurred or not. The option value must be an
9442 integer in the range [-30,30]. A value of 0 will filter all the image,
9443 a value included in [0,30] will filter flat areas and a value included
9444 in [-30,0] will filter edges. Default value is 0.
9447 If a chroma option is not explicitly set, the corresponding luma value
9452 Obtain the SSIM (Structural SImilarity Metric) between two input videos.
9454 This filter takes in input two input videos, the first input is
9455 considered the "main" source and is passed unchanged to the
9456 output. The second input is used as a "reference" video for computing
9459 Both video inputs must have the same resolution and pixel format for
9460 this filter to work correctly. Also it assumes that both inputs
9461 have the same number of frames, which are compared one by one.
9463 The filter stores the calculated SSIM of each frame.
9465 The description of the accepted parameters follows.
9469 If specified the filter will use the named file to save the SSIM of
9470 each individual frame.
9473 The file printed if @var{stats_file} is selected, contains a sequence of
9474 key/value pairs of the form @var{key}:@var{value} for each compared
9477 A description of each shown parameter follows:
9481 sequential number of the input frame, starting from 1
9483 @item Y, U, V, R, G, B
9484 SSIM of the compared frames for the component specified by the suffix.
9487 SSIM of the compared frames for the whole frame.
9490 Same as above but in dB representation.
9495 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
9496 [main][ref] ssim="stats_file=stats.log" [out]
9499 On this example the input file being processed is compared with the
9500 reference file @file{ref_movie.mpg}. The SSIM of each individual frame
9501 is stored in @file{stats.log}.
9503 Another example with both psnr and ssim at same time:
9505 ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
9510 Convert between different stereoscopic image formats.
9512 The filters accept the following options:
9516 Set stereoscopic image format of input.
9518 Available values for input image formats are:
9521 side by side parallel (left eye left, right eye right)
9524 side by side crosseye (right eye left, left eye right)
9527 side by side parallel with half width resolution
9528 (left eye left, right eye right)
9531 side by side crosseye with half width resolution
9532 (right eye left, left eye right)
9535 above-below (left eye above, right eye below)
9538 above-below (right eye above, left eye below)
9541 above-below with half height resolution
9542 (left eye above, right eye below)
9545 above-below with half height resolution
9546 (right eye above, left eye below)
9549 alternating frames (left eye first, right eye second)
9552 alternating frames (right eye first, left eye second)
9554 Default value is @samp{sbsl}.
9558 Set stereoscopic image format of output.
9560 Available values for output image formats are all the input formats as well as:
9563 anaglyph red/blue gray
9564 (red filter on left eye, blue filter on right eye)
9567 anaglyph red/green gray
9568 (red filter on left eye, green filter on right eye)
9571 anaglyph red/cyan gray
9572 (red filter on left eye, cyan filter on right eye)
9575 anaglyph red/cyan half colored
9576 (red filter on left eye, cyan filter on right eye)
9579 anaglyph red/cyan color
9580 (red filter on left eye, cyan filter on right eye)
9583 anaglyph red/cyan color optimized with the least squares projection of dubois
9584 (red filter on left eye, cyan filter on right eye)
9587 anaglyph green/magenta gray
9588 (green filter on left eye, magenta filter on right eye)
9591 anaglyph green/magenta half colored
9592 (green filter on left eye, magenta filter on right eye)
9595 anaglyph green/magenta colored
9596 (green filter on left eye, magenta filter on right eye)
9599 anaglyph green/magenta color optimized with the least squares projection of dubois
9600 (green filter on left eye, magenta filter on right eye)
9603 anaglyph yellow/blue gray
9604 (yellow filter on left eye, blue filter on right eye)
9607 anaglyph yellow/blue half colored
9608 (yellow filter on left eye, blue filter on right eye)
9611 anaglyph yellow/blue colored
9612 (yellow filter on left eye, blue filter on right eye)
9615 anaglyph yellow/blue color optimized with the least squares projection of dubois
9616 (yellow filter on left eye, blue filter on right eye)
9619 interleaved rows (left eye has top row, right eye starts on next row)
9622 interleaved rows (right eye has top row, left eye starts on next row)
9625 mono output (left eye only)
9628 mono output (right eye only)
9631 Default value is @samp{arcd}.
9634 @subsection Examples
9638 Convert input video from side by side parallel to anaglyph yellow/blue dubois:
9644 Convert input video from above bellow (left eye above, right eye below) to side by side crosseye.
9653 Apply a simple postprocessing filter that compresses and decompresses the image
9654 at several (or - in the case of @option{quality} level @code{6} - all) shifts
9655 and average the results.
9657 The filter accepts the following options:
9661 Set quality. This option defines the number of levels for averaging. It accepts
9662 an integer in the range 0-6. If set to @code{0}, the filter will have no
9663 effect. A value of @code{6} means the higher quality. For each increment of
9664 that value the speed drops by a factor of approximately 2. Default value is
9668 Force a constant quantization parameter. If not set, the filter will use the QP
9669 from the video stream (if available).
9672 Set thresholding mode. Available modes are:
9676 Set hard thresholding (default).
9678 Set soft thresholding (better de-ringing effect, but likely blurrier).
9682 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
9683 option may cause flicker since the B-Frames have often larger QP. Default is
9684 @code{0} (not enabled).
9690 Draw subtitles on top of input video using the libass library.
9692 To enable compilation of this filter you need to configure FFmpeg with
9693 @code{--enable-libass}. This filter also requires a build with libavcodec and
9694 libavformat to convert the passed subtitles file to ASS (Advanced Substation
9695 Alpha) subtitles format.
9697 The filter accepts the following options:
9701 Set the filename of the subtitle file to read. It must be specified.
9704 Specify the size of the original video, the video for which the ASS file
9705 was composed. For the syntax of this option, check the
9706 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
9707 Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
9708 correctly scale the fonts if the aspect ratio has been changed.
9711 Set subtitles input character encoding. @code{subtitles} filter only. Only
9712 useful if not UTF-8.
9714 @item stream_index, si
9715 Set subtitles stream index. @code{subtitles} filter only.
9718 Override default style or script info parameters of the subtitles. It accepts a
9719 string containing ASS style format @code{KEY=VALUE} couples separated by ",".
9722 If the first key is not specified, it is assumed that the first value
9723 specifies the @option{filename}.
9725 For example, to render the file @file{sub.srt} on top of the input
9726 video, use the command:
9731 which is equivalent to:
9733 subtitles=filename=sub.srt
9736 To render the default subtitles stream from file @file{video.mkv}, use:
9741 To render the second subtitles stream from that file, use:
9743 subtitles=video.mkv:si=1
9746 To make the subtitles stream from @file{sub.srt} appear in transparent green
9747 @code{DejaVu Serif}, use:
9749 subtitles=sub.srt:force_style='FontName=DejaVu Serif,PrimaryColour=&HAA00FF00'
9754 Scale the input by 2x and smooth using the Super2xSaI (Scale and
9755 Interpolate) pixel art scaling algorithm.
9757 Useful for enlarging pixel art images without reducing sharpness.
9764 Apply telecine process to the video.
9766 This filter accepts the following options:
9775 The default value is @code{top}.
9779 A string of numbers representing the pulldown pattern you wish to apply.
9780 The default value is @code{23}.
9784 Some typical patterns:
9789 24p: 2332 (preferred)
9796 24p: 222222222223 ("Euro pulldown")
9802 Select the most representative frame in a given sequence of consecutive frames.
9804 The filter accepts the following options:
9808 Set the frames batch size to analyze; in a set of @var{n} frames, the filter
9809 will pick one of them, and then handle the next batch of @var{n} frames until
9810 the end. Default is @code{100}.
9813 Since the filter keeps track of the whole frames sequence, a bigger @var{n}
9814 value will result in a higher memory usage, so a high value is not recommended.
9816 @subsection Examples
9820 Extract one picture each 50 frames:
9826 Complete example of a thumbnail creation with @command{ffmpeg}:
9828 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
9834 Tile several successive frames together.
9836 The filter accepts the following options:
9841 Set the grid size (i.e. the number of lines and columns). For the syntax of
9842 this option, check the
9843 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
9846 Set the maximum number of frames to render in the given area. It must be less
9847 than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
9848 the area will be used.
9851 Set the outer border margin in pixels.
9854 Set the inner border thickness (i.e. the number of pixels between frames). For
9855 more advanced padding options (such as having different values for the edges),
9856 refer to the pad video filter.
9859 Specify the color of the unused area. For the syntax of this option, check the
9860 "Color" section in the ffmpeg-utils manual. The default value of @var{color}
9864 @subsection Examples
9868 Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
9870 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
9872 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
9873 duplicating each output frame to accommodate the originally detected frame
9877 Display @code{5} pictures in an area of @code{3x2} frames,
9878 with @code{7} pixels between them, and @code{2} pixels of initial margin, using
9879 mixed flat and named options:
9881 tile=3x2:nb_frames=5:padding=7:margin=2
9887 Perform various types of temporal field interlacing.
9889 Frames are counted starting from 1, so the first input frame is
9892 The filter accepts the following options:
9897 Specify the mode of the interlacing. This option can also be specified
9898 as a value alone. See below for a list of values for this option.
9900 Available values are:
9904 Move odd frames into the upper field, even into the lower field,
9905 generating a double height frame at half frame rate.
9909 Frame 1 Frame 2 Frame 3 Frame 4
9911 11111 22222 33333 44444
9912 11111 22222 33333 44444
9913 11111 22222 33333 44444
9914 11111 22222 33333 44444
9928 Only output even frames, odd frames are dropped, generating a frame with
9929 unchanged height at half frame rate.
9934 Frame 1 Frame 2 Frame 3 Frame 4
9936 11111 22222 33333 44444
9937 11111 22222 33333 44444
9938 11111 22222 33333 44444
9939 11111 22222 33333 44444
9949 Only output odd frames, even frames are dropped, generating a frame with
9950 unchanged height at half frame rate.
9955 Frame 1 Frame 2 Frame 3 Frame 4
9957 11111 22222 33333 44444
9958 11111 22222 33333 44444
9959 11111 22222 33333 44444
9960 11111 22222 33333 44444
9970 Expand each frame to full height, but pad alternate lines with black,
9971 generating a frame with double height at the same input frame rate.
9976 Frame 1 Frame 2 Frame 3 Frame 4
9978 11111 22222 33333 44444
9979 11111 22222 33333 44444
9980 11111 22222 33333 44444
9981 11111 22222 33333 44444
9984 11111 ..... 33333 .....
9985 ..... 22222 ..... 44444
9986 11111 ..... 33333 .....
9987 ..... 22222 ..... 44444
9988 11111 ..... 33333 .....
9989 ..... 22222 ..... 44444
9990 11111 ..... 33333 .....
9991 ..... 22222 ..... 44444
9995 @item interleave_top, 4
9996 Interleave the upper field from odd frames with the lower field from
9997 even frames, generating a frame with unchanged height at half frame rate.
10002 Frame 1 Frame 2 Frame 3 Frame 4
10004 11111<- 22222 33333<- 44444
10005 11111 22222<- 33333 44444<-
10006 11111<- 22222 33333<- 44444
10007 11111 22222<- 33333 44444<-
10017 @item interleave_bottom, 5
10018 Interleave the lower field from odd frames with the upper field from
10019 even frames, generating a frame with unchanged height at half frame rate.
10024 Frame 1 Frame 2 Frame 3 Frame 4
10026 11111 22222<- 33333 44444<-
10027 11111<- 22222 33333<- 44444
10028 11111 22222<- 33333 44444<-
10029 11111<- 22222 33333<- 44444
10039 @item interlacex2, 6
10040 Double frame rate with unchanged height. Frames are inserted each
10041 containing the second temporal field from the previous input frame and
10042 the first temporal field from the next input frame. This mode relies on
10043 the top_field_first flag. Useful for interlaced video displays with no
10044 field synchronisation.
10049 Frame 1 Frame 2 Frame 3 Frame 4
10051 11111 22222 33333 44444
10052 11111 22222 33333 44444
10053 11111 22222 33333 44444
10054 11111 22222 33333 44444
10057 11111 22222 22222 33333 33333 44444 44444
10058 11111 11111 22222 22222 33333 33333 44444
10059 11111 22222 22222 33333 33333 44444 44444
10060 11111 11111 22222 22222 33333 33333 44444
10066 Numeric values are deprecated but are accepted for backward
10067 compatibility reasons.
10069 Default mode is @code{merge}.
10072 Specify flags influencing the filter process.
10074 Available value for @var{flags} is:
10077 @item low_pass_filter, vlfp
10078 Enable vertical low-pass filtering in the filter.
10079 Vertical low-pass filtering is required when creating an interlaced
10080 destination from a progressive source which contains high-frequency
10081 vertical detail. Filtering will reduce interlace 'twitter' and Moire
10084 Vertical low-pass filtering can only be enabled for @option{mode}
10085 @var{interleave_top} and @var{interleave_bottom}.
10092 Transpose rows with columns in the input video and optionally flip it.
10094 It accepts the following parameters:
10099 Specify the transposition direction.
10101 Can assume the following values:
10103 @item 0, 4, cclock_flip
10104 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
10112 Rotate by 90 degrees clockwise, that is:
10120 Rotate by 90 degrees counterclockwise, that is:
10127 @item 3, 7, clock_flip
10128 Rotate by 90 degrees clockwise and vertically flip, that is:
10136 For values between 4-7, the transposition is only done if the input
10137 video geometry is portrait and not landscape. These values are
10138 deprecated, the @code{passthrough} option should be used instead.
10140 Numerical values are deprecated, and should be dropped in favor of
10141 symbolic constants.
10144 Do not apply the transposition if the input geometry matches the one
10145 specified by the specified value. It accepts the following values:
10148 Always apply transposition.
10150 Preserve portrait geometry (when @var{height} >= @var{width}).
10152 Preserve landscape geometry (when @var{width} >= @var{height}).
10155 Default value is @code{none}.
10158 For example to rotate by 90 degrees clockwise and preserve portrait
10161 transpose=dir=1:passthrough=portrait
10164 The command above can also be specified as:
10166 transpose=1:portrait
10170 Trim the input so that the output contains one continuous subpart of the input.
10172 It accepts the following parameters:
10175 Specify the time of the start of the kept section, i.e. the frame with the
10176 timestamp @var{start} will be the first frame in the output.
10179 Specify the time of the first frame that will be dropped, i.e. the frame
10180 immediately preceding the one with the timestamp @var{end} will be the last
10181 frame in the output.
10184 This is the same as @var{start}, except this option sets the start timestamp
10185 in timebase units instead of seconds.
10188 This is the same as @var{end}, except this option sets the end timestamp
10189 in timebase units instead of seconds.
10192 The maximum duration of the output in seconds.
10195 The number of the first frame that should be passed to the output.
10198 The number of the first frame that should be dropped.
10201 @option{start}, @option{end}, and @option{duration} are expressed as time
10202 duration specifications; see
10203 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
10204 for the accepted syntax.
10206 Note that the first two sets of the start/end options and the @option{duration}
10207 option look at the frame timestamp, while the _frame variants simply count the
10208 frames that pass through the filter. Also note that this filter does not modify
10209 the timestamps. If you wish for the output timestamps to start at zero, insert a
10210 setpts filter after the trim filter.
10212 If multiple start or end options are set, this filter tries to be greedy and
10213 keep all the frames that match at least one of the specified constraints. To keep
10214 only the part that matches all the constraints at once, chain multiple trim
10217 The defaults are such that all the input is kept. So it is possible to set e.g.
10218 just the end values to keep everything before the specified time.
10223 Drop everything except the second minute of input:
10225 ffmpeg -i INPUT -vf trim=60:120
10229 Keep only the first second:
10231 ffmpeg -i INPUT -vf trim=duration=1
10240 Sharpen or blur the input video.
10242 It accepts the following parameters:
10245 @item luma_msize_x, lx
10246 Set the luma matrix horizontal size. It must be an odd integer between
10247 3 and 63. The default value is 5.
10249 @item luma_msize_y, ly
10250 Set the luma matrix vertical size. It must be an odd integer between 3
10251 and 63. The default value is 5.
10253 @item luma_amount, la
10254 Set the luma effect strength. It must be a floating point number, reasonable
10255 values lay between -1.5 and 1.5.
10257 Negative values will blur the input video, while positive values will
10258 sharpen it, a value of zero will disable the effect.
10260 Default value is 1.0.
10262 @item chroma_msize_x, cx
10263 Set the chroma matrix horizontal size. It must be an odd integer
10264 between 3 and 63. The default value is 5.
10266 @item chroma_msize_y, cy
10267 Set the chroma matrix vertical size. It must be an odd integer
10268 between 3 and 63. The default value is 5.
10270 @item chroma_amount, ca
10271 Set the chroma effect strength. It must be a floating point number, reasonable
10272 values lay between -1.5 and 1.5.
10274 Negative values will blur the input video, while positive values will
10275 sharpen it, a value of zero will disable the effect.
10277 Default value is 0.0.
10280 If set to 1, specify using OpenCL capabilities, only available if
10281 FFmpeg was configured with @code{--enable-opencl}. Default value is 0.
10285 All parameters are optional and default to the equivalent of the
10286 string '5:5:1.0:5:5:0.0'.
10288 @subsection Examples
10292 Apply strong luma sharpen effect:
10294 unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
10298 Apply a strong blur of both luma and chroma parameters:
10300 unsharp=7:7:-2:7:7:-2
10306 Apply ultra slow/simple postprocessing filter that compresses and decompresses
10307 the image at several (or - in the case of @option{quality} level @code{8} - all)
10308 shifts and average the results.
10310 The way this differs from the behavior of spp is that uspp actually encodes &
10311 decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
10312 DCT similar to MJPEG.
10314 The filter accepts the following options:
10318 Set quality. This option defines the number of levels for averaging. It accepts
10319 an integer in the range 0-8. If set to @code{0}, the filter will have no
10320 effect. A value of @code{8} means the higher quality. For each increment of
10321 that value the speed drops by a factor of approximately 2. Default value is
10325 Force a constant quantization parameter. If not set, the filter will use the QP
10326 from the video stream (if available).
10329 @anchor{vidstabdetect}
10330 @section vidstabdetect
10332 Analyze video stabilization/deshaking. Perform pass 1 of 2, see
10333 @ref{vidstabtransform} for pass 2.
10335 This filter generates a file with relative translation and rotation
10336 transform information about subsequent frames, which is then used by
10337 the @ref{vidstabtransform} filter.
10339 To enable compilation of this filter you need to configure FFmpeg with
10340 @code{--enable-libvidstab}.
10342 This filter accepts the following options:
10346 Set the path to the file used to write the transforms information.
10347 Default value is @file{transforms.trf}.
10350 Set how shaky the video is and how quick the camera is. It accepts an
10351 integer in the range 1-10, a value of 1 means little shakiness, a
10352 value of 10 means strong shakiness. Default value is 5.
10355 Set the accuracy of the detection process. It must be a value in the
10356 range 1-15. A value of 1 means low accuracy, a value of 15 means high
10357 accuracy. Default value is 15.
10360 Set stepsize of the search process. The region around minimum is
10361 scanned with 1 pixel resolution. Default value is 6.
10364 Set minimum contrast. Below this value a local measurement field is
10365 discarded. Must be a floating point value in the range 0-1. Default
10369 Set reference frame number for tripod mode.
10371 If enabled, the motion of the frames is compared to a reference frame
10372 in the filtered stream, identified by the specified number. The idea
10373 is to compensate all movements in a more-or-less static scene and keep
10374 the camera view absolutely still.
10376 If set to 0, it is disabled. The frames are counted starting from 1.
10379 Show fields and transforms in the resulting frames. It accepts an
10380 integer in the range 0-2. Default value is 0, which disables any
10384 @subsection Examples
10388 Use default values:
10394 Analyze strongly shaky movie and put the results in file
10395 @file{mytransforms.trf}:
10397 vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
10401 Visualize the result of internal transformations in the resulting
10404 vidstabdetect=show=1
10408 Analyze a video with medium shakiness using @command{ffmpeg}:
10410 ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
10414 @anchor{vidstabtransform}
10415 @section vidstabtransform
10417 Video stabilization/deshaking: pass 2 of 2,
10418 see @ref{vidstabdetect} for pass 1.
10420 Read a file with transform information for each frame and
10421 apply/compensate them. Together with the @ref{vidstabdetect}
10422 filter this can be used to deshake videos. See also
10423 @url{http://public.hronopik.de/vid.stab}. It is important to also use
10424 the @ref{unsharp} filter, see below.
10426 To enable compilation of this filter you need to configure FFmpeg with
10427 @code{--enable-libvidstab}.
10429 @subsection Options
10433 Set path to the file used to read the transforms. Default value is
10434 @file{transforms.trf}.
10437 Set the number of frames (value*2 + 1) used for lowpass filtering the
10438 camera movements. Default value is 10.
10440 For example a number of 10 means that 21 frames are used (10 in the
10441 past and 10 in the future) to smoothen the motion in the video. A
10442 larger value leads to a smoother video, but limits the acceleration of
10443 the camera (pan/tilt movements). 0 is a special case where a static
10444 camera is simulated.
10447 Set the camera path optimization algorithm.
10449 Accepted values are:
10452 gaussian kernel low-pass filter on camera motion (default)
10454 averaging on transformations
10458 Set maximal number of pixels to translate frames. Default value is -1,
10462 Set maximal angle in radians (degree*PI/180) to rotate frames. Default
10463 value is -1, meaning no limit.
10466 Specify how to deal with borders that may be visible due to movement
10469 Available values are:
10472 keep image information from previous frame (default)
10474 fill the border black
10478 Invert transforms if set to 1. Default value is 0.
10481 Consider transforms as relative to previous frame if set to 1,
10482 absolute if set to 0. Default value is 0.
10485 Set percentage to zoom. A positive value will result in a zoom-in
10486 effect, a negative value in a zoom-out effect. Default value is 0 (no
10490 Set optimal zooming to avoid borders.
10492 Accepted values are:
10497 optimal static zoom value is determined (only very strong movements
10498 will lead to visible borders) (default)
10500 optimal adaptive zoom value is determined (no borders will be
10501 visible), see @option{zoomspeed}
10504 Note that the value given at zoom is added to the one calculated here.
10507 Set percent to zoom maximally each frame (enabled when
10508 @option{optzoom} is set to 2). Range is from 0 to 5, default value is
10512 Specify type of interpolation.
10514 Available values are:
10519 linear only horizontal
10521 linear in both directions (default)
10523 cubic in both directions (slow)
10527 Enable virtual tripod mode if set to 1, which is equivalent to
10528 @code{relative=0:smoothing=0}. Default value is 0.
10530 Use also @code{tripod} option of @ref{vidstabdetect}.
10533 Increase log verbosity if set to 1. Also the detected global motions
10534 are written to the temporary file @file{global_motions.trf}. Default
10538 @subsection Examples
10542 Use @command{ffmpeg} for a typical stabilization with default values:
10544 ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
10547 Note the use of the @ref{unsharp} filter which is always recommended.
10550 Zoom in a bit more and load transform data from a given file:
10552 vidstabtransform=zoom=5:input="mytransforms.trf"
10556 Smoothen the video even more:
10558 vidstabtransform=smoothing=30
10564 Flip the input video vertically.
10566 For example, to vertically flip a video with @command{ffmpeg}:
10568 ffmpeg -i in.avi -vf "vflip" out.avi
10574 Make or reverse a natural vignetting effect.
10576 The filter accepts the following options:
10580 Set lens angle expression as a number of radians.
10582 The value is clipped in the @code{[0,PI/2]} range.
10584 Default value: @code{"PI/5"}
10588 Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
10592 Set forward/backward mode.
10594 Available modes are:
10597 The larger the distance from the central point, the darker the image becomes.
10600 The larger the distance from the central point, the brighter the image becomes.
10601 This can be used to reverse a vignette effect, though there is no automatic
10602 detection to extract the lens @option{angle} and other settings (yet). It can
10603 also be used to create a burning effect.
10606 Default value is @samp{forward}.
10609 Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
10611 It accepts the following values:
10614 Evaluate expressions only once during the filter initialization.
10617 Evaluate expressions for each incoming frame. This is way slower than the
10618 @samp{init} mode since it requires all the scalers to be re-computed, but it
10619 allows advanced dynamic expressions.
10622 Default value is @samp{init}.
10625 Set dithering to reduce the circular banding effects. Default is @code{1}
10629 Set vignette aspect. This setting allows one to adjust the shape of the vignette.
10630 Setting this value to the SAR of the input will make a rectangular vignetting
10631 following the dimensions of the video.
10633 Default is @code{1/1}.
10636 @subsection Expressions
10638 The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
10639 following parameters.
10644 input width and height
10647 the number of input frame, starting from 0
10650 the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
10651 @var{TB} units, NAN if undefined
10654 frame rate of the input video, NAN if the input frame rate is unknown
10657 the PTS (Presentation TimeStamp) of the filtered video frame,
10658 expressed in seconds, NAN if undefined
10661 time base of the input video
10665 @subsection Examples
10669 Apply simple strong vignetting effect:
10675 Make a flickering vignetting:
10677 vignette='PI/4+random(1)*PI/50':eval=frame
10684 Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
10685 Deinterlacing Filter").
10687 Based on the process described by Martin Weston for BBC R&D, and
10688 implemented based on the de-interlace algorithm written by Jim
10689 Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
10690 uses filter coefficients calculated by BBC R&D.
10692 There are two sets of filter coefficients, so called "simple":
10693 and "complex". Which set of filter coefficients is used can
10694 be set by passing an optional parameter:
10698 Set the interlacing filter coefficients. Accepts one of the following values:
10702 Simple filter coefficient set.
10704 More-complex filter coefficient set.
10706 Default value is @samp{complex}.
10709 Specify which frames to deinterlace. Accept one of the following values:
10713 Deinterlace all frames,
10715 Only deinterlace frames marked as interlaced.
10718 Default value is @samp{all}.
10722 Apply the xBR high-quality magnification filter which is designed for pixel
10723 art. It follows a set of edge-detection rules, see
10724 @url{http://www.libretro.com/forums/viewtopic.php?f=6&t=134}.
10726 It accepts the following option:
10730 Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
10731 @code{3xBR} and @code{4} for @code{4xBR}.
10732 Default is @code{3}.
10738 Deinterlace the input video ("yadif" means "yet another deinterlacing
10741 It accepts the following parameters:
10747 The interlacing mode to adopt. It accepts one of the following values:
10750 @item 0, send_frame
10751 Output one frame for each frame.
10752 @item 1, send_field
10753 Output one frame for each field.
10754 @item 2, send_frame_nospatial
10755 Like @code{send_frame}, but it skips the spatial interlacing check.
10756 @item 3, send_field_nospatial
10757 Like @code{send_field}, but it skips the spatial interlacing check.
10760 The default value is @code{send_frame}.
10763 The picture field parity assumed for the input interlaced video. It accepts one
10764 of the following values:
10768 Assume the top field is first.
10770 Assume the bottom field is first.
10772 Enable automatic detection of field parity.
10775 The default value is @code{auto}.
10776 If the interlacing is unknown or the decoder does not export this information,
10777 top field first will be assumed.
10780 Specify which frames to deinterlace. Accept one of the following
10785 Deinterlace all frames.
10786 @item 1, interlaced
10787 Only deinterlace frames marked as interlaced.
10790 The default value is @code{all}.
10795 Apply Zoom & Pan effect.
10797 This filter accepts the following options:
10801 Set the zoom expression. Default is 1.
10805 Set the x and y expression. Default is 0.
10808 Set the duration expression in number of frames.
10809 This sets for how many number of frames effect will last for
10810 single input image.
10813 Set the output image size, default is 'hd720'.
10816 Each expression can contain the following constants:
10835 Output frame count.
10839 Last calculated 'x' and 'y' position from 'x' and 'y' expression
10840 for current input frame.
10844 'x' and 'y' of last output frame of previous input frame or 0 when there was
10845 not yet such frame (first input frame).
10848 Last calculated zoom from 'z' expression for current input frame.
10851 Last calculated zoom of last output frame of previous input frame.
10854 Number of output frames for current input frame. Calculated from 'd' expression
10855 for each input frame.
10858 number of output frames created for previous input frame
10861 Rational number: input width / input height
10864 sample aspect ratio
10867 display aspect ratio
10871 @subsection Examples
10875 Zoom-in up to 1.5 and pan at same time to some spot near center of picture:
10877 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
10881 Zoom-in up to 1.5 and pan always at center of picture:
10883 zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
10887 @c man end VIDEO FILTERS
10889 @chapter Video Sources
10890 @c man begin VIDEO SOURCES
10892 Below is a description of the currently available video sources.
10896 Buffer video frames, and make them available to the filter chain.
10898 This source is mainly intended for a programmatic use, in particular
10899 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
10901 It accepts the following parameters:
10906 Specify the size (width and height) of the buffered video frames. For the
10907 syntax of this option, check the
10908 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
10911 The input video width.
10914 The input video height.
10917 A string representing the pixel format of the buffered video frames.
10918 It may be a number corresponding to a pixel format, or a pixel format
10922 Specify the timebase assumed by the timestamps of the buffered frames.
10925 Specify the frame rate expected for the video stream.
10927 @item pixel_aspect, sar
10928 The sample (pixel) aspect ratio of the input video.
10931 Specify the optional parameters to be used for the scale filter which
10932 is automatically inserted when an input change is detected in the
10933 input size or format.
10938 buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
10941 will instruct the source to accept video frames with size 320x240 and
10942 with format "yuv410p", assuming 1/24 as the timestamps timebase and
10943 square pixels (1:1 sample aspect ratio).
10944 Since the pixel format with name "yuv410p" corresponds to the number 6
10945 (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
10946 this example corresponds to:
10948 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
10951 Alternatively, the options can be specified as a flat string, but this
10952 syntax is deprecated:
10954 @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}]
10958 Create a pattern generated by an elementary cellular automaton.
10960 The initial state of the cellular automaton can be defined through the
10961 @option{filename}, and @option{pattern} options. If such options are
10962 not specified an initial state is created randomly.
10964 At each new frame a new row in the video is filled with the result of
10965 the cellular automaton next generation. The behavior when the whole
10966 frame is filled is defined by the @option{scroll} option.
10968 This source accepts the following options:
10972 Read the initial cellular automaton state, i.e. the starting row, from
10973 the specified file.
10974 In the file, each non-whitespace character is considered an alive
10975 cell, a newline will terminate the row, and further characters in the
10976 file will be ignored.
10979 Read the initial cellular automaton state, i.e. the starting row, from
10980 the specified string.
10982 Each non-whitespace character in the string is considered an alive
10983 cell, a newline will terminate the row, and further characters in the
10984 string will be ignored.
10987 Set the video rate, that is the number of frames generated per second.
10990 @item random_fill_ratio, ratio
10991 Set the random fill ratio for the initial cellular automaton row. It
10992 is a floating point number value ranging from 0 to 1, defaults to
10995 This option is ignored when a file or a pattern is specified.
10997 @item random_seed, seed
10998 Set the seed for filling randomly the initial row, must be an integer
10999 included between 0 and UINT32_MAX. If not specified, or if explicitly
11000 set to -1, the filter will try to use a good random seed on a best
11004 Set the cellular automaton rule, it is a number ranging from 0 to 255.
11005 Default value is 110.
11008 Set the size of the output video. For the syntax of this option, check the
11009 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
11011 If @option{filename} or @option{pattern} is specified, the size is set
11012 by default to the width of the specified initial state row, and the
11013 height is set to @var{width} * PHI.
11015 If @option{size} is set, it must contain the width of the specified
11016 pattern string, and the specified pattern will be centered in the
11019 If a filename or a pattern string is not specified, the size value
11020 defaults to "320x518" (used for a randomly generated initial state).
11023 If set to 1, scroll the output upward when all the rows in the output
11024 have been already filled. If set to 0, the new generated row will be
11025 written over the top row just after the bottom row is filled.
11028 @item start_full, full
11029 If set to 1, completely fill the output with generated rows before
11030 outputting the first frame.
11031 This is the default behavior, for disabling set the value to 0.
11034 If set to 1, stitch the left and right row edges together.
11035 This is the default behavior, for disabling set the value to 0.
11038 @subsection Examples
11042 Read the initial state from @file{pattern}, and specify an output of
11045 cellauto=f=pattern:s=200x400
11049 Generate a random initial row with a width of 200 cells, with a fill
11052 cellauto=ratio=2/3:s=200x200
11056 Create a pattern generated by rule 18 starting by a single alive cell
11057 centered on an initial row with width 100:
11059 cellauto=p=@@:s=100x400:full=0:rule=18
11063 Specify a more elaborated initial pattern:
11065 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
11070 @section mandelbrot
11072 Generate a Mandelbrot set fractal, and progressively zoom towards the
11073 point specified with @var{start_x} and @var{start_y}.
11075 This source accepts the following options:
11080 Set the terminal pts value. Default value is 400.
11083 Set the terminal scale value.
11084 Must be a floating point value. Default value is 0.3.
11087 Set the inner coloring mode, that is the algorithm used to draw the
11088 Mandelbrot fractal internal region.
11090 It shall assume one of the following values:
11095 Show time until convergence.
11097 Set color based on point closest to the origin of the iterations.
11102 Default value is @var{mincol}.
11105 Set the bailout value. Default value is 10.0.
11108 Set the maximum of iterations performed by the rendering
11109 algorithm. Default value is 7189.
11112 Set outer coloring mode.
11113 It shall assume one of following values:
11115 @item iteration_count
11116 Set iteration cound mode.
11117 @item normalized_iteration_count
11118 set normalized iteration count mode.
11120 Default value is @var{normalized_iteration_count}.
11123 Set frame rate, expressed as number of frames per second. Default
11127 Set frame size. For the syntax of this option, check the "Video
11128 size" section in the ffmpeg-utils manual. Default value is "640x480".
11131 Set the initial scale value. Default value is 3.0.
11134 Set the initial x position. Must be a floating point value between
11135 -100 and 100. Default value is -0.743643887037158704752191506114774.
11138 Set the initial y position. Must be a floating point value between
11139 -100 and 100. Default value is -0.131825904205311970493132056385139.
11144 Generate various test patterns, as generated by the MPlayer test filter.
11146 The size of the generated video is fixed, and is 256x256.
11147 This source is useful in particular for testing encoding features.
11149 This source accepts the following options:
11154 Specify the frame rate of the sourced video, as the number of frames
11155 generated per second. It has to be a string in the format
11156 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
11157 number or a valid video frame rate abbreviation. The default value is
11161 Set the duration of the sourced video. See
11162 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
11163 for the accepted syntax.
11165 If not specified, or the expressed duration is negative, the video is
11166 supposed to be generated forever.
11170 Set the number or the name of the test to perform. Supported tests are:
11186 Default value is "all", which will cycle through the list of all tests.
11191 mptestsrc=t=dc_luma
11194 will generate a "dc_luma" test pattern.
11196 @section frei0r_src
11198 Provide a frei0r source.
11200 To enable compilation of this filter you need to install the frei0r
11201 header and configure FFmpeg with @code{--enable-frei0r}.
11203 This source accepts the following parameters:
11208 The size of the video to generate. For the syntax of this option, check the
11209 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
11212 The framerate of the generated video. It may be a string of the form
11213 @var{num}/@var{den} or a frame rate abbreviation.
11216 The name to the frei0r source to load. For more information regarding frei0r and
11217 how to set the parameters, read the @ref{frei0r} section in the video filters
11220 @item filter_params
11221 A '|'-separated list of parameters to pass to the frei0r source.
11225 For example, to generate a frei0r partik0l source with size 200x200
11226 and frame rate 10 which is overlaid on the overlay filter main input:
11228 frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
11233 Generate a life pattern.
11235 This source is based on a generalization of John Conway's life game.
11237 The sourced input represents a life grid, each pixel represents a cell
11238 which can be in one of two possible states, alive or dead. Every cell
11239 interacts with its eight neighbours, which are the cells that are
11240 horizontally, vertically, or diagonally adjacent.
11242 At each interaction the grid evolves according to the adopted rule,
11243 which specifies the number of neighbor alive cells which will make a
11244 cell stay alive or born. The @option{rule} option allows one to specify
11247 This source accepts the following options:
11251 Set the file from which to read the initial grid state. In the file,
11252 each non-whitespace character is considered an alive cell, and newline
11253 is used to delimit the end of each row.
11255 If this option is not specified, the initial grid is generated
11259 Set the video rate, that is the number of frames generated per second.
11262 @item random_fill_ratio, ratio
11263 Set the random fill ratio for the initial random grid. It is a
11264 floating point number value ranging from 0 to 1, defaults to 1/PHI.
11265 It is ignored when a file is specified.
11267 @item random_seed, seed
11268 Set the seed for filling the initial random grid, must be an integer
11269 included between 0 and UINT32_MAX. If not specified, or if explicitly
11270 set to -1, the filter will try to use a good random seed on a best
11276 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
11277 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
11278 @var{NS} specifies the number of alive neighbor cells which make a
11279 live cell stay alive, and @var{NB} the number of alive neighbor cells
11280 which make a dead cell to become alive (i.e. to "born").
11281 "s" and "b" can be used in place of "S" and "B", respectively.
11283 Alternatively a rule can be specified by an 18-bits integer. The 9
11284 high order bits are used to encode the next cell state if it is alive
11285 for each number of neighbor alive cells, the low order bits specify
11286 the rule for "borning" new cells. Higher order bits encode for an
11287 higher number of neighbor cells.
11288 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
11289 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
11291 Default value is "S23/B3", which is the original Conway's game of life
11292 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
11293 cells, and will born a new cell if there are three alive cells around
11297 Set the size of the output video. For the syntax of this option, check the
11298 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
11300 If @option{filename} is specified, the size is set by default to the
11301 same size of the input file. If @option{size} is set, it must contain
11302 the size specified in the input file, and the initial grid defined in
11303 that file is centered in the larger resulting area.
11305 If a filename is not specified, the size value defaults to "320x240"
11306 (used for a randomly generated initial grid).
11309 If set to 1, stitch the left and right grid edges together, and the
11310 top and bottom edges also. Defaults to 1.
11313 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
11314 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
11315 value from 0 to 255.
11318 Set the color of living (or new born) cells.
11321 Set the color of dead cells. If @option{mold} is set, this is the first color
11322 used to represent a dead cell.
11325 Set mold color, for definitely dead and moldy cells.
11327 For the syntax of these 3 color options, check the "Color" section in the
11328 ffmpeg-utils manual.
11331 @subsection Examples
11335 Read a grid from @file{pattern}, and center it on a grid of size
11338 life=f=pattern:s=300x300
11342 Generate a random grid of size 200x200, with a fill ratio of 2/3:
11344 life=ratio=2/3:s=200x200
11348 Specify a custom rule for evolving a randomly generated grid:
11354 Full example with slow death effect (mold) using @command{ffplay}:
11356 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
11361 @anchor{haldclutsrc}
11363 @anchor{rgbtestsrc}
11365 @anchor{smptehdbars}
11367 @section color, haldclutsrc, nullsrc, rgbtestsrc, smptebars, smptehdbars, testsrc
11369 The @code{color} source provides an uniformly colored input.
11371 The @code{haldclutsrc} source provides an identity Hald CLUT. See also
11372 @ref{haldclut} filter.
11374 The @code{nullsrc} source returns unprocessed video frames. It is
11375 mainly useful to be employed in analysis / debugging tools, or as the
11376 source for filters which ignore the input data.
11378 The @code{rgbtestsrc} source generates an RGB test pattern useful for
11379 detecting RGB vs BGR issues. You should see a red, green and blue
11380 stripe from top to bottom.
11382 The @code{smptebars} source generates a color bars pattern, based on
11383 the SMPTE Engineering Guideline EG 1-1990.
11385 The @code{smptehdbars} source generates a color bars pattern, based on
11386 the SMPTE RP 219-2002.
11388 The @code{testsrc} source generates a test video pattern, showing a
11389 color pattern, a scrolling gradient and a timestamp. This is mainly
11390 intended for testing purposes.
11392 The sources accept the following parameters:
11397 Specify the color of the source, only available in the @code{color}
11398 source. For the syntax of this option, check the "Color" section in the
11399 ffmpeg-utils manual.
11402 Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
11403 source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
11404 pixels to be used as identity matrix for 3D lookup tables. Each component is
11405 coded on a @code{1/(N*N)} scale.
11408 Specify the size of the sourced video. For the syntax of this option, check the
11409 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
11410 The default value is @code{320x240}.
11412 This option is not available with the @code{haldclutsrc} filter.
11415 Specify the frame rate of the sourced video, as the number of frames
11416 generated per second. It has to be a string in the format
11417 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
11418 number or a valid video frame rate abbreviation. The default value is
11422 Set the sample aspect ratio of the sourced video.
11425 Set the duration of the sourced video. See
11426 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
11427 for the accepted syntax.
11429 If not specified, or the expressed duration is negative, the video is
11430 supposed to be generated forever.
11433 Set the number of decimals to show in the timestamp, only available in the
11434 @code{testsrc} source.
11436 The displayed timestamp value will correspond to the original
11437 timestamp value multiplied by the power of 10 of the specified
11438 value. Default value is 0.
11441 For example the following:
11443 testsrc=duration=5.3:size=qcif:rate=10
11446 will generate a video with a duration of 5.3 seconds, with size
11447 176x144 and a frame rate of 10 frames per second.
11449 The following graph description will generate a red source
11450 with an opacity of 0.2, with size "qcif" and a frame rate of 10
11453 color=c=red@@0.2:s=qcif:r=10
11456 If the input content is to be ignored, @code{nullsrc} can be used. The
11457 following command generates noise in the luminance plane by employing
11458 the @code{geq} filter:
11460 nullsrc=s=256x256, geq=random(1)*255:128:128
11463 @subsection Commands
11465 The @code{color} source supports the following commands:
11469 Set the color of the created image. Accepts the same syntax of the
11470 corresponding @option{color} option.
11473 @c man end VIDEO SOURCES
11475 @chapter Video Sinks
11476 @c man begin VIDEO SINKS
11478 Below is a description of the currently available video sinks.
11480 @section buffersink
11482 Buffer video frames, and make them available to the end of the filter
11485 This sink is mainly intended for programmatic use, in particular
11486 through the interface defined in @file{libavfilter/buffersink.h}
11487 or the options system.
11489 It accepts a pointer to an AVBufferSinkContext structure, which
11490 defines the incoming buffers' formats, to be passed as the opaque
11491 parameter to @code{avfilter_init_filter} for initialization.
11495 Null video sink: do absolutely nothing with the input video. It is
11496 mainly useful as a template and for use in analysis / debugging
11499 @c man end VIDEO SINKS
11501 @chapter Multimedia Filters
11502 @c man begin MULTIMEDIA FILTERS
11504 Below is a description of the currently available multimedia filters.
11506 @section avectorscope
11508 Convert input audio to a video output, representing the audio vector
11511 The filter is used to measure the difference between channels of stereo
11512 audio stream. A monoaural signal, consisting of identical left and right
11513 signal, results in straight vertical line. Any stereo separation is visible
11514 as a deviation from this line, creating a Lissajous figure.
11515 If the straight (or deviation from it) but horizontal line appears this
11516 indicates that the left and right channels are out of phase.
11518 The filter accepts the following options:
11522 Set the vectorscope mode.
11524 Available values are:
11527 Lissajous rotated by 45 degrees.
11530 Same as above but not rotated.
11533 Default value is @samp{lissajous}.
11536 Set the video size for the output. For the syntax of this option, check the
11537 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
11538 Default value is @code{400x400}.
11541 Set the output frame rate. Default value is @code{25}.
11546 Specify the red, green and blue contrast. Default values are @code{40}, @code{160} and @code{80}.
11547 Allowed range is @code{[0, 255]}.
11552 Specify the red, green and blue fade. Default values are @code{15}, @code{10} and @code{5}.
11553 Allowed range is @code{[0, 255]}.
11556 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[1, 10]}.
11559 @subsection Examples
11563 Complete example using @command{ffplay}:
11565 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
11566 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
11572 Concatenate audio and video streams, joining them together one after the
11575 The filter works on segments of synchronized video and audio streams. All
11576 segments must have the same number of streams of each type, and that will
11577 also be the number of streams at output.
11579 The filter accepts the following options:
11584 Set the number of segments. Default is 2.
11587 Set the number of output video streams, that is also the number of video
11588 streams in each segment. Default is 1.
11591 Set the number of output audio streams, that is also the number of audio
11592 streams in each segment. Default is 0.
11595 Activate unsafe mode: do not fail if segments have a different format.
11599 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
11600 @var{a} audio outputs.
11602 There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
11603 segment, in the same order as the outputs, then the inputs for the second
11606 Related streams do not always have exactly the same duration, for various
11607 reasons including codec frame size or sloppy authoring. For that reason,
11608 related synchronized streams (e.g. a video and its audio track) should be
11609 concatenated at once. The concat filter will use the duration of the longest
11610 stream in each segment (except the last one), and if necessary pad shorter
11611 audio streams with silence.
11613 For this filter to work correctly, all segments must start at timestamp 0.
11615 All corresponding streams must have the same parameters in all segments; the
11616 filtering system will automatically select a common pixel format for video
11617 streams, and a common sample format, sample rate and channel layout for
11618 audio streams, but other settings, such as resolution, must be converted
11619 explicitly by the user.
11621 Different frame rates are acceptable but will result in variable frame rate
11622 at output; be sure to configure the output file to handle it.
11624 @subsection Examples
11628 Concatenate an opening, an episode and an ending, all in bilingual version
11629 (video in stream 0, audio in streams 1 and 2):
11631 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
11632 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
11633 concat=n=3:v=1:a=2 [v] [a1] [a2]' \
11634 -map '[v]' -map '[a1]' -map '[a2]' output.mkv
11638 Concatenate two parts, handling audio and video separately, using the
11639 (a)movie sources, and adjusting the resolution:
11641 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
11642 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
11643 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
11645 Note that a desync will happen at the stitch if the audio and video streams
11646 do not have exactly the same duration in the first file.
11653 EBU R128 scanner filter. This filter takes an audio stream as input and outputs
11654 it unchanged. By default, it logs a message at a frequency of 10Hz with the
11655 Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
11656 Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
11658 The filter also has a video output (see the @var{video} option) with a real
11659 time graph to observe the loudness evolution. The graphic contains the logged
11660 message mentioned above, so it is not printed anymore when this option is set,
11661 unless the verbose logging is set. The main graphing area contains the
11662 short-term loudness (3 seconds of analysis), and the gauge on the right is for
11663 the momentary loudness (400 milliseconds).
11665 More information about the Loudness Recommendation EBU R128 on
11666 @url{http://tech.ebu.ch/loudness}.
11668 The filter accepts the following options:
11673 Activate the video output. The audio stream is passed unchanged whether this
11674 option is set or no. The video stream will be the first output stream if
11675 activated. Default is @code{0}.
11678 Set the video size. This option is for video only. For the syntax of this
11680 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
11681 Default and minimum resolution is @code{640x480}.
11684 Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
11685 @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
11686 other integer value between this range is allowed.
11689 Set metadata injection. If set to @code{1}, the audio input will be segmented
11690 into 100ms output frames, each of them containing various loudness information
11691 in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
11693 Default is @code{0}.
11696 Force the frame logging level.
11698 Available values are:
11701 information logging level
11703 verbose logging level
11706 By default, the logging level is set to @var{info}. If the @option{video} or
11707 the @option{metadata} options are set, it switches to @var{verbose}.
11712 Available modes can be cumulated (the option is a @code{flag} type). Possible
11716 Disable any peak mode (default).
11718 Enable sample-peak mode.
11720 Simple peak mode looking for the higher sample value. It logs a message
11721 for sample-peak (identified by @code{SPK}).
11723 Enable true-peak mode.
11725 If enabled, the peak lookup is done on an over-sampled version of the input
11726 stream for better peak accuracy. It logs a message for true-peak.
11727 (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
11728 This mode requires a build with @code{libswresample}.
11733 @subsection Examples
11737 Real-time graph using @command{ffplay}, with a EBU scale meter +18:
11739 ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
11743 Run an analysis with @command{ffmpeg}:
11745 ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
11749 @section interleave, ainterleave
11751 Temporally interleave frames from several inputs.
11753 @code{interleave} works with video inputs, @code{ainterleave} with audio.
11755 These filters read frames from several inputs and send the oldest
11756 queued frame to the output.
11758 Input streams must have a well defined, monotonically increasing frame
11761 In order to submit one frame to output, these filters need to enqueue
11762 at least one frame for each input, so they cannot work in case one
11763 input is not yet terminated and will not receive incoming frames.
11765 For example consider the case when one input is a @code{select} filter
11766 which always drop input frames. The @code{interleave} filter will keep
11767 reading from that input, but it will never be able to send new frames
11768 to output until the input will send an end-of-stream signal.
11770 Also, depending on inputs synchronization, the filters will drop
11771 frames in case one input receives more frames than the other ones, and
11772 the queue is already filled.
11774 These filters accept the following options:
11778 Set the number of different inputs, it is 2 by default.
11781 @subsection Examples
11785 Interleave frames belonging to different streams using @command{ffmpeg}:
11787 ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
11791 Add flickering blur effect:
11793 select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
11797 @section perms, aperms
11799 Set read/write permissions for the output frames.
11801 These filters are mainly aimed at developers to test direct path in the
11802 following filter in the filtergraph.
11804 The filters accept the following options:
11808 Select the permissions mode.
11810 It accepts the following values:
11813 Do nothing. This is the default.
11815 Set all the output frames read-only.
11817 Set all the output frames directly writable.
11819 Make the frame read-only if writable, and writable if read-only.
11821 Set each output frame read-only or writable randomly.
11825 Set the seed for the @var{random} mode, must be an integer included between
11826 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
11827 @code{-1}, the filter will try to use a good random seed on a best effort
11831 Note: in case of auto-inserted filter between the permission filter and the
11832 following one, the permission might not be received as expected in that
11833 following filter. Inserting a @ref{format} or @ref{aformat} filter before the
11834 perms/aperms filter can avoid this problem.
11836 @section select, aselect
11838 Select frames to pass in output.
11840 This filter accepts the following options:
11845 Set expression, which is evaluated for each input frame.
11847 If the expression is evaluated to zero, the frame is discarded.
11849 If the evaluation result is negative or NaN, the frame is sent to the
11850 first output; otherwise it is sent to the output with index
11851 @code{ceil(val)-1}, assuming that the input index starts from 0.
11853 For example a value of @code{1.2} corresponds to the output with index
11854 @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
11857 Set the number of outputs. The output to which to send the selected
11858 frame is based on the result of the evaluation. Default value is 1.
11861 The expression can contain the following constants:
11865 The (sequential) number of the filtered frame, starting from 0.
11868 The (sequential) number of the selected frame, starting from 0.
11870 @item prev_selected_n
11871 The sequential number of the last selected frame. It's NAN if undefined.
11874 The timebase of the input timestamps.
11877 The PTS (Presentation TimeStamp) of the filtered video frame,
11878 expressed in @var{TB} units. It's NAN if undefined.
11881 The PTS of the filtered video frame,
11882 expressed in seconds. It's NAN if undefined.
11885 The PTS of the previously filtered video frame. It's NAN if undefined.
11887 @item prev_selected_pts
11888 The PTS of the last previously filtered video frame. It's NAN if undefined.
11890 @item prev_selected_t
11891 The PTS of the last previously selected video frame. It's NAN if undefined.
11894 The PTS of the first video frame in the video. It's NAN if undefined.
11897 The time of the first video frame in the video. It's NAN if undefined.
11899 @item pict_type @emph{(video only)}
11900 The type of the filtered frame. It can assume one of the following
11912 @item interlace_type @emph{(video only)}
11913 The frame interlace type. It can assume one of the following values:
11916 The frame is progressive (not interlaced).
11918 The frame is top-field-first.
11920 The frame is bottom-field-first.
11923 @item consumed_sample_n @emph{(audio only)}
11924 the number of selected samples before the current frame
11926 @item samples_n @emph{(audio only)}
11927 the number of samples in the current frame
11929 @item sample_rate @emph{(audio only)}
11930 the input sample rate
11933 This is 1 if the filtered frame is a key-frame, 0 otherwise.
11936 the position in the file of the filtered frame, -1 if the information
11937 is not available (e.g. for synthetic video)
11939 @item scene @emph{(video only)}
11940 value between 0 and 1 to indicate a new scene; a low value reflects a low
11941 probability for the current frame to introduce a new scene, while a higher
11942 value means the current frame is more likely to be one (see the example below)
11946 The default value of the select expression is "1".
11948 @subsection Examples
11952 Select all frames in input:
11957 The example above is the same as:
11969 Select only I-frames:
11971 select='eq(pict_type\,I)'
11975 Select one frame every 100:
11977 select='not(mod(n\,100))'
11981 Select only frames contained in the 10-20 time interval:
11983 select=between(t\,10\,20)
11987 Select only I frames contained in the 10-20 time interval:
11989 select=between(t\,10\,20)*eq(pict_type\,I)
11993 Select frames with a minimum distance of 10 seconds:
11995 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
11999 Use aselect to select only audio frames with samples number > 100:
12001 aselect='gt(samples_n\,100)'
12005 Create a mosaic of the first scenes:
12007 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
12010 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
12014 Send even and odd frames to separate outputs, and compose them:
12016 select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
12020 @section sendcmd, asendcmd
12022 Send commands to filters in the filtergraph.
12024 These filters read commands to be sent to other filters in the
12027 @code{sendcmd} must be inserted between two video filters,
12028 @code{asendcmd} must be inserted between two audio filters, but apart
12029 from that they act the same way.
12031 The specification of commands can be provided in the filter arguments
12032 with the @var{commands} option, or in a file specified by the
12033 @var{filename} option.
12035 These filters accept the following options:
12038 Set the commands to be read and sent to the other filters.
12040 Set the filename of the commands to be read and sent to the other
12044 @subsection Commands syntax
12046 A commands description consists of a sequence of interval
12047 specifications, comprising a list of commands to be executed when a
12048 particular event related to that interval occurs. The occurring event
12049 is typically the current frame time entering or leaving a given time
12052 An interval is specified by the following syntax:
12054 @var{START}[-@var{END}] @var{COMMANDS};
12057 The time interval is specified by the @var{START} and @var{END} times.
12058 @var{END} is optional and defaults to the maximum time.
12060 The current frame time is considered within the specified interval if
12061 it is included in the interval [@var{START}, @var{END}), that is when
12062 the time is greater or equal to @var{START} and is lesser than
12065 @var{COMMANDS} consists of a sequence of one or more command
12066 specifications, separated by ",", relating to that interval. The
12067 syntax of a command specification is given by:
12069 [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
12072 @var{FLAGS} is optional and specifies the type of events relating to
12073 the time interval which enable sending the specified command, and must
12074 be a non-null sequence of identifier flags separated by "+" or "|" and
12075 enclosed between "[" and "]".
12077 The following flags are recognized:
12080 The command is sent when the current frame timestamp enters the
12081 specified interval. In other words, the command is sent when the
12082 previous frame timestamp was not in the given interval, and the
12086 The command is sent when the current frame timestamp leaves the
12087 specified interval. In other words, the command is sent when the
12088 previous frame timestamp was in the given interval, and the
12092 If @var{FLAGS} is not specified, a default value of @code{[enter]} is
12095 @var{TARGET} specifies the target of the command, usually the name of
12096 the filter class or a specific filter instance name.
12098 @var{COMMAND} specifies the name of the command for the target filter.
12100 @var{ARG} is optional and specifies the optional list of argument for
12101 the given @var{COMMAND}.
12103 Between one interval specification and another, whitespaces, or
12104 sequences of characters starting with @code{#} until the end of line,
12105 are ignored and can be used to annotate comments.
12107 A simplified BNF description of the commands specification syntax
12110 @var{COMMAND_FLAG} ::= "enter" | "leave"
12111 @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
12112 @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
12113 @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
12114 @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
12115 @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
12118 @subsection Examples
12122 Specify audio tempo change at second 4:
12124 asendcmd=c='4.0 atempo tempo 1.5',atempo
12128 Specify a list of drawtext and hue commands in a file.
12130 # show text in the interval 5-10
12131 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
12132 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
12134 # desaturate the image in the interval 15-20
12135 15.0-20.0 [enter] hue s 0,
12136 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
12138 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
12140 # apply an exponential saturation fade-out effect, starting from time 25
12141 25 [enter] hue s exp(25-t)
12144 A filtergraph allowing to read and process the above command list
12145 stored in a file @file{test.cmd}, can be specified with:
12147 sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
12152 @section setpts, asetpts
12154 Change the PTS (presentation timestamp) of the input frames.
12156 @code{setpts} works on video frames, @code{asetpts} on audio frames.
12158 This filter accepts the following options:
12163 The expression which is evaluated for each frame to construct its timestamp.
12167 The expression is evaluated through the eval API and can contain the following
12172 frame rate, only defined for constant frame-rate video
12175 The presentation timestamp in input
12178 The count of the input frame for video or the number of consumed samples,
12179 not including the current frame for audio, starting from 0.
12181 @item NB_CONSUMED_SAMPLES
12182 The number of consumed samples, not including the current frame (only
12185 @item NB_SAMPLES, S
12186 The number of samples in the current frame (only audio)
12188 @item SAMPLE_RATE, SR
12189 The audio sample rate.
12192 The PTS of the first frame.
12195 the time in seconds of the first frame
12198 State whether the current frame is interlaced.
12201 the time in seconds of the current frame
12204 original position in the file of the frame, or undefined if undefined
12205 for the current frame
12208 The previous input PTS.
12211 previous input time in seconds
12214 The previous output PTS.
12217 previous output time in seconds
12220 The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
12224 The wallclock (RTC) time at the start of the movie in microseconds.
12227 The timebase of the input timestamps.
12231 @subsection Examples
12235 Start counting PTS from zero
12237 setpts=PTS-STARTPTS
12241 Apply fast motion effect:
12247 Apply slow motion effect:
12253 Set fixed rate of 25 frames per second:
12259 Set fixed rate 25 fps with some jitter:
12261 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
12265 Apply an offset of 10 seconds to the input PTS:
12271 Generate timestamps from a "live source" and rebase onto the current timebase:
12273 setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
12277 Generate timestamps by counting samples:
12284 @section settb, asettb
12286 Set the timebase to use for the output frames timestamps.
12287 It is mainly useful for testing timebase configuration.
12289 It accepts the following parameters:
12294 The expression which is evaluated into the output timebase.
12298 The value for @option{tb} is an arithmetic expression representing a
12299 rational. The expression can contain the constants "AVTB" (the default
12300 timebase), "intb" (the input timebase) and "sr" (the sample rate,
12301 audio only). Default value is "intb".
12303 @subsection Examples
12307 Set the timebase to 1/25:
12313 Set the timebase to 1/10:
12319 Set the timebase to 1001/1000:
12325 Set the timebase to 2*intb:
12331 Set the default timebase value:
12338 Convert input audio to a video output representing
12339 frequency spectrum logarithmically (using constant Q transform with
12340 Brown-Puckette algorithm), with musical tone scale, from E0 to D#10 (10 octaves).
12342 The filter accepts the following options:
12346 Specify transform volume (multiplier) expression. The expression can contain
12349 @item frequency, freq, f
12350 the frequency where transform is evaluated
12351 @item timeclamp, tc
12352 value of timeclamp option
12356 @item a_weighting(f)
12357 A-weighting of equal loudness
12358 @item b_weighting(f)
12359 B-weighting of equal loudness
12360 @item c_weighting(f)
12361 C-weighting of equal loudness
12363 Default value is @code{16}.
12366 Specify transform length expression. The expression can contain variables:
12368 @item frequency, freq, f
12369 the frequency where transform is evaluated
12370 @item timeclamp, tc
12371 value of timeclamp option
12373 Default value is @code{384/f*tc/(384/f+tc)}.
12376 Specify the transform timeclamp. At low frequency, there is trade-off between
12377 accuracy in time domain and frequency domain. If timeclamp is lower,
12378 event in time domain is represented more accurately (such as fast bass drum),
12379 otherwise event in frequency domain is represented more accurately
12380 (such as bass guitar). Acceptable value is [0.1, 1.0]. Default value is @code{0.17}.
12383 Specify the transform coeffclamp. If coeffclamp is lower, transform is
12384 more accurate, otherwise transform is faster. Acceptable value is [0.1, 10.0].
12385 Default value is @code{1.0}.
12388 Specify gamma. Lower gamma makes the spectrum more contrast, higher gamma
12389 makes the spectrum having more range. Acceptable value is [1.0, 7.0].
12390 Default value is @code{3.0}.
12393 Specify gamma of bargraph. Acceptable value is [1.0, 7.0].
12394 Default value is @code{1.0}.
12397 Specify font file for use with freetype. If not specified, use embedded font.
12400 Specify font color expression. This is arithmetic expression that should return
12401 integer value 0xRRGGBB. The expression can contain variables:
12403 @item frequency, freq, f
12404 the frequency where transform is evaluated
12405 @item timeclamp, tc
12406 value of timeclamp option
12411 midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
12412 @item r(x), g(x), b(x)
12413 red, green, and blue value of intensity x
12415 Default value is @code{st(0, (midi(f)-59.5)/12);
12416 st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
12417 r(1-ld(1)) + b(ld(1))}
12420 If set to 1 (the default), the video size is 1920x1080 (full HD),
12421 if set to 0, the video size is 960x540. Use this option to make CPU usage lower.
12424 Specify video fps. Default value is @code{25}.
12427 Specify number of transform per frame, so there are fps*count transforms
12428 per second. Note that audio data rate must be divisible by fps*count.
12429 Default value is @code{6}.
12433 @subsection Examples
12437 Playing audio while showing the spectrum:
12439 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
12443 Same as above, but with frame rate 30 fps:
12445 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
12449 Playing at 960x540 and lower CPU usage:
12451 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fullhd=0:count=3 [out0]'
12455 A1 and its harmonics: A1, A2, (near)E3, A3:
12457 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),
12458 asplit[a][out1]; [a] showcqt [out0]'
12462 Same as above, but with more accuracy in frequency domain (and slower):
12464 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),
12465 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
12469 B-weighting of equal loudness
12471 volume=16*b_weighting(f)
12477 tlength=100/f*tc/(100/f+tc)
12481 Custom fontcolor, C-note is colored green, others are colored blue
12483 fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))'
12487 Custom gamma, now spectrum is linear to the amplitude.
12494 @section showspectrum
12496 Convert input audio to a video output, representing the audio frequency
12499 The filter accepts the following options:
12503 Specify the video size for the output. For the syntax of this option, check the
12504 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
12505 Default value is @code{640x512}.
12508 Specify how the spectrum should slide along the window.
12510 It accepts the following values:
12513 the samples start again on the left when they reach the right
12515 the samples scroll from right to left
12517 frames are only produced when the samples reach the right
12520 Default value is @code{replace}.
12523 Specify display mode.
12525 It accepts the following values:
12528 all channels are displayed in the same row
12530 all channels are displayed in separate rows
12533 Default value is @samp{combined}.
12536 Specify display color mode.
12538 It accepts the following values:
12541 each channel is displayed in a separate color
12543 each channel is is displayed using the same color scheme
12546 Default value is @samp{channel}.
12549 Specify scale used for calculating intensity color values.
12551 It accepts the following values:
12556 square root, default
12563 Default value is @samp{sqrt}.
12566 Set saturation modifier for displayed colors. Negative values provide
12567 alternative color scheme. @code{0} is no saturation at all.
12568 Saturation must be in [-10.0, 10.0] range.
12569 Default value is @code{1}.
12572 Set window function.
12574 It accepts the following values:
12577 No samples pre-processing (do not expect this to be faster)
12586 Default value is @code{hann}.
12589 The usage is very similar to the showwaves filter; see the examples in that
12592 @subsection Examples
12596 Large window with logarithmic color scaling:
12598 showspectrum=s=1280x480:scale=log
12602 Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
12604 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
12605 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
12609 @section showvolume
12611 Convert input audio volume to a video output.
12613 The filter accepts the following options:
12620 Set border width, allowed range is [0, 5]. Default is 1.
12623 Set channel width, allowed range is [40, 1080]. Default is 400.
12626 Set channel height, allowed range is [1, 100]. Default is 20.
12629 Set fade, allowed range is [1, 255]. Default is 20.
12632 Set volume color expression.
12634 The expression can use the following variables:
12638 Current max volume of channel in dB.
12641 Current channel number, starting from 0.
12645 If set, displays channel names. Default is enabled.
12650 Convert input audio to a video output, representing the samples waves.
12652 The filter accepts the following options:
12656 Specify the video size for the output. For the syntax of this option, check the
12657 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
12658 Default value is @code{600x240}.
12663 Available values are:
12666 Draw a point for each sample.
12669 Draw a vertical line for each sample.
12672 Draw a point for each sample and a line between them.
12675 Draw a centered vertical line for each sample.
12678 Default value is @code{point}.
12681 Set the number of samples which are printed on the same column. A
12682 larger value will decrease the frame rate. Must be a positive
12683 integer. This option can be set only if the value for @var{rate}
12684 is not explicitly specified.
12687 Set the (approximate) output frame rate. This is done by setting the
12688 option @var{n}. Default value is "25".
12690 @item split_channels
12691 Set if channels should be drawn separately or overlap. Default value is 0.
12695 @subsection Examples
12699 Output the input file audio and the corresponding video representation
12702 amovie=a.mp3,asplit[out0],showwaves[out1]
12706 Create a synthetic signal and show it with showwaves, forcing a
12707 frame rate of 30 frames per second:
12709 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
12713 @section showwavespic
12715 Convert input audio to a single video frame, representing the samples waves.
12717 The filter accepts the following options:
12721 Specify the video size for the output. For the syntax of this option, check the
12722 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
12723 Default value is @code{600x240}.
12725 @item split_channels
12726 Set if channels should be drawn separately or overlap. Default value is 0.
12729 @subsection Examples
12733 Extract a channel split representation of the wave form of a whole audio track
12734 in a 1024x800 picture using @command{ffmpeg}:
12736 ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
12740 @section split, asplit
12742 Split input into several identical outputs.
12744 @code{asplit} works with audio input, @code{split} with video.
12746 The filter accepts a single parameter which specifies the number of outputs. If
12747 unspecified, it defaults to 2.
12749 @subsection Examples
12753 Create two separate outputs from the same input:
12755 [in] split [out0][out1]
12759 To create 3 or more outputs, you need to specify the number of
12762 [in] asplit=3 [out0][out1][out2]
12766 Create two separate outputs from the same input, one cropped and
12769 [in] split [splitout1][splitout2];
12770 [splitout1] crop=100:100:0:0 [cropout];
12771 [splitout2] pad=200:200:100:100 [padout];
12775 Create 5 copies of the input audio with @command{ffmpeg}:
12777 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
12783 Receive commands sent through a libzmq client, and forward them to
12784 filters in the filtergraph.
12786 @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
12787 must be inserted between two video filters, @code{azmq} between two
12790 To enable these filters you need to install the libzmq library and
12791 headers and configure FFmpeg with @code{--enable-libzmq}.
12793 For more information about libzmq see:
12794 @url{http://www.zeromq.org/}
12796 The @code{zmq} and @code{azmq} filters work as a libzmq server, which
12797 receives messages sent through a network interface defined by the
12798 @option{bind_address} option.
12800 The received message must be in the form:
12802 @var{TARGET} @var{COMMAND} [@var{ARG}]
12805 @var{TARGET} specifies the target of the command, usually the name of
12806 the filter class or a specific filter instance name.
12808 @var{COMMAND} specifies the name of the command for the target filter.
12810 @var{ARG} is optional and specifies the optional argument list for the
12811 given @var{COMMAND}.
12813 Upon reception, the message is processed and the corresponding command
12814 is injected into the filtergraph. Depending on the result, the filter
12815 will send a reply to the client, adopting the format:
12817 @var{ERROR_CODE} @var{ERROR_REASON}
12821 @var{MESSAGE} is optional.
12823 @subsection Examples
12825 Look at @file{tools/zmqsend} for an example of a zmq client which can
12826 be used to send commands processed by these filters.
12828 Consider the following filtergraph generated by @command{ffplay}
12830 ffplay -dumpgraph 1 -f lavfi "
12831 color=s=100x100:c=red [l];
12832 color=s=100x100:c=blue [r];
12833 nullsrc=s=200x100, zmq [bg];
12834 [bg][l] overlay [bg+l];
12835 [bg+l][r] overlay=x=100 "
12838 To change the color of the left side of the video, the following
12839 command can be used:
12841 echo Parsed_color_0 c yellow | tools/zmqsend
12844 To change the right side:
12846 echo Parsed_color_1 c pink | tools/zmqsend
12849 @c man end MULTIMEDIA FILTERS
12851 @chapter Multimedia Sources
12852 @c man begin MULTIMEDIA SOURCES
12854 Below is a description of the currently available multimedia sources.
12858 This is the same as @ref{movie} source, except it selects an audio
12864 Read audio and/or video stream(s) from a movie container.
12866 It accepts the following parameters:
12870 The name of the resource to read (not necessarily a file; it can also be a
12871 device or a stream accessed through some protocol).
12873 @item format_name, f
12874 Specifies the format assumed for the movie to read, and can be either
12875 the name of a container or an input device. If not specified, the
12876 format is guessed from @var{movie_name} or by probing.
12878 @item seek_point, sp
12879 Specifies the seek point in seconds. The frames will be output
12880 starting from this seek point. The parameter is evaluated with
12881 @code{av_strtod}, so the numerical value may be suffixed by an IS
12882 postfix. The default value is "0".
12885 Specifies the streams to read. Several streams can be specified,
12886 separated by "+". The source will then have as many outputs, in the
12887 same order. The syntax is explained in the ``Stream specifiers''
12888 section in the ffmpeg manual. Two special names, "dv" and "da" specify
12889 respectively the default (best suited) video and audio stream. Default
12890 is "dv", or "da" if the filter is called as "amovie".
12892 @item stream_index, si
12893 Specifies the index of the video stream to read. If the value is -1,
12894 the most suitable video stream will be automatically selected. The default
12895 value is "-1". Deprecated. If the filter is called "amovie", it will select
12896 audio instead of video.
12899 Specifies how many times to read the stream in sequence.
12900 If the value is less than 1, the stream will be read again and again.
12901 Default value is "1".
12903 Note that when the movie is looped the source timestamps are not
12904 changed, so it will generate non monotonically increasing timestamps.
12907 It allows overlaying a second video on top of the main input of
12908 a filtergraph, as shown in this graph:
12910 input -----------> deltapts0 --> overlay --> output
12913 movie --> scale--> deltapts1 -------+
12915 @subsection Examples
12919 Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
12920 on top of the input labelled "in":
12922 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
12923 [in] setpts=PTS-STARTPTS [main];
12924 [main][over] overlay=16:16 [out]
12928 Read from a video4linux2 device, and overlay it on top of the input
12931 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
12932 [in] setpts=PTS-STARTPTS [main];
12933 [main][over] overlay=16:16 [out]
12937 Read the first video stream and the audio stream with id 0x81 from
12938 dvd.vob; the video is connected to the pad named "video" and the audio is
12939 connected to the pad named "audio":
12941 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
12945 @c man end MULTIMEDIA SOURCES