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{id}=@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 optionally followed by "@@@var{id}".
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{FILTER_NAME} ::= @var{NAME}["@@"@var{NAME}]
216 @var{LINKLABEL} ::= "[" @var{NAME} "]"
217 @var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
218 @var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted)
219 @var{FILTER} ::= [@var{LINKLABELS}] @var{FILTER_NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]
220 @var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]
221 @var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
224 @anchor{filtergraph escaping}
225 @section Notes on filtergraph escaping
227 Filtergraph description composition entails several levels of
228 escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping"
229 section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more
230 information about the employed escaping procedure.
232 A first level escaping affects the content of each filter option
233 value, which may contain the special character @code{:} used to
234 separate values, or one of the escaping characters @code{\'}.
236 A second level escaping affects the whole filter description, which
237 may contain the escaping characters @code{\'} or the special
238 characters @code{[],;} used by the filtergraph description.
240 Finally, when you specify a filtergraph on a shell commandline, you
241 need to perform a third level escaping for the shell special
242 characters contained within it.
244 For example, consider the following string to be embedded in
245 the @ref{drawtext} filter description @option{text} value:
247 this is a 'string': may contain one, or more, special characters
250 This string contains the @code{'} special escaping character, and the
251 @code{:} special character, so it needs to be escaped in this way:
253 text=this is a \'string\'\: may contain one, or more, special characters
256 A second level of escaping is required when embedding the filter
257 description in a filtergraph description, in order to escape all the
258 filtergraph special characters. Thus the example above becomes:
260 drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
262 (note that in addition to the @code{\'} escaping special characters,
263 also @code{,} needs to be escaped).
265 Finally an additional level of escaping is needed when writing the
266 filtergraph description in a shell command, which depends on the
267 escaping rules of the adopted shell. For example, assuming that
268 @code{\} is special and needs to be escaped with another @code{\}, the
269 previous string will finally result in:
271 -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
274 @chapter Timeline editing
276 Some filters support a generic @option{enable} option. For the filters
277 supporting timeline editing, this option can be set to an expression which is
278 evaluated before sending a frame to the filter. If the evaluation is non-zero,
279 the filter will be enabled, otherwise the frame will be sent unchanged to the
280 next filter in the filtergraph.
282 The expression accepts the following values:
285 timestamp expressed in seconds, NAN if the input timestamp is unknown
288 sequential number of the input frame, starting from 0
291 the position in the file of the input frame, NAN if unknown
295 width and height of the input frame if video
298 Additionally, these filters support an @option{enable} command that can be used
299 to re-define the expression.
301 Like any other filtering option, the @option{enable} option follows the same
304 For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3
305 minutes, and a @ref{curves} filter starting at 3 seconds:
307 smartblur = enable='between(t,10,3*60)',
308 curves = enable='gte(t,3)' : preset=cross_process
311 See @code{ffmpeg -filters} to view which filters have timeline support.
313 @c man end FILTERGRAPH DESCRIPTION
316 @chapter Options for filters with several inputs (framesync)
317 @c man begin OPTIONS FOR FILTERS WITH SEVERAL INPUTS
319 Some filters with several inputs support a common set of options.
320 These options can only be set by name, not with the short notation.
324 The action to take when EOF is encountered on the secondary input; it accepts
325 one of the following values:
329 Repeat the last frame (the default).
333 Pass the main input through.
337 If set to 1, force the output to terminate when the shortest input
338 terminates. Default value is 0.
341 If set to 1, force the filter to extend the last frame of secondary streams
342 until the end of the primary stream. A value of 0 disables this behavior.
346 @c man end OPTIONS FOR FILTERS WITH SEVERAL INPUTS
348 @chapter Audio Filters
349 @c man begin AUDIO FILTERS
351 When you configure your FFmpeg build, you can disable any of the
352 existing filters using @code{--disable-filters}.
353 The configure output will show the audio filters included in your
356 Below is a description of the currently available audio filters.
360 A compressor is mainly used to reduce the dynamic range of a signal.
361 Especially modern music is mostly compressed at a high ratio to
362 improve the overall loudness. It's done to get the highest attention
363 of a listener, "fatten" the sound and bring more "power" to the track.
364 If a signal is compressed too much it may sound dull or "dead"
365 afterwards or it may start to "pump" (which could be a powerful effect
366 but can also destroy a track completely).
367 The right compression is the key to reach a professional sound and is
368 the high art of mixing and mastering. Because of its complex settings
369 it may take a long time to get the right feeling for this kind of effect.
371 Compression is done by detecting the volume above a chosen level
372 @code{threshold} and dividing it by the factor set with @code{ratio}.
373 So if you set the threshold to -12dB and your signal reaches -6dB a ratio
374 of 2:1 will result in a signal at -9dB. Because an exact manipulation of
375 the signal would cause distortion of the waveform the reduction can be
376 levelled over the time. This is done by setting "Attack" and "Release".
377 @code{attack} determines how long the signal has to rise above the threshold
378 before any reduction will occur and @code{release} sets the time the signal
379 has to fall below the threshold to reduce the reduction again. Shorter signals
380 than the chosen attack time will be left untouched.
381 The overall reduction of the signal can be made up afterwards with the
382 @code{makeup} setting. So compressing the peaks of a signal about 6dB and
383 raising the makeup to this level results in a signal twice as loud than the
384 source. To gain a softer entry in the compression the @code{knee} flattens the
385 hard edge at the threshold in the range of the chosen decibels.
387 The filter accepts the following options:
391 Set input gain. Default is 1. Range is between 0.015625 and 64.
394 If a signal of stream rises above this level it will affect the gain
396 By default it is 0.125. Range is between 0.00097563 and 1.
399 Set a ratio by which the signal is reduced. 1:2 means that if the level
400 rose 4dB above the threshold, it will be only 2dB above after the reduction.
401 Default is 2. Range is between 1 and 20.
404 Amount of milliseconds the signal has to rise above the threshold before gain
405 reduction starts. Default is 20. Range is between 0.01 and 2000.
408 Amount of milliseconds the signal has to fall below the threshold before
409 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
412 Set the amount by how much signal will be amplified after processing.
413 Default is 1. Range is from 1 to 64.
416 Curve the sharp knee around the threshold to enter gain reduction more softly.
417 Default is 2.82843. Range is between 1 and 8.
420 Choose if the @code{average} level between all channels of input stream
421 or the louder(@code{maximum}) channel of input stream affects the
422 reduction. Default is @code{average}.
425 Should the exact signal be taken in case of @code{peak} or an RMS one in case
426 of @code{rms}. Default is @code{rms} which is mostly smoother.
429 How much to use compressed signal in output. Default is 1.
430 Range is between 0 and 1.
434 Simple audio dynamic range commpression/expansion filter.
436 The filter accepts the following options:
440 Set contrast. Default is 33. Allowed range is between 0 and 100.
445 Copy the input audio source unchanged to the output. This is mainly useful for
450 Apply cross fade from one input audio stream to another input audio stream.
451 The cross fade is applied for specified duration near the end of first stream.
453 The filter accepts the following options:
457 Specify the number of samples for which the cross fade effect has to last.
458 At the end of the cross fade effect the first input audio will be completely
459 silent. Default is 44100.
462 Specify the duration of the cross fade effect. See
463 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
464 for the accepted syntax.
465 By default the duration is determined by @var{nb_samples}.
466 If set this option is used instead of @var{nb_samples}.
469 Should first stream end overlap with second stream start. Default is enabled.
472 Set curve for cross fade transition for first stream.
475 Set curve for cross fade transition for second stream.
477 For description of available curve types see @ref{afade} filter description.
484 Cross fade from one input to another:
486 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
490 Cross fade from one input to another but without overlapping:
492 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
497 Split audio stream into several bands.
499 This filter splits audio stream into two or more frequency ranges.
500 Summing all streams back will give flat output.
502 The filter accepts the following options:
506 Set split frequencies. Those must be positive and increasing.
509 Set filter order, can be @var{2nd}, @var{4th} or @var{8th}.
510 Default is @var{4th}.
515 Reduce audio bit resolution.
517 This filter is bit crusher with enhanced functionality. A bit crusher
518 is used to audibly reduce number of bits an audio signal is sampled
519 with. This doesn't change the bit depth at all, it just produces the
520 effect. Material reduced in bit depth sounds more harsh and "digital".
521 This filter is able to even round to continuous values instead of discrete
523 Additionally it has a D/C offset which results in different crushing of
524 the lower and the upper half of the signal.
525 An Anti-Aliasing setting is able to produce "softer" crushing sounds.
527 Another feature of this filter is the logarithmic mode.
528 This setting switches from linear distances between bits to logarithmic ones.
529 The result is a much more "natural" sounding crusher which doesn't gate low
530 signals for example. The human ear has a logarithmic perception,
531 so this kind of crushing is much more pleasant.
532 Logarithmic crushing is also able to get anti-aliased.
534 The filter accepts the following options:
550 Can be linear: @code{lin} or logarithmic: @code{log}.
559 Set sample reduction.
562 Enable LFO. By default disabled.
573 Delay audio filtering until a given wallclock timestamp. See the @ref{cue}
577 Remove impulsive noise from input audio.
579 Samples detected as impulsive noise are replaced by interpolated samples using
580 autoregressive modelling.
584 Set window size, in milliseconds. Allowed range is from @code{10} to
585 @code{100}. Default value is @code{55} milliseconds.
586 This sets size of window which will be processed at once.
589 Set window overlap, in percentage of window size. Allowed range is from
590 @code{50} to @code{95}. Default value is @code{75} percent.
591 Setting this to a very high value increases impulsive noise removal but makes
592 whole process much slower.
595 Set autoregression order, in percentage of window size. Allowed range is from
596 @code{0} to @code{25}. Default value is @code{2} percent. This option also
597 controls quality of interpolated samples using neighbour good samples.
600 Set threshold value. Allowed range is from @code{1} to @code{100}.
601 Default value is @code{2}.
602 This controls the strength of impulsive noise which is going to be removed.
603 The lower value, the more samples will be detected as impulsive noise.
606 Set burst fusion, in percentage of window size. Allowed range is @code{0} to
607 @code{10}. Default value is @code{2}.
608 If any two samples deteced as noise are spaced less than this value then any
609 sample inbetween those two samples will be also detected as noise.
614 It accepts the following values:
617 Select overlap-add method. Even not interpolated samples are slightly
618 changed with this method.
621 Select overlap-save method. Not interpolated samples remain unchanged.
624 Default value is @code{a}.
628 Remove clipped samples from input audio.
630 Samples detected as clipped are replaced by interpolated samples using
631 autoregressive modelling.
635 Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}.
636 Default value is @code{55} milliseconds.
637 This sets size of window which will be processed at once.
640 Set window overlap, in percentage of window size. Allowed range is from @code{50}
641 to @code{95}. Default value is @code{75} percent.
644 Set autoregression order, in percentage of window size. Allowed range is from
645 @code{0} to @code{25}. Default value is @code{8} percent. This option also controls
646 quality of interpolated samples using neighbour good samples.
649 Set threshold value. Allowed range is from @code{1} to @code{100}.
650 Default value is @code{10}. Higher values make clip detection less aggressive.
653 Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}.
654 Default value is @code{1000}. Higher values make clip detection less aggressive.
659 It accepts the following values:
662 Select overlap-add method. Even not interpolated samples are slightly changed
666 Select overlap-save method. Not interpolated samples remain unchanged.
669 Default value is @code{a}.
674 Delay one or more audio channels.
676 Samples in delayed channel are filled with silence.
678 The filter accepts the following option:
682 Set list of delays in milliseconds for each channel separated by '|'.
683 Unused delays will be silently ignored. If number of given delays is
684 smaller than number of channels all remaining channels will not be delayed.
685 If you want to delay exact number of samples, append 'S' to number.
692 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
693 the second channel (and any other channels that may be present) unchanged.
699 Delay second channel by 500 samples, the third channel by 700 samples and leave
700 the first channel (and any other channels that may be present) unchanged.
706 @section aderivative, aintegral
708 Compute derivative/integral of audio stream.
710 Applying both filters one after another produces original audio.
714 Apply echoing to the input audio.
716 Echoes are reflected sound and can occur naturally amongst mountains
717 (and sometimes large buildings) when talking or shouting; digital echo
718 effects emulate this behaviour and are often used to help fill out the
719 sound of a single instrument or vocal. The time difference between the
720 original signal and the reflection is the @code{delay}, and the
721 loudness of the reflected signal is the @code{decay}.
722 Multiple echoes can have different delays and decays.
724 A description of the accepted parameters follows.
728 Set input gain of reflected signal. Default is @code{0.6}.
731 Set output gain of reflected signal. Default is @code{0.3}.
734 Set list of time intervals in milliseconds between original signal and reflections
735 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
736 Default is @code{1000}.
739 Set list of loudness of reflected signals separated by '|'.
740 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
741 Default is @code{0.5}.
748 Make it sound as if there are twice as many instruments as are actually playing:
750 aecho=0.8:0.88:60:0.4
754 If delay is very short, then it sound like a (metallic) robot playing music:
760 A longer delay will sound like an open air concert in the mountains:
762 aecho=0.8:0.9:1000:0.3
766 Same as above but with one more mountain:
768 aecho=0.8:0.9:1000|1800:0.3|0.25
773 Audio emphasis filter creates or restores material directly taken from LPs or
774 emphased CDs with different filter curves. E.g. to store music on vinyl the
775 signal has to be altered by a filter first to even out the disadvantages of
776 this recording medium.
777 Once the material is played back the inverse filter has to be applied to
778 restore the distortion of the frequency response.
780 The filter accepts the following options:
790 Set filter mode. For restoring material use @code{reproduction} mode, otherwise
791 use @code{production} mode. Default is @code{reproduction} mode.
794 Set filter type. Selects medium. Can be one of the following:
806 select Compact Disc (CD).
812 select 50µs (FM-KF).
814 select 75µs (FM-KF).
820 Modify an audio signal according to the specified expressions.
822 This filter accepts one or more expressions (one for each channel),
823 which are evaluated and used to modify a corresponding audio signal.
825 It accepts the following parameters:
829 Set the '|'-separated expressions list for each separate channel. If
830 the number of input channels is greater than the number of
831 expressions, the last specified expression is used for the remaining
834 @item channel_layout, c
835 Set output channel layout. If not specified, the channel layout is
836 specified by the number of expressions. If set to @samp{same}, it will
837 use by default the same input channel layout.
840 Each expression in @var{exprs} can contain the following constants and functions:
844 channel number of the current expression
847 number of the evaluated sample, starting from 0
853 time of the evaluated sample expressed in seconds
856 @item nb_out_channels
857 input and output number of channels
860 the value of input channel with number @var{CH}
863 Note: this filter is slow. For faster processing you should use a
872 aeval=val(ch)/2:c=same
876 Invert phase of the second channel:
885 Apply fade-in/out effect to input audio.
887 A description of the accepted parameters follows.
891 Specify the effect type, can be either @code{in} for fade-in, or
892 @code{out} for a fade-out effect. Default is @code{in}.
894 @item start_sample, ss
895 Specify the number of the start sample for starting to apply the fade
896 effect. Default is 0.
899 Specify the number of samples for which the fade effect has to last. At
900 the end of the fade-in effect the output audio will have the same
901 volume as the input audio, at the end of the fade-out transition
902 the output audio will be silence. Default is 44100.
905 Specify the start time of the fade effect. Default is 0.
906 The value must be specified as a time duration; see
907 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
908 for the accepted syntax.
909 If set this option is used instead of @var{start_sample}.
912 Specify the duration of the fade effect. See
913 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
914 for the accepted syntax.
915 At the end of the fade-in effect the output audio will have the same
916 volume as the input audio, at the end of the fade-out transition
917 the output audio will be silence.
918 By default the duration is determined by @var{nb_samples}.
919 If set this option is used instead of @var{nb_samples}.
922 Set curve for fade transition.
924 It accepts the following values:
927 select triangular, linear slope (default)
929 select quarter of sine wave
931 select half of sine wave
933 select exponential sine wave
937 select inverted parabola
951 select inverted quarter of sine wave
953 select inverted half of sine wave
955 select double-exponential seat
957 select double-exponential sigmoid
965 Fade in first 15 seconds of audio:
971 Fade out last 25 seconds of a 900 seconds audio:
973 afade=t=out:st=875:d=25
978 Apply arbitrary expressions to samples in frequency domain.
982 Set frequency domain real expression for each separate channel separated
983 by '|'. Default is "1".
984 If the number of input channels is greater than the number of
985 expressions, the last specified expression is used for the remaining
989 Set frequency domain imaginary expression for each separate channel
990 separated by '|'. If not set, @var{real} option is used.
992 Each expression in @var{real} and @var{imag} can contain the following
1000 current frequency bin number
1003 number of available bins
1006 channel number of the current expression
1018 It accepts the following values:
1034 Default is @code{w4096}
1037 Set window function. Default is @code{hann}.
1040 Set window overlap. If set to 1, the recommended overlap for selected
1041 window function will be picked. Default is @code{0.75}.
1044 @subsection Examples
1048 Leave almost only low frequencies in audio:
1050 afftfilt="1-clip((b/nb)*b,0,1)"
1057 Apply an arbitrary Frequency Impulse Response filter.
1059 This filter is designed for applying long FIR filters,
1060 up to 30 seconds long.
1062 It can be used as component for digital crossover filters,
1063 room equalization, cross talk cancellation, wavefield synthesis,
1064 auralization, ambiophonics and ambisonics.
1066 This filter uses second stream as FIR coefficients.
1067 If second stream holds single channel, it will be used
1068 for all input channels in first stream, otherwise
1069 number of channels in second stream must be same as
1070 number of channels in first stream.
1072 It accepts the following parameters:
1076 Set dry gain. This sets input gain.
1079 Set wet gain. This sets final output gain.
1082 Set Impulse Response filter length. Default is 1, which means whole IR is processed.
1085 Enable applying gain measured from power of IR.
1088 Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds.
1089 Allowed range is 0.1 to 60 seconds.
1092 Show IR frequency reponse, magnitude and phase in additional video stream.
1093 By default it is disabled.
1096 Set for which IR channel to display frequency response. By default is first channel
1097 displayed. This option is used only when @var{response} is enabled.
1100 Set video stream size. This option is used only when @var{response} is enabled.
1103 @subsection Examples
1107 Apply reverb to stream using mono IR file as second input, complete command using ffmpeg:
1109 ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
1116 Set output format constraints for the input audio. The framework will
1117 negotiate the most appropriate format to minimize conversions.
1119 It accepts the following parameters:
1123 A '|'-separated list of requested sample formats.
1126 A '|'-separated list of requested sample rates.
1128 @item channel_layouts
1129 A '|'-separated list of requested channel layouts.
1131 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1132 for the required syntax.
1135 If a parameter is omitted, all values are allowed.
1137 Force the output to either unsigned 8-bit or signed 16-bit stereo
1139 aformat=sample_fmts=u8|s16:channel_layouts=stereo
1144 A gate is mainly used to reduce lower parts of a signal. This kind of signal
1145 processing reduces disturbing noise between useful signals.
1147 Gating is done by detecting the volume below a chosen level @var{threshold}
1148 and dividing it by the factor set with @var{ratio}. The bottom of the noise
1149 floor is set via @var{range}. Because an exact manipulation of the signal
1150 would cause distortion of the waveform the reduction can be levelled over
1151 time. This is done by setting @var{attack} and @var{release}.
1153 @var{attack} determines how long the signal has to fall below the threshold
1154 before any reduction will occur and @var{release} sets the time the signal
1155 has to rise above the threshold to reduce the reduction again.
1156 Shorter signals than the chosen attack time will be left untouched.
1160 Set input level before filtering.
1161 Default is 1. Allowed range is from 0.015625 to 64.
1164 Set the level of gain reduction when the signal is below the threshold.
1165 Default is 0.06125. Allowed range is from 0 to 1.
1168 If a signal rises above this level the gain reduction is released.
1169 Default is 0.125. Allowed range is from 0 to 1.
1172 Set a ratio by which the signal is reduced.
1173 Default is 2. Allowed range is from 1 to 9000.
1176 Amount of milliseconds the signal has to rise above the threshold before gain
1178 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
1181 Amount of milliseconds the signal has to fall below the threshold before the
1182 reduction is increased again. Default is 250 milliseconds.
1183 Allowed range is from 0.01 to 9000.
1186 Set amount of amplification of signal after processing.
1187 Default is 1. Allowed range is from 1 to 64.
1190 Curve the sharp knee around the threshold to enter gain reduction more softly.
1191 Default is 2.828427125. Allowed range is from 1 to 8.
1194 Choose if exact signal should be taken for detection or an RMS like one.
1195 Default is @code{rms}. Can be @code{peak} or @code{rms}.
1198 Choose if the average level between all channels or the louder channel affects
1200 Default is @code{average}. Can be @code{average} or @code{maximum}.
1205 Apply an arbitrary Infinite Impulse Response filter.
1207 It accepts the following parameters:
1211 Set numerator/zeros coefficients.
1214 Set denominator/poles coefficients.
1226 Set coefficients format.
1232 Z-plane zeros/poles, cartesian (default)
1234 Z-plane zeros/poles, polar radians
1236 Z-plane zeros/poles, polar degrees
1240 Set kind of processing.
1241 Can be @code{d} - direct or @code{s} - serial cascading. Defauls is @code{s}.
1244 Set filtering precision.
1248 double-precision floating-point (default)
1250 single-precision floating-point
1258 Show IR frequency reponse, magnitude and phase in additional video stream.
1259 By default it is disabled.
1262 Set for which IR channel to display frequency response. By default is first channel
1263 displayed. This option is used only when @var{response} is enabled.
1266 Set video stream size. This option is used only when @var{response} is enabled.
1269 Coefficients in @code{tf} format are separated by spaces and are in ascending
1272 Coefficients in @code{zp} format are separated by spaces and order of coefficients
1273 doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i}
1276 Different coefficients and gains can be provided for every channel, in such case
1277 use '|' to separate coefficients or gains. Last provided coefficients will be
1278 used for all remaining channels.
1280 @subsection Examples
1284 Apply 2 pole elliptic notch at arround 5000Hz for 48000 Hz sample rate:
1286 aiir=k=1:z=7.957584807809675810E-1 -2.575128568908332300 3.674839853930788710 -2.57512875289799137 7.957586296317130880E-1:p=1 -2.86950072432325953 3.63022088054647218 -2.28075678147272232 6.361362326477423500E-1:f=tf:r=d
1290 Same as above but in @code{zp} format:
1292 aiir=k=0.79575848078096756:z=0.80918701+0.58773007i 0.80918701-0.58773007i 0.80884700+0.58784055i 0.80884700-0.58784055i:p=0.63892345+0.59951235i 0.63892345-0.59951235i 0.79582691+0.44198673i 0.79582691-0.44198673i:f=zp:r=s
1298 The limiter prevents an input signal from rising over a desired threshold.
1299 This limiter uses lookahead technology to prevent your signal from distorting.
1300 It means that there is a small delay after the signal is processed. Keep in mind
1301 that the delay it produces is the attack time you set.
1303 The filter accepts the following options:
1307 Set input gain. Default is 1.
1310 Set output gain. Default is 1.
1313 Don't let signals above this level pass the limiter. Default is 1.
1316 The limiter will reach its attenuation level in this amount of time in
1317 milliseconds. Default is 5 milliseconds.
1320 Come back from limiting to attenuation 1.0 in this amount of milliseconds.
1321 Default is 50 milliseconds.
1324 When gain reduction is always needed ASC takes care of releasing to an
1325 average reduction level rather than reaching a reduction of 0 in the release
1329 Select how much the release time is affected by ASC, 0 means nearly no changes
1330 in release time while 1 produces higher release times.
1333 Auto level output signal. Default is enabled.
1334 This normalizes audio back to 0dB if enabled.
1337 Depending on picked setting it is recommended to upsample input 2x or 4x times
1338 with @ref{aresample} before applying this filter.
1342 Apply a two-pole all-pass filter with central frequency (in Hz)
1343 @var{frequency}, and filter-width @var{width}.
1344 An all-pass filter changes the audio's frequency to phase relationship
1345 without changing its frequency to amplitude relationship.
1347 The filter accepts the following options:
1351 Set frequency in Hz.
1354 Set method to specify band-width of filter.
1369 Specify the band-width of a filter in width_type units.
1372 Specify which channels to filter, by default all available are filtered.
1375 @subsection Commands
1377 This filter supports the following commands:
1380 Change allpass frequency.
1381 Syntax for the command is : "@var{frequency}"
1384 Change allpass width_type.
1385 Syntax for the command is : "@var{width_type}"
1388 Change allpass width.
1389 Syntax for the command is : "@var{width}"
1396 The filter accepts the following options:
1400 Set the number of loops. Setting this value to -1 will result in infinite loops.
1404 Set maximal number of samples. Default is 0.
1407 Set first sample of loop. Default is 0.
1413 Merge two or more audio streams into a single multi-channel stream.
1415 The filter accepts the following options:
1420 Set the number of inputs. Default is 2.
1424 If the channel layouts of the inputs are disjoint, and therefore compatible,
1425 the channel layout of the output will be set accordingly and the channels
1426 will be reordered as necessary. If the channel layouts of the inputs are not
1427 disjoint, the output will have all the channels of the first input then all
1428 the channels of the second input, in that order, and the channel layout of
1429 the output will be the default value corresponding to the total number of
1432 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
1433 is FC+BL+BR, then the output will be in 5.1, with the channels in the
1434 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
1435 first input, b1 is the first channel of the second input).
1437 On the other hand, if both input are in stereo, the output channels will be
1438 in the default order: a1, a2, b1, b2, and the channel layout will be
1439 arbitrarily set to 4.0, which may or may not be the expected value.
1441 All inputs must have the same sample rate, and format.
1443 If inputs do not have the same duration, the output will stop with the
1446 @subsection Examples
1450 Merge two mono files into a stereo stream:
1452 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
1456 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
1458 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
1464 Mixes multiple audio inputs into a single output.
1466 Note that this filter only supports float samples (the @var{amerge}
1467 and @var{pan} audio filters support many formats). If the @var{amix}
1468 input has integer samples then @ref{aresample} will be automatically
1469 inserted to perform the conversion to float samples.
1473 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
1475 will mix 3 input audio streams to a single output with the same duration as the
1476 first input and a dropout transition time of 3 seconds.
1478 It accepts the following parameters:
1482 The number of inputs. If unspecified, it defaults to 2.
1485 How to determine the end-of-stream.
1489 The duration of the longest input. (default)
1492 The duration of the shortest input.
1495 The duration of the first input.
1499 @item dropout_transition
1500 The transition time, in seconds, for volume renormalization when an input
1501 stream ends. The default value is 2 seconds.
1504 Specify weight of each input audio stream as sequence.
1505 Each weight is separated by space. By default all inputs have same weight.
1510 Multiply first audio stream with second audio stream and store result
1511 in output audio stream. Multiplication is done by multiplying each
1512 sample from first stream with sample at same position from second stream.
1514 With this element-wise multiplication one can create amplitude fades and
1515 amplitude modulations.
1517 @section anequalizer
1519 High-order parametric multiband equalizer for each channel.
1521 It accepts the following parameters:
1525 This option string is in format:
1526 "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
1527 Each equalizer band is separated by '|'.
1531 Set channel number to which equalization will be applied.
1532 If input doesn't have that channel the entry is ignored.
1535 Set central frequency for band.
1536 If input doesn't have that frequency the entry is ignored.
1539 Set band width in hertz.
1542 Set band gain in dB.
1545 Set filter type for band, optional, can be:
1549 Butterworth, this is default.
1560 With this option activated frequency response of anequalizer is displayed
1564 Set video stream size. Only useful if curves option is activated.
1567 Set max gain that will be displayed. Only useful if curves option is activated.
1568 Setting this to a reasonable value makes it possible to display gain which is derived from
1569 neighbour bands which are too close to each other and thus produce higher gain
1570 when both are activated.
1573 Set frequency scale used to draw frequency response in video output.
1574 Can be linear or logarithmic. Default is logarithmic.
1577 Set color for each channel curve which is going to be displayed in video stream.
1578 This is list of color names separated by space or by '|'.
1579 Unrecognised or missing colors will be replaced by white color.
1582 @subsection Examples
1586 Lower gain by 10 of central frequency 200Hz and width 100 Hz
1587 for first 2 channels using Chebyshev type 1 filter:
1589 anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
1593 @subsection Commands
1595 This filter supports the following commands:
1598 Alter existing filter parameters.
1599 Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
1601 @var{fN} is existing filter number, starting from 0, if no such filter is available
1603 @var{freq} set new frequency parameter.
1604 @var{width} set new width parameter in herz.
1605 @var{gain} set new gain parameter in dB.
1607 Full filter invocation with asendcmd may look like this:
1608 asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
1613 Pass the audio source unchanged to the output.
1617 Pad the end of an audio stream with silence.
1619 This can be used together with @command{ffmpeg} @option{-shortest} to
1620 extend audio streams to the same length as the video stream.
1622 A description of the accepted options follows.
1626 Set silence packet size. Default value is 4096.
1629 Set the number of samples of silence to add to the end. After the
1630 value is reached, the stream is terminated. This option is mutually
1631 exclusive with @option{whole_len}.
1634 Set the minimum total number of samples in the output audio stream. If
1635 the value is longer than the input audio length, silence is added to
1636 the end, until the value is reached. This option is mutually exclusive
1637 with @option{pad_len}.
1640 If neither the @option{pad_len} nor the @option{whole_len} option is
1641 set, the filter will add silence to the end of the input stream
1644 @subsection Examples
1648 Add 1024 samples of silence to the end of the input:
1654 Make sure the audio output will contain at least 10000 samples, pad
1655 the input with silence if required:
1657 apad=whole_len=10000
1661 Use @command{ffmpeg} to pad the audio input with silence, so that the
1662 video stream will always result the shortest and will be converted
1663 until the end in the output file when using the @option{shortest}
1666 ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
1671 Add a phasing effect to the input audio.
1673 A phaser filter creates series of peaks and troughs in the frequency spectrum.
1674 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
1676 A description of the accepted parameters follows.
1680 Set input gain. Default is 0.4.
1683 Set output gain. Default is 0.74
1686 Set delay in milliseconds. Default is 3.0.
1689 Set decay. Default is 0.4.
1692 Set modulation speed in Hz. Default is 0.5.
1695 Set modulation type. Default is triangular.
1697 It accepts the following values:
1706 Audio pulsator is something between an autopanner and a tremolo.
1707 But it can produce funny stereo effects as well. Pulsator changes the volume
1708 of the left and right channel based on a LFO (low frequency oscillator) with
1709 different waveforms and shifted phases.
1710 This filter have the ability to define an offset between left and right
1711 channel. An offset of 0 means that both LFO shapes match each other.
1712 The left and right channel are altered equally - a conventional tremolo.
1713 An offset of 50% means that the shape of the right channel is exactly shifted
1714 in phase (or moved backwards about half of the frequency) - pulsator acts as
1715 an autopanner. At 1 both curves match again. Every setting in between moves the
1716 phase shift gapless between all stages and produces some "bypassing" sounds with
1717 sine and triangle waveforms. The more you set the offset near 1 (starting from
1718 the 0.5) the faster the signal passes from the left to the right speaker.
1720 The filter accepts the following options:
1724 Set input gain. By default it is 1. Range is [0.015625 - 64].
1727 Set output gain. By default it is 1. Range is [0.015625 - 64].
1730 Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
1731 sawup or sawdown. Default is sine.
1734 Set modulation. Define how much of original signal is affected by the LFO.
1737 Set left channel offset. Default is 0. Allowed range is [0 - 1].
1740 Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
1743 Set pulse width. Default is 1. Allowed range is [0 - 2].
1746 Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
1749 Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
1753 Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
1757 Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
1758 if timing is set to hz.
1764 Resample the input audio to the specified parameters, using the
1765 libswresample library. If none are specified then the filter will
1766 automatically convert between its input and output.
1768 This filter is also able to stretch/squeeze the audio data to make it match
1769 the timestamps or to inject silence / cut out audio to make it match the
1770 timestamps, do a combination of both or do neither.
1772 The filter accepts the syntax
1773 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
1774 expresses a sample rate and @var{resampler_options} is a list of
1775 @var{key}=@var{value} pairs, separated by ":". See the
1776 @ref{Resampler Options,,"Resampler Options" section in the
1777 ffmpeg-resampler(1) manual,ffmpeg-resampler}
1778 for the complete list of supported options.
1780 @subsection Examples
1784 Resample the input audio to 44100Hz:
1790 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
1791 samples per second compensation:
1793 aresample=async=1000
1799 Reverse an audio clip.
1801 Warning: This filter requires memory to buffer the entire clip, so trimming
1804 @subsection Examples
1808 Take the first 5 seconds of a clip, and reverse it.
1810 atrim=end=5,areverse
1814 @section asetnsamples
1816 Set the number of samples per each output audio frame.
1818 The last output packet may contain a different number of samples, as
1819 the filter will flush all the remaining samples when the input audio
1822 The filter accepts the following options:
1826 @item nb_out_samples, n
1827 Set the number of frames per each output audio frame. The number is
1828 intended as the number of samples @emph{per each channel}.
1829 Default value is 1024.
1832 If set to 1, the filter will pad the last audio frame with zeroes, so
1833 that the last frame will contain the same number of samples as the
1834 previous ones. Default value is 1.
1837 For example, to set the number of per-frame samples to 1234 and
1838 disable padding for the last frame, use:
1840 asetnsamples=n=1234:p=0
1845 Set the sample rate without altering the PCM data.
1846 This will result in a change of speed and pitch.
1848 The filter accepts the following options:
1851 @item sample_rate, r
1852 Set the output sample rate. Default is 44100 Hz.
1857 Show a line containing various information for each input audio frame.
1858 The input audio is not modified.
1860 The shown line contains a sequence of key/value pairs of the form
1861 @var{key}:@var{value}.
1863 The following values are shown in the output:
1867 The (sequential) number of the input frame, starting from 0.
1870 The presentation timestamp of the input frame, in time base units; the time base
1871 depends on the filter input pad, and is usually 1/@var{sample_rate}.
1874 The presentation timestamp of the input frame in seconds.
1877 position of the frame in the input stream, -1 if this information in
1878 unavailable and/or meaningless (for example in case of synthetic audio)
1887 The sample rate for the audio frame.
1890 The number of samples (per channel) in the frame.
1893 The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
1894 audio, the data is treated as if all the planes were concatenated.
1896 @item plane_checksums
1897 A list of Adler-32 checksums for each data plane.
1903 Display time domain statistical information about the audio channels.
1904 Statistics are calculated and displayed for each audio channel and,
1905 where applicable, an overall figure is also given.
1907 It accepts the following option:
1910 Short window length in seconds, used for peak and trough RMS measurement.
1911 Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}.
1915 Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
1916 where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
1919 Available keys for each channel are:
1955 For example full key look like this @code{lavfi.astats.1.DC_offset} or
1956 this @code{lavfi.astats.Overall.Peak_count}.
1958 For description what each key means read below.
1961 Set number of frame after which stats are going to be recalculated.
1962 Default is disabled.
1965 A description of each shown parameter follows:
1969 Mean amplitude displacement from zero.
1972 Minimal sample level.
1975 Maximal sample level.
1977 @item Min difference
1978 Minimal difference between two consecutive samples.
1980 @item Max difference
1981 Maximal difference between two consecutive samples.
1983 @item Mean difference
1984 Mean difference between two consecutive samples.
1985 The average of each difference between two consecutive samples.
1987 @item RMS difference
1988 Root Mean Square difference between two consecutive samples.
1992 Standard peak and RMS level measured in dBFS.
1996 Peak and trough values for RMS level measured over a short window.
1999 Standard ratio of peak to RMS level (note: not in dB).
2002 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
2003 (i.e. either @var{Min level} or @var{Max level}).
2006 Number of occasions (not the number of samples) that the signal attained either
2007 @var{Min level} or @var{Max level}.
2010 Overall bit depth of audio. Number of bits used for each sample.
2013 Measured dynamic range of audio in dB.
2015 @item Zero crossings
2016 Number of points where the waveform crosses the zero level axis.
2018 @item Zero crossings rate
2019 Rate of Zero crossings and number of audio samples.
2026 The filter accepts exactly one parameter, the audio tempo. If not
2027 specified then the filter will assume nominal 1.0 tempo. Tempo must
2028 be in the [0.5, 100.0] range.
2030 Note that tempo greater than 2 will skip some samples rather than
2031 blend them in. If for any reason this is a concern it is always
2032 possible to daisy-chain several instances of atempo to achieve the
2033 desired product tempo.
2035 @subsection Examples
2039 Slow down audio to 80% tempo:
2045 To speed up audio to 300% tempo:
2051 To speed up audio to 300% tempo by daisy-chaining two atempo instances:
2053 atempo=sqrt(3),atempo=sqrt(3)
2059 Trim the input so that the output contains one continuous subpart of the input.
2061 It accepts the following parameters:
2064 Timestamp (in seconds) of the start of the section to keep. I.e. the audio
2065 sample with the timestamp @var{start} will be the first sample in the output.
2068 Specify time of the first audio sample that will be dropped, i.e. the
2069 audio sample immediately preceding the one with the timestamp @var{end} will be
2070 the last sample in the output.
2073 Same as @var{start}, except this option sets the start timestamp in samples
2077 Same as @var{end}, except this option sets the end timestamp in samples instead
2081 The maximum duration of the output in seconds.
2084 The number of the first sample that should be output.
2087 The number of the first sample that should be dropped.
2090 @option{start}, @option{end}, and @option{duration} are expressed as time
2091 duration specifications; see
2092 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
2094 Note that the first two sets of the start/end options and the @option{duration}
2095 option look at the frame timestamp, while the _sample options simply count the
2096 samples that pass through the filter. So start/end_pts and start/end_sample will
2097 give different results when the timestamps are wrong, inexact or do not start at
2098 zero. Also note that this filter does not modify the timestamps. If you wish
2099 to have the output timestamps start at zero, insert the asetpts filter after the
2102 If multiple start or end options are set, this filter tries to be greedy and
2103 keep all samples that match at least one of the specified constraints. To keep
2104 only the part that matches all the constraints at once, chain multiple atrim
2107 The defaults are such that all the input is kept. So it is possible to set e.g.
2108 just the end values to keep everything before the specified time.
2113 Drop everything except the second minute of input:
2115 ffmpeg -i INPUT -af atrim=60:120
2119 Keep only the first 1000 samples:
2121 ffmpeg -i INPUT -af atrim=end_sample=1000
2128 Apply a two-pole Butterworth band-pass filter with central
2129 frequency @var{frequency}, and (3dB-point) band-width width.
2130 The @var{csg} option selects a constant skirt gain (peak gain = Q)
2131 instead of the default: constant 0dB peak gain.
2132 The filter roll off at 6dB per octave (20dB per decade).
2134 The filter accepts the following options:
2138 Set the filter's central frequency. Default is @code{3000}.
2141 Constant skirt gain if set to 1. Defaults to 0.
2144 Set method to specify band-width of filter.
2159 Specify the band-width of a filter in width_type units.
2162 Specify which channels to filter, by default all available are filtered.
2165 @subsection Commands
2167 This filter supports the following commands:
2170 Change bandpass frequency.
2171 Syntax for the command is : "@var{frequency}"
2174 Change bandpass width_type.
2175 Syntax for the command is : "@var{width_type}"
2178 Change bandpass width.
2179 Syntax for the command is : "@var{width}"
2184 Apply a two-pole Butterworth band-reject filter with central
2185 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
2186 The filter roll off at 6dB per octave (20dB per decade).
2188 The filter accepts the following options:
2192 Set the filter's central frequency. Default is @code{3000}.
2195 Set method to specify band-width of filter.
2210 Specify the band-width of a filter in width_type units.
2213 Specify which channels to filter, by default all available are filtered.
2216 @subsection Commands
2218 This filter supports the following commands:
2221 Change bandreject frequency.
2222 Syntax for the command is : "@var{frequency}"
2225 Change bandreject width_type.
2226 Syntax for the command is : "@var{width_type}"
2229 Change bandreject width.
2230 Syntax for the command is : "@var{width}"
2233 @section bass, lowshelf
2235 Boost or cut the bass (lower) frequencies of the audio using a two-pole
2236 shelving filter with a response similar to that of a standard
2237 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
2239 The filter accepts the following options:
2243 Give the gain at 0 Hz. Its useful range is about -20
2244 (for a large cut) to +20 (for a large boost).
2245 Beware of clipping when using a positive gain.
2248 Set the filter's central frequency and so can be used
2249 to extend or reduce the frequency range to be boosted or cut.
2250 The default value is @code{100} Hz.
2253 Set method to specify band-width of filter.
2268 Determine how steep is the filter's shelf transition.
2271 Specify which channels to filter, by default all available are filtered.
2274 @subsection Commands
2276 This filter supports the following commands:
2279 Change bass frequency.
2280 Syntax for the command is : "@var{frequency}"
2283 Change bass width_type.
2284 Syntax for the command is : "@var{width_type}"
2288 Syntax for the command is : "@var{width}"
2292 Syntax for the command is : "@var{gain}"
2297 Apply a biquad IIR filter with the given coefficients.
2298 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
2299 are the numerator and denominator coefficients respectively.
2300 and @var{channels}, @var{c} specify which channels to filter, by default all
2301 available are filtered.
2303 @subsection Commands
2305 This filter supports the following commands:
2313 Change biquad parameter.
2314 Syntax for the command is : "@var{value}"
2318 Bauer stereo to binaural transformation, which improves headphone listening of
2319 stereo audio records.
2321 To enable compilation of this filter you need to configure FFmpeg with
2322 @code{--enable-libbs2b}.
2324 It accepts the following parameters:
2328 Pre-defined crossfeed level.
2332 Default level (fcut=700, feed=50).
2335 Chu Moy circuit (fcut=700, feed=60).
2338 Jan Meier circuit (fcut=650, feed=95).
2343 Cut frequency (in Hz).
2352 Remap input channels to new locations.
2354 It accepts the following parameters:
2357 Map channels from input to output. The argument is a '|'-separated list of
2358 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
2359 @var{in_channel} form. @var{in_channel} can be either the name of the input
2360 channel (e.g. FL for front left) or its index in the input channel layout.
2361 @var{out_channel} is the name of the output channel or its index in the output
2362 channel layout. If @var{out_channel} is not given then it is implicitly an
2363 index, starting with zero and increasing by one for each mapping.
2365 @item channel_layout
2366 The channel layout of the output stream.
2369 If no mapping is present, the filter will implicitly map input channels to
2370 output channels, preserving indices.
2372 @subsection Examples
2376 For example, assuming a 5.1+downmix input MOV file,
2378 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
2380 will create an output WAV file tagged as stereo from the downmix channels of
2384 To fix a 5.1 WAV improperly encoded in AAC's native channel order
2386 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
2390 @section channelsplit
2392 Split each channel from an input audio stream into a separate output stream.
2394 It accepts the following parameters:
2396 @item channel_layout
2397 The channel layout of the input stream. The default is "stereo".
2399 A channel layout describing the channels to be extracted as separate output streams
2400 or "all" to extract each input channel as a separate stream. The default is "all".
2402 Choosing channels not present in channel layout in the input will result in an error.
2405 @subsection Examples
2409 For example, assuming a stereo input MP3 file,
2411 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
2413 will create an output Matroska file with two audio streams, one containing only
2414 the left channel and the other the right channel.
2417 Split a 5.1 WAV file into per-channel files:
2419 ffmpeg -i in.wav -filter_complex
2420 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
2421 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
2422 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
2427 Extract only LFE from a 5.1 WAV file:
2429 ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
2430 -map '[LFE]' lfe.wav
2435 Add a chorus effect to the audio.
2437 Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
2439 Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
2440 constant, with chorus, it is varied using using sinusoidal or triangular modulation.
2441 The modulation depth defines the range the modulated delay is played before or after
2442 the delay. Hence the delayed sound will sound slower or faster, that is the delayed
2443 sound tuned around the original one, like in a chorus where some vocals are slightly
2446 It accepts the following parameters:
2449 Set input gain. Default is 0.4.
2452 Set output gain. Default is 0.4.
2455 Set delays. A typical delay is around 40ms to 60ms.
2467 @subsection Examples
2473 chorus=0.7:0.9:55:0.4:0.25:2
2479 chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
2483 Fuller sounding chorus with three delays:
2485 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
2490 Compress or expand the audio's dynamic range.
2492 It accepts the following parameters:
2498 A list of times in seconds for each channel over which the instantaneous level
2499 of the input signal is averaged to determine its volume. @var{attacks} refers to
2500 increase of volume and @var{decays} refers to decrease of volume. For most
2501 situations, the attack time (response to the audio getting louder) should be
2502 shorter than the decay time, because the human ear is more sensitive to sudden
2503 loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
2504 a typical value for decay is 0.8 seconds.
2505 If specified number of attacks & decays is lower than number of channels, the last
2506 set attack/decay will be used for all remaining channels.
2509 A list of points for the transfer function, specified in dB relative to the
2510 maximum possible signal amplitude. Each key points list must be defined using
2511 the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
2512 @code{x0/y0 x1/y1 x2/y2 ....}
2514 The input values must be in strictly increasing order but the transfer function
2515 does not have to be monotonically rising. The point @code{0/0} is assumed but
2516 may be overridden (by @code{0/out-dBn}). Typical values for the transfer
2517 function are @code{-70/-70|-60/-20|1/0}.
2520 Set the curve radius in dB for all joints. It defaults to 0.01.
2523 Set the additional gain in dB to be applied at all points on the transfer
2524 function. This allows for easy adjustment of the overall gain.
2528 Set an initial volume, in dB, to be assumed for each channel when filtering
2529 starts. This permits the user to supply a nominal level initially, so that, for
2530 example, a very large gain is not applied to initial signal levels before the
2531 companding has begun to operate. A typical value for audio which is initially
2532 quiet is -90 dB. It defaults to 0.
2535 Set a delay, in seconds. The input audio is analyzed immediately, but audio is
2536 delayed before being fed to the volume adjuster. Specifying a delay
2537 approximately equal to the attack/decay times allows the filter to effectively
2538 operate in predictive rather than reactive mode. It defaults to 0.
2542 @subsection Examples
2546 Make music with both quiet and loud passages suitable for listening to in a
2549 compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
2552 Another example for audio with whisper and explosion parts:
2554 compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
2558 A noise gate for when the noise is at a lower level than the signal:
2560 compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
2564 Here is another noise gate, this time for when the noise is at a higher level
2565 than the signal (making it, in some ways, similar to squelch):
2567 compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
2571 2:1 compression starting at -6dB:
2573 compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
2577 2:1 compression starting at -9dB:
2579 compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
2583 2:1 compression starting at -12dB:
2585 compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
2589 2:1 compression starting at -18dB:
2591 compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
2595 3:1 compression starting at -15dB:
2597 compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
2603 compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
2609 compand=attacks=0:points=-80/-169|-54/-80|-49.5/-64.6|-41.1/-41.1|-25.8/-15|-10.8/-4.5|0/0|20/8.3
2613 Hard limiter at -6dB:
2615 compand=attacks=0:points=-80/-80|-6/-6|20/-6
2619 Hard limiter at -12dB:
2621 compand=attacks=0:points=-80/-80|-12/-12|20/-12
2625 Hard noise gate at -35 dB:
2627 compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
2633 compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
2637 @section compensationdelay
2639 Compensation Delay Line is a metric based delay to compensate differing
2640 positions of microphones or speakers.
2642 For example, you have recorded guitar with two microphones placed in
2643 different location. Because the front of sound wave has fixed speed in
2644 normal conditions, the phasing of microphones can vary and depends on
2645 their location and interposition. The best sound mix can be achieved when
2646 these microphones are in phase (synchronized). Note that distance of
2647 ~30 cm between microphones makes one microphone to capture signal in
2648 antiphase to another microphone. That makes the final mix sounding moody.
2649 This filter helps to solve phasing problems by adding different delays
2650 to each microphone track and make them synchronized.
2652 The best result can be reached when you take one track as base and
2653 synchronize other tracks one by one with it.
2654 Remember that synchronization/delay tolerance depends on sample rate, too.
2655 Higher sample rates will give more tolerance.
2657 It accepts the following parameters:
2661 Set millimeters distance. This is compensation distance for fine tuning.
2665 Set cm distance. This is compensation distance for tightening distance setup.
2669 Set meters distance. This is compensation distance for hard distance setup.
2673 Set dry amount. Amount of unprocessed (dry) signal.
2677 Set wet amount. Amount of processed (wet) signal.
2681 Set temperature degree in Celsius. This is the temperature of the environment.
2686 Apply headphone crossfeed filter.
2688 Crossfeed is the process of blending the left and right channels of stereo
2690 It is mainly used to reduce extreme stereo separation of low frequencies.
2692 The intent is to produce more speaker like sound to the listener.
2694 The filter accepts the following options:
2698 Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1.
2699 This sets gain of low shelf filter for side part of stereo image.
2700 Default is -6dB. Max allowed is -30db when strength is set to 1.
2703 Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1.
2704 This sets cut off frequency of low shelf filter. Default is cut off near
2705 1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz.
2708 Set input gain. Default is 0.9.
2711 Set output gain. Default is 1.
2714 @section crystalizer
2715 Simple algorithm to expand audio dynamic range.
2717 The filter accepts the following options:
2721 Sets the intensity of effect (default: 2.0). Must be in range between 0.0
2722 (unchanged sound) to 10.0 (maximum effect).
2725 Enable clipping. By default is enabled.
2729 Apply a DC shift to the audio.
2731 This can be useful to remove a DC offset (caused perhaps by a hardware problem
2732 in the recording chain) from the audio. The effect of a DC offset is reduced
2733 headroom and hence volume. The @ref{astats} filter can be used to determine if
2734 a signal has a DC offset.
2738 Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
2742 Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
2743 used to prevent clipping.
2747 Measure audio dynamic range.
2749 DR values of 14 and higher is found in very dynamic material. DR of 8 to 13
2750 is found in transition material. And anything less that 8 have very poor dynamics
2751 and is very compressed.
2753 The filter accepts the following options:
2757 Set window length in seconds used to split audio into segments of equal length.
2758 Default is 3 seconds.
2762 Dynamic Audio Normalizer.
2764 This filter applies a certain amount of gain to the input audio in order
2765 to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
2766 contrast to more "simple" normalization algorithms, the Dynamic Audio
2767 Normalizer *dynamically* re-adjusts the gain factor to the input audio.
2768 This allows for applying extra gain to the "quiet" sections of the audio
2769 while avoiding distortions or clipping the "loud" sections. In other words:
2770 The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
2771 sections, in the sense that the volume of each section is brought to the
2772 same target level. Note, however, that the Dynamic Audio Normalizer achieves
2773 this goal *without* applying "dynamic range compressing". It will retain 100%
2774 of the dynamic range *within* each section of the audio file.
2778 Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
2779 Default is 500 milliseconds.
2780 The Dynamic Audio Normalizer processes the input audio in small chunks,
2781 referred to as frames. This is required, because a peak magnitude has no
2782 meaning for just a single sample value. Instead, we need to determine the
2783 peak magnitude for a contiguous sequence of sample values. While a "standard"
2784 normalizer would simply use the peak magnitude of the complete file, the
2785 Dynamic Audio Normalizer determines the peak magnitude individually for each
2786 frame. The length of a frame is specified in milliseconds. By default, the
2787 Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
2788 been found to give good results with most files.
2789 Note that the exact frame length, in number of samples, will be determined
2790 automatically, based on the sampling rate of the individual input audio file.
2793 Set the Gaussian filter window size. In range from 3 to 301, must be odd
2794 number. Default is 31.
2795 Probably the most important parameter of the Dynamic Audio Normalizer is the
2796 @code{window size} of the Gaussian smoothing filter. The filter's window size
2797 is specified in frames, centered around the current frame. For the sake of
2798 simplicity, this must be an odd number. Consequently, the default value of 31
2799 takes into account the current frame, as well as the 15 preceding frames and
2800 the 15 subsequent frames. Using a larger window results in a stronger
2801 smoothing effect and thus in less gain variation, i.e. slower gain
2802 adaptation. Conversely, using a smaller window results in a weaker smoothing
2803 effect and thus in more gain variation, i.e. faster gain adaptation.
2804 In other words, the more you increase this value, the more the Dynamic Audio
2805 Normalizer will behave like a "traditional" normalization filter. On the
2806 contrary, the more you decrease this value, the more the Dynamic Audio
2807 Normalizer will behave like a dynamic range compressor.
2810 Set the target peak value. This specifies the highest permissible magnitude
2811 level for the normalized audio input. This filter will try to approach the
2812 target peak magnitude as closely as possible, but at the same time it also
2813 makes sure that the normalized signal will never exceed the peak magnitude.
2814 A frame's maximum local gain factor is imposed directly by the target peak
2815 magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
2816 It is not recommended to go above this value.
2819 Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
2820 The Dynamic Audio Normalizer determines the maximum possible (local) gain
2821 factor for each input frame, i.e. the maximum gain factor that does not
2822 result in clipping or distortion. The maximum gain factor is determined by
2823 the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
2824 additionally bounds the frame's maximum gain factor by a predetermined
2825 (global) maximum gain factor. This is done in order to avoid excessive gain
2826 factors in "silent" or almost silent frames. By default, the maximum gain
2827 factor is 10.0, For most inputs the default value should be sufficient and
2828 it usually is not recommended to increase this value. Though, for input
2829 with an extremely low overall volume level, it may be necessary to allow even
2830 higher gain factors. Note, however, that the Dynamic Audio Normalizer does
2831 not simply apply a "hard" threshold (i.e. cut off values above the threshold).
2832 Instead, a "sigmoid" threshold function will be applied. This way, the
2833 gain factors will smoothly approach the threshold value, but never exceed that
2837 Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
2838 By default, the Dynamic Audio Normalizer performs "peak" normalization.
2839 This means that the maximum local gain factor for each frame is defined
2840 (only) by the frame's highest magnitude sample. This way, the samples can
2841 be amplified as much as possible without exceeding the maximum signal
2842 level, i.e. without clipping. Optionally, however, the Dynamic Audio
2843 Normalizer can also take into account the frame's root mean square,
2844 abbreviated RMS. In electrical engineering, the RMS is commonly used to
2845 determine the power of a time-varying signal. It is therefore considered
2846 that the RMS is a better approximation of the "perceived loudness" than
2847 just looking at the signal's peak magnitude. Consequently, by adjusting all
2848 frames to a constant RMS value, a uniform "perceived loudness" can be
2849 established. If a target RMS value has been specified, a frame's local gain
2850 factor is defined as the factor that would result in exactly that RMS value.
2851 Note, however, that the maximum local gain factor is still restricted by the
2852 frame's highest magnitude sample, in order to prevent clipping.
2855 Enable channels coupling. By default is enabled.
2856 By default, the Dynamic Audio Normalizer will amplify all channels by the same
2857 amount. This means the same gain factor will be applied to all channels, i.e.
2858 the maximum possible gain factor is determined by the "loudest" channel.
2859 However, in some recordings, it may happen that the volume of the different
2860 channels is uneven, e.g. one channel may be "quieter" than the other one(s).
2861 In this case, this option can be used to disable the channel coupling. This way,
2862 the gain factor will be determined independently for each channel, depending
2863 only on the individual channel's highest magnitude sample. This allows for
2864 harmonizing the volume of the different channels.
2867 Enable DC bias correction. By default is disabled.
2868 An audio signal (in the time domain) is a sequence of sample values.
2869 In the Dynamic Audio Normalizer these sample values are represented in the
2870 -1.0 to 1.0 range, regardless of the original input format. Normally, the
2871 audio signal, or "waveform", should be centered around the zero point.
2872 That means if we calculate the mean value of all samples in a file, or in a
2873 single frame, then the result should be 0.0 or at least very close to that
2874 value. If, however, there is a significant deviation of the mean value from
2875 0.0, in either positive or negative direction, this is referred to as a
2876 DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
2877 Audio Normalizer provides optional DC bias correction.
2878 With DC bias correction enabled, the Dynamic Audio Normalizer will determine
2879 the mean value, or "DC correction" offset, of each input frame and subtract
2880 that value from all of the frame's sample values which ensures those samples
2881 are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
2882 boundaries, the DC correction offset values will be interpolated smoothly
2883 between neighbouring frames.
2886 Enable alternative boundary mode. By default is disabled.
2887 The Dynamic Audio Normalizer takes into account a certain neighbourhood
2888 around each frame. This includes the preceding frames as well as the
2889 subsequent frames. However, for the "boundary" frames, located at the very
2890 beginning and at the very end of the audio file, not all neighbouring
2891 frames are available. In particular, for the first few frames in the audio
2892 file, the preceding frames are not known. And, similarly, for the last few
2893 frames in the audio file, the subsequent frames are not known. Thus, the
2894 question arises which gain factors should be assumed for the missing frames
2895 in the "boundary" region. The Dynamic Audio Normalizer implements two modes
2896 to deal with this situation. The default boundary mode assumes a gain factor
2897 of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
2898 "fade out" at the beginning and at the end of the input, respectively.
2901 Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
2902 By default, the Dynamic Audio Normalizer does not apply "traditional"
2903 compression. This means that signal peaks will not be pruned and thus the
2904 full dynamic range will be retained within each local neighbourhood. However,
2905 in some cases it may be desirable to combine the Dynamic Audio Normalizer's
2906 normalization algorithm with a more "traditional" compression.
2907 For this purpose, the Dynamic Audio Normalizer provides an optional compression
2908 (thresholding) function. If (and only if) the compression feature is enabled,
2909 all input frames will be processed by a soft knee thresholding function prior
2910 to the actual normalization process. Put simply, the thresholding function is
2911 going to prune all samples whose magnitude exceeds a certain threshold value.
2912 However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
2913 value. Instead, the threshold value will be adjusted for each individual
2915 In general, smaller parameters result in stronger compression, and vice versa.
2916 Values below 3.0 are not recommended, because audible distortion may appear.
2921 Make audio easier to listen to on headphones.
2923 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
2924 so that when listened to on headphones the stereo image is moved from
2925 inside your head (standard for headphones) to outside and in front of
2926 the listener (standard for speakers).
2932 Apply a two-pole peaking equalisation (EQ) filter. With this
2933 filter, the signal-level at and around a selected frequency can
2934 be increased or decreased, whilst (unlike bandpass and bandreject
2935 filters) that at all other frequencies is unchanged.
2937 In order to produce complex equalisation curves, this filter can
2938 be given several times, each with a different central frequency.
2940 The filter accepts the following options:
2944 Set the filter's central frequency in Hz.
2947 Set method to specify band-width of filter.
2962 Specify the band-width of a filter in width_type units.
2965 Set the required gain or attenuation in dB.
2966 Beware of clipping when using a positive gain.
2969 Specify which channels to filter, by default all available are filtered.
2972 @subsection Examples
2975 Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
2977 equalizer=f=1000:t=h:width=200:g=-10
2981 Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
2983 equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
2987 @subsection Commands
2989 This filter supports the following commands:
2992 Change equalizer frequency.
2993 Syntax for the command is : "@var{frequency}"
2996 Change equalizer width_type.
2997 Syntax for the command is : "@var{width_type}"
3000 Change equalizer width.
3001 Syntax for the command is : "@var{width}"
3004 Change equalizer gain.
3005 Syntax for the command is : "@var{gain}"
3008 @section extrastereo
3010 Linearly increases the difference between left and right channels which
3011 adds some sort of "live" effect to playback.
3013 The filter accepts the following options:
3017 Sets the difference coefficient (default: 2.5). 0.0 means mono sound
3018 (average of both channels), with 1.0 sound will be unchanged, with
3019 -1.0 left and right channels will be swapped.
3022 Enable clipping. By default is enabled.
3025 @section firequalizer
3026 Apply FIR Equalization using arbitrary frequency response.
3028 The filter accepts the following option:
3032 Set gain curve equation (in dB). The expression can contain variables:
3035 the evaluated frequency
3039 channel number, set to 0 when multichannels evaluation is disabled
3041 channel id, see libavutil/channel_layout.h, set to the first channel id when
3042 multichannels evaluation is disabled
3046 channel_layout, see libavutil/channel_layout.h
3051 @item gain_interpolate(f)
3052 interpolate gain on frequency f based on gain_entry
3053 @item cubic_interpolate(f)
3054 same as gain_interpolate, but smoother
3056 This option is also available as command. Default is @code{gain_interpolate(f)}.
3059 Set gain entry for gain_interpolate function. The expression can
3063 store gain entry at frequency f with value g
3065 This option is also available as command.
3068 Set filter delay in seconds. Higher value means more accurate.
3069 Default is @code{0.01}.
3072 Set filter accuracy in Hz. Lower value means more accurate.
3073 Default is @code{5}.
3076 Set window function. Acceptable values are:
3079 rectangular window, useful when gain curve is already smooth
3081 hann window (default)
3087 3-terms continuous 1st derivative nuttall window
3089 minimum 3-terms discontinuous nuttall window
3091 4-terms continuous 1st derivative nuttall window
3093 minimum 4-terms discontinuous nuttall (blackman-nuttall) window
3095 blackman-harris window
3101 If enabled, use fixed number of audio samples. This improves speed when
3102 filtering with large delay. Default is disabled.
3105 Enable multichannels evaluation on gain. Default is disabled.
3108 Enable zero phase mode by subtracting timestamp to compensate delay.
3109 Default is disabled.
3112 Set scale used by gain. Acceptable values are:
3115 linear frequency, linear gain
3117 linear frequency, logarithmic (in dB) gain (default)
3119 logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain
3121 logarithmic frequency, logarithmic gain
3125 Set file for dumping, suitable for gnuplot.
3128 Set scale for dumpfile. Acceptable values are same with scale option.
3132 Enable 2-channel convolution using complex FFT. This improves speed significantly.
3133 Default is disabled.
3136 Enable minimum phase impulse response. Default is disabled.
3139 @subsection Examples
3144 firequalizer=gain='if(lt(f,1000), 0, -INF)'
3147 lowpass at 1000 Hz with gain_entry:
3149 firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
3152 custom equalization:
3154 firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
3157 higher delay with zero phase to compensate delay:
3159 firequalizer=delay=0.1:fixed=on:zero_phase=on
3162 lowpass on left channel, highpass on right channel:
3164 firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
3165 :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
3170 Apply a flanging effect to the audio.
3172 The filter accepts the following options:
3176 Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
3179 Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2.
3182 Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
3186 Set percentage of delayed signal mixed with original. Range from 0 to 100.
3187 Default value is 71.
3190 Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
3193 Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
3194 Default value is @var{sinusoidal}.
3197 Set swept wave percentage-shift for multi channel. Range from 0 to 100.
3198 Default value is 25.
3201 Set delay-line interpolation, @var{linear} or @var{quadratic}.
3202 Default is @var{linear}.
3206 Apply Haas effect to audio.
3208 Note that this makes most sense to apply on mono signals.
3209 With this filter applied to mono signals it give some directionality and
3210 stretches its stereo image.
3212 The filter accepts the following options:
3216 Set input level. By default is @var{1}, or 0dB
3219 Set output level. By default is @var{1}, or 0dB.
3222 Set gain applied to side part of signal. By default is @var{1}.
3225 Set kind of middle source. Can be one of the following:
3235 Pick middle part signal of stereo image.
3238 Pick side part signal of stereo image.
3242 Change middle phase. By default is disabled.
3245 Set left channel delay. By default is @var{2.05} milliseconds.
3248 Set left channel balance. By default is @var{-1}.
3251 Set left channel gain. By default is @var{1}.
3254 Change left phase. By default is disabled.
3257 Set right channel delay. By defaults is @var{2.12} milliseconds.
3260 Set right channel balance. By default is @var{1}.
3263 Set right channel gain. By default is @var{1}.
3266 Change right phase. By default is enabled.
3271 Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
3272 embedded HDCD codes is expanded into a 20-bit PCM stream.
3274 The filter supports the Peak Extend and Low-level Gain Adjustment features
3275 of HDCD, and detects the Transient Filter flag.
3278 ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
3281 When using the filter with wav, note the default encoding for wav is 16-bit,
3282 so the resulting 20-bit stream will be truncated back to 16-bit. Use something
3283 like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
3285 ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
3286 ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
3289 The filter accepts the following options:
3292 @item disable_autoconvert
3293 Disable any automatic format conversion or resampling in the filter graph.
3295 @item process_stereo
3296 Process the stereo channels together. If target_gain does not match between
3297 channels, consider it invalid and use the last valid target_gain.
3300 Set the code detect timer period in ms.
3303 Always extend peaks above -3dBFS even if PE isn't signaled.
3306 Replace audio with a solid tone and adjust the amplitude to signal some
3307 specific aspect of the decoding process. The output file can be loaded in
3308 an audio editor alongside the original to aid analysis.
3310 @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
3317 Gain adjustment level at each sample
3319 Samples where peak extend occurs
3321 Samples where the code detect timer is active
3323 Samples where the target gain does not match between channels
3329 Apply head-related transfer functions (HRTFs) to create virtual
3330 loudspeakers around the user for binaural listening via headphones.
3331 The HRIRs are provided via additional streams, for each channel
3332 one stereo input stream is needed.
3334 The filter accepts the following options:
3338 Set mapping of input streams for convolution.
3339 The argument is a '|'-separated list of channel names in order as they
3340 are given as additional stream inputs for filter.
3341 This also specify number of input streams. Number of input streams
3342 must be not less than number of channels in first stream plus one.
3345 Set gain applied to audio. Value is in dB. Default is 0.
3348 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
3349 processing audio in time domain which is slow.
3350 @var{freq} is processing audio in frequency domain which is fast.
3351 Default is @var{freq}.
3354 Set custom gain for LFE channels. Value is in dB. Default is 0.
3357 Set size of frame in number of samples which will be processed at once.
3358 Default value is @var{1024}. Allowed range is from 1024 to 96000.
3361 Set format of hrir stream.
3362 Default value is @var{stereo}. Alternative value is @var{multich}.
3363 If value is set to @var{stereo}, number of additional streams should
3364 be greater or equal to number of input channels in first input stream.
3365 Also each additional stream should have stereo number of channels.
3366 If value is set to @var{multich}, number of additional streams should
3367 be exactly one. Also number of input channels of additional stream
3368 should be equal or greater than twice number of channels of first input
3372 @subsection Examples
3376 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
3377 each amovie filter use stereo file with IR coefficients as input.
3378 The files give coefficients for each position of virtual loudspeaker:
3380 ffmpeg -i input.wav -lavfi-complex "amovie=azi_270_ele_0_DFC.wav[sr],amovie=azi_90_ele_0_DFC.wav[sl],amovie=azi_225_ele_0_DFC.wav[br],amovie=azi_135_ele_0_DFC.wav[bl],amovie=azi_0_ele_0_DFC.wav,asplit[fc][lfe],amovie=azi_35_ele_0_DFC.wav[fl],amovie=azi_325_ele_0_DFC.wav[fr],[a:0][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR"
3385 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
3386 but now in @var{multich} @var{hrir} format.
3388 ffmpeg -i input.wav -lavfi-complex "amovie=minp.wav[hrirs],[a:0][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich"
3395 Apply a high-pass filter with 3dB point frequency.
3396 The filter can be either single-pole, or double-pole (the default).
3397 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
3399 The filter accepts the following options:
3403 Set frequency in Hz. Default is 3000.
3406 Set number of poles. Default is 2.
3409 Set method to specify band-width of filter.
3424 Specify the band-width of a filter in width_type units.
3425 Applies only to double-pole filter.
3426 The default is 0.707q and gives a Butterworth response.
3429 Specify which channels to filter, by default all available are filtered.
3432 @subsection Commands
3434 This filter supports the following commands:
3437 Change highpass frequency.
3438 Syntax for the command is : "@var{frequency}"
3441 Change highpass width_type.
3442 Syntax for the command is : "@var{width_type}"
3445 Change highpass width.
3446 Syntax for the command is : "@var{width}"
3451 Join multiple input streams into one multi-channel stream.
3453 It accepts the following parameters:
3457 The number of input streams. It defaults to 2.
3459 @item channel_layout
3460 The desired output channel layout. It defaults to stereo.
3463 Map channels from inputs to output. The argument is a '|'-separated list of
3464 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
3465 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
3466 can be either the name of the input channel (e.g. FL for front left) or its
3467 index in the specified input stream. @var{out_channel} is the name of the output
3471 The filter will attempt to guess the mappings when they are not specified
3472 explicitly. It does so by first trying to find an unused matching input channel
3473 and if that fails it picks the first unused input channel.
3475 Join 3 inputs (with properly set channel layouts):
3477 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
3480 Build a 5.1 output from 6 single-channel streams:
3482 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
3483 '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'
3489 Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
3491 To enable compilation of this filter you need to configure FFmpeg with
3492 @code{--enable-ladspa}.
3496 Specifies the name of LADSPA plugin library to load. If the environment
3497 variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
3498 each one of the directories specified by the colon separated list in
3499 @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
3500 this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
3501 @file{/usr/lib/ladspa/}.
3504 Specifies the plugin within the library. Some libraries contain only
3505 one plugin, but others contain many of them. If this is not set filter
3506 will list all available plugins within the specified library.
3509 Set the '|' separated list of controls which are zero or more floating point
3510 values that determine the behavior of the loaded plugin (for example delay,
3512 Controls need to be defined using the following syntax:
3513 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
3514 @var{valuei} is the value set on the @var{i}-th control.
3515 Alternatively they can be also defined using the following syntax:
3516 @var{value0}|@var{value1}|@var{value2}|..., where
3517 @var{valuei} is the value set on the @var{i}-th control.
3518 If @option{controls} is set to @code{help}, all available controls and
3519 their valid ranges are printed.
3521 @item sample_rate, s
3522 Specify the sample rate, default to 44100. Only used if plugin have
3526 Set the number of samples per channel per each output frame, default
3527 is 1024. Only used if plugin have zero inputs.
3530 Set the minimum duration of the sourced audio. See
3531 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
3532 for the accepted syntax.
3533 Note that the resulting duration may be greater than the specified duration,
3534 as the generated audio is always cut at the end of a complete frame.
3535 If not specified, or the expressed duration is negative, the audio is
3536 supposed to be generated forever.
3537 Only used if plugin have zero inputs.
3541 @subsection Examples
3545 List all available plugins within amp (LADSPA example plugin) library:
3551 List all available controls and their valid ranges for @code{vcf_notch}
3552 plugin from @code{VCF} library:
3554 ladspa=f=vcf:p=vcf_notch:c=help
3558 Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
3561 ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
3565 Add reverberation to the audio using TAP-plugins
3566 (Tom's Audio Processing plugins):
3568 ladspa=file=tap_reverb:tap_reverb
3572 Generate white noise, with 0.2 amplitude:
3574 ladspa=file=cmt:noise_source_white:c=c0=.2
3578 Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
3579 @code{C* Audio Plugin Suite} (CAPS) library:
3581 ladspa=file=caps:Click:c=c1=20'
3585 Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
3587 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
3591 Increase volume by 20dB using fast lookahead limiter from Steve Harris
3592 @code{SWH Plugins} collection:
3594 ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
3598 Attenuate low frequencies using Multiband EQ from Steve Harris
3599 @code{SWH Plugins} collection:
3601 ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
3605 Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite}
3608 ladspa=caps:Narrower
3612 Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library:
3614 ladspa=caps:White:.2
3618 Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library:
3620 ladspa=caps:Fractal:c=c1=1
3624 Dynamic volume normalization using @code{VLevel} plugin:
3626 ladspa=vlevel-ladspa:vlevel_mono
3630 @subsection Commands
3632 This filter supports the following commands:
3635 Modify the @var{N}-th control value.
3637 If the specified value is not valid, it is ignored and prior one is kept.
3642 EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
3643 Support for both single pass (livestreams, files) and double pass (files) modes.
3644 This algorithm can target IL, LRA, and maximum true peak. To accurately detect true peaks,
3645 the audio stream will be upsampled to 192 kHz unless the normalization mode is linear.
3646 Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate.
3648 The filter accepts the following options:
3652 Set integrated loudness target.
3653 Range is -70.0 - -5.0. Default value is -24.0.
3656 Set loudness range target.
3657 Range is 1.0 - 20.0. Default value is 7.0.
3660 Set maximum true peak.
3661 Range is -9.0 - +0.0. Default value is -2.0.
3663 @item measured_I, measured_i
3664 Measured IL of input file.
3665 Range is -99.0 - +0.0.
3667 @item measured_LRA, measured_lra
3668 Measured LRA of input file.
3669 Range is 0.0 - 99.0.
3671 @item measured_TP, measured_tp
3672 Measured true peak of input file.
3673 Range is -99.0 - +99.0.
3675 @item measured_thresh
3676 Measured threshold of input file.
3677 Range is -99.0 - +0.0.
3680 Set offset gain. Gain is applied before the true-peak limiter.
3681 Range is -99.0 - +99.0. Default is +0.0.
3684 Normalize linearly if possible.
3685 measured_I, measured_LRA, measured_TP, and measured_thresh must also
3686 to be specified in order to use this mode.
3687 Options are true or false. Default is true.
3690 Treat mono input files as "dual-mono". If a mono file is intended for playback
3691 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
3692 If set to @code{true}, this option will compensate for this effect.
3693 Multi-channel input files are not affected by this option.
3694 Options are true or false. Default is false.
3697 Set print format for stats. Options are summary, json, or none.
3698 Default value is none.
3703 Apply a low-pass filter with 3dB point frequency.
3704 The filter can be either single-pole or double-pole (the default).
3705 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
3707 The filter accepts the following options:
3711 Set frequency in Hz. Default is 500.
3714 Set number of poles. Default is 2.
3717 Set method to specify band-width of filter.
3732 Specify the band-width of a filter in width_type units.
3733 Applies only to double-pole filter.
3734 The default is 0.707q and gives a Butterworth response.
3737 Specify which channels to filter, by default all available are filtered.
3740 @subsection Examples
3743 Lowpass only LFE channel, it LFE is not present it does nothing:
3749 @subsection Commands
3751 This filter supports the following commands:
3754 Change lowpass frequency.
3755 Syntax for the command is : "@var{frequency}"
3758 Change lowpass width_type.
3759 Syntax for the command is : "@var{width_type}"
3762 Change lowpass width.
3763 Syntax for the command is : "@var{width}"
3768 Load a LV2 (LADSPA Version 2) plugin.
3770 To enable compilation of this filter you need to configure FFmpeg with
3771 @code{--enable-lv2}.
3775 Specifies the plugin URI. You may need to escape ':'.
3778 Set the '|' separated list of controls which are zero or more floating point
3779 values that determine the behavior of the loaded plugin (for example delay,
3781 If @option{controls} is set to @code{help}, all available controls and
3782 their valid ranges are printed.
3784 @item sample_rate, s
3785 Specify the sample rate, default to 44100. Only used if plugin have
3789 Set the number of samples per channel per each output frame, default
3790 is 1024. Only used if plugin have zero inputs.
3793 Set the minimum duration of the sourced audio. See
3794 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
3795 for the accepted syntax.
3796 Note that the resulting duration may be greater than the specified duration,
3797 as the generated audio is always cut at the end of a complete frame.
3798 If not specified, or the expressed duration is negative, the audio is
3799 supposed to be generated forever.
3800 Only used if plugin have zero inputs.
3803 @subsection Examples
3807 Apply bass enhancer plugin from Calf:
3809 lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
3813 Apply vinyl plugin from Calf:
3815 lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
3819 Apply bit crusher plugin from ArtyFX:
3821 lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
3826 Multiband Compress or expand the audio's dynamic range.
3828 The input audio is divided into bands using 4th order Linkwitz-Riley IIRs.
3829 This is akin to the crossover of a loudspeaker, and results in flat frequency
3830 response when absent compander action.
3832 It accepts the following parameters:
3836 This option syntax is:
3837 attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ...
3838 For explanation of each item refer to compand filter documentation.
3844 Mix channels with specific gain levels. The filter accepts the output
3845 channel layout followed by a set of channels definitions.
3847 This filter is also designed to efficiently remap the channels of an audio
3850 The filter accepts parameters of the form:
3851 "@var{l}|@var{outdef}|@var{outdef}|..."
3855 output channel layout or number of channels
3858 output channel specification, of the form:
3859 "@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]"
3862 output channel to define, either a channel name (FL, FR, etc.) or a channel
3863 number (c0, c1, etc.)
3866 multiplicative coefficient for the channel, 1 leaving the volume unchanged
3869 input channel to use, see out_name for details; it is not possible to mix
3870 named and numbered input channels
3873 If the `=' in a channel specification is replaced by `<', then the gains for
3874 that specification will be renormalized so that the total is 1, thus
3875 avoiding clipping noise.
3877 @subsection Mixing examples
3879 For example, if you want to down-mix from stereo to mono, but with a bigger
3880 factor for the left channel:
3882 pan=1c|c0=0.9*c0+0.1*c1
3885 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
3886 7-channels surround:
3888 pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
3891 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
3892 that should be preferred (see "-ac" option) unless you have very specific
3895 @subsection Remapping examples
3897 The channel remapping will be effective if, and only if:
3900 @item gain coefficients are zeroes or ones,
3901 @item only one input per channel output,
3904 If all these conditions are satisfied, the filter will notify the user ("Pure
3905 channel mapping detected"), and use an optimized and lossless method to do the
3908 For example, if you have a 5.1 source and want a stereo audio stream by
3909 dropping the extra channels:
3911 pan="stereo| c0=FL | c1=FR"
3914 Given the same source, you can also switch front left and front right channels
3915 and keep the input channel layout:
3917 pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
3920 If the input is a stereo audio stream, you can mute the front left channel (and
3921 still keep the stereo channel layout) with:
3926 Still with a stereo audio stream input, you can copy the right channel in both
3927 front left and right:
3929 pan="stereo| c0=FR | c1=FR"
3934 ReplayGain scanner filter. This filter takes an audio stream as an input and
3935 outputs it unchanged.
3936 At end of filtering it displays @code{track_gain} and @code{track_peak}.
3940 Convert the audio sample format, sample rate and channel layout. It is
3941 not meant to be used directly.
3944 Apply time-stretching and pitch-shifting with librubberband.
3946 To enable compilation of this filter, you need to configure FFmpeg with
3947 @code{--enable-librubberband}.
3949 The filter accepts the following options:
3953 Set tempo scale factor.
3956 Set pitch scale factor.
3959 Set transients detector.
3960 Possible values are:
3969 Possible values are:
3978 Possible values are:
3985 Set processing window size.
3986 Possible values are:
3995 Possible values are:
4002 Enable formant preservation when shift pitching.
4003 Possible values are:
4011 Possible values are:
4020 Possible values are:
4027 @section sidechaincompress
4029 This filter acts like normal compressor but has the ability to compress
4030 detected signal using second input signal.
4031 It needs two input streams and returns one output stream.
4032 First input stream will be processed depending on second stream signal.
4033 The filtered signal then can be filtered with other filters in later stages of
4034 processing. See @ref{pan} and @ref{amerge} filter.
4036 The filter accepts the following options:
4040 Set input gain. Default is 1. Range is between 0.015625 and 64.
4043 If a signal of second stream raises above this level it will affect the gain
4044 reduction of first stream.
4045 By default is 0.125. Range is between 0.00097563 and 1.
4048 Set a ratio about which the signal is reduced. 1:2 means that if the level
4049 raised 4dB above the threshold, it will be only 2dB above after the reduction.
4050 Default is 2. Range is between 1 and 20.
4053 Amount of milliseconds the signal has to rise above the threshold before gain
4054 reduction starts. Default is 20. Range is between 0.01 and 2000.
4057 Amount of milliseconds the signal has to fall below the threshold before
4058 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
4061 Set the amount by how much signal will be amplified after processing.
4062 Default is 1. Range is from 1 to 64.
4065 Curve the sharp knee around the threshold to enter gain reduction more softly.
4066 Default is 2.82843. Range is between 1 and 8.
4069 Choose if the @code{average} level between all channels of side-chain stream
4070 or the louder(@code{maximum}) channel of side-chain stream affects the
4071 reduction. Default is @code{average}.
4074 Should the exact signal be taken in case of @code{peak} or an RMS one in case
4075 of @code{rms}. Default is @code{rms} which is mainly smoother.
4078 Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
4081 How much to use compressed signal in output. Default is 1.
4082 Range is between 0 and 1.
4085 @subsection Examples
4089 Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
4090 depending on the signal of 2nd input and later compressed signal to be
4091 merged with 2nd input:
4093 ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
4097 @section sidechaingate
4099 A sidechain gate acts like a normal (wideband) gate but has the ability to
4100 filter the detected signal before sending it to the gain reduction stage.
4101 Normally a gate uses the full range signal to detect a level above the
4103 For example: If you cut all lower frequencies from your sidechain signal
4104 the gate will decrease the volume of your track only if not enough highs
4105 appear. With this technique you are able to reduce the resonation of a
4106 natural drum or remove "rumbling" of muted strokes from a heavily distorted
4108 It needs two input streams and returns one output stream.
4109 First input stream will be processed depending on second stream signal.
4111 The filter accepts the following options:
4115 Set input level before filtering.
4116 Default is 1. Allowed range is from 0.015625 to 64.
4119 Set the level of gain reduction when the signal is below the threshold.
4120 Default is 0.06125. Allowed range is from 0 to 1.
4123 If a signal rises above this level the gain reduction is released.
4124 Default is 0.125. Allowed range is from 0 to 1.
4127 Set a ratio about which the signal is reduced.
4128 Default is 2. Allowed range is from 1 to 9000.
4131 Amount of milliseconds the signal has to rise above the threshold before gain
4133 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
4136 Amount of milliseconds the signal has to fall below the threshold before the
4137 reduction is increased again. Default is 250 milliseconds.
4138 Allowed range is from 0.01 to 9000.
4141 Set amount of amplification of signal after processing.
4142 Default is 1. Allowed range is from 1 to 64.
4145 Curve the sharp knee around the threshold to enter gain reduction more softly.
4146 Default is 2.828427125. Allowed range is from 1 to 8.
4149 Choose if exact signal should be taken for detection or an RMS like one.
4150 Default is rms. Can be peak or rms.
4153 Choose if the average level between all channels or the louder channel affects
4155 Default is average. Can be average or maximum.
4158 Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
4161 @section silencedetect
4163 Detect silence in an audio stream.
4165 This filter logs a message when it detects that the input audio volume is less
4166 or equal to a noise tolerance value for a duration greater or equal to the
4167 minimum detected noise duration.
4169 The printed times and duration are expressed in seconds.
4171 The filter accepts the following options:
4175 Set silence duration until notification (default is 2 seconds).
4178 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
4179 specified value) or amplitude ratio. Default is -60dB, or 0.001.
4182 @subsection Examples
4186 Detect 5 seconds of silence with -50dB noise tolerance:
4188 silencedetect=n=-50dB:d=5
4192 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
4193 tolerance in @file{silence.mp3}:
4195 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
4199 @section silenceremove
4201 Remove silence from the beginning, middle or end of the audio.
4203 The filter accepts the following options:
4207 This value is used to indicate if audio should be trimmed at beginning of
4208 the audio. A value of zero indicates no silence should be trimmed from the
4209 beginning. When specifying a non-zero value, it trims audio up until it
4210 finds non-silence. Normally, when trimming silence from beginning of audio
4211 the @var{start_periods} will be @code{1} but it can be increased to higher
4212 values to trim all audio up to specific count of non-silence periods.
4213 Default value is @code{0}.
4215 @item start_duration
4216 Specify the amount of time that non-silence must be detected before it stops
4217 trimming audio. By increasing the duration, bursts of noises can be treated
4218 as silence and trimmed off. Default value is @code{0}.
4220 @item start_threshold
4221 This indicates what sample value should be treated as silence. For digital
4222 audio, a value of @code{0} may be fine but for audio recorded from analog,
4223 you may wish to increase the value to account for background noise.
4224 Can be specified in dB (in case "dB" is appended to the specified value)
4225 or amplitude ratio. Default value is @code{0}.
4228 Set the count for trimming silence from the end of audio.
4229 To remove silence from the middle of a file, specify a @var{stop_periods}
4230 that is negative. This value is then treated as a positive value and is
4231 used to indicate the effect should restart processing as specified by
4232 @var{start_periods}, making it suitable for removing periods of silence
4233 in the middle of the audio.
4234 Default value is @code{0}.
4237 Specify a duration of silence that must exist before audio is not copied any
4238 more. By specifying a higher duration, silence that is wanted can be left in
4240 Default value is @code{0}.
4242 @item stop_threshold
4243 This is the same as @option{start_threshold} but for trimming silence from
4245 Can be specified in dB (in case "dB" is appended to the specified value)
4246 or amplitude ratio. Default value is @code{0}.
4249 This indicates that @var{stop_duration} length of audio should be left intact
4250 at the beginning of each period of silence.
4251 For example, if you want to remove long pauses between words but do not want
4252 to remove the pauses completely. Default value is @code{0}.
4255 Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
4256 and works better with digital silence which is exactly 0.
4257 Default value is @code{rms}.
4260 Set ratio used to calculate size of window for detecting silence.
4261 Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
4264 @subsection Examples
4268 The following example shows how this filter can be used to start a recording
4269 that does not contain the delay at the start which usually occurs between
4270 pressing the record button and the start of the performance:
4272 silenceremove=1:5:0.02
4276 Trim all silence encountered from beginning to end where there is more than 1
4277 second of silence in audio:
4279 silenceremove=0:0:0:-1:1:-90dB
4285 SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
4286 loudspeakers around the user for binaural listening via headphones (audio
4287 formats up to 9 channels supported).
4288 The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
4289 SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
4290 Austrian Academy of Sciences.
4292 To enable compilation of this filter you need to configure FFmpeg with
4293 @code{--enable-libmysofa}.
4295 The filter accepts the following options:
4299 Set the SOFA file used for rendering.
4302 Set gain applied to audio. Value is in dB. Default is 0.
4305 Set rotation of virtual loudspeakers in deg. Default is 0.
4308 Set elevation of virtual speakers in deg. Default is 0.
4311 Set distance in meters between loudspeakers and the listener with near-field
4312 HRTFs. Default is 1.
4315 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
4316 processing audio in time domain which is slow.
4317 @var{freq} is processing audio in frequency domain which is fast.
4318 Default is @var{freq}.
4321 Set custom positions of virtual loudspeakers. Syntax for this option is:
4322 <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
4323 Each virtual loudspeaker is described with short channel name following with
4324 azimuth and elevation in degrees.
4325 Each virtual loudspeaker description is separated by '|'.
4326 For example to override front left and front right channel positions use:
4327 'speakers=FL 45 15|FR 345 15'.
4328 Descriptions with unrecognised channel names are ignored.
4331 Set custom gain for LFE channels. Value is in dB. Default is 0.
4334 @subsection Examples
4338 Using ClubFritz6 sofa file:
4340 sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
4344 Using ClubFritz12 sofa file and bigger radius with small rotation:
4346 sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
4350 Similar as above but with custom speaker positions for front left, front right, back left and back right
4351 and also with custom gain:
4353 "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
4357 @section stereotools
4359 This filter has some handy utilities to manage stereo signals, for converting
4360 M/S stereo recordings to L/R signal while having control over the parameters
4361 or spreading the stereo image of master track.
4363 The filter accepts the following options:
4367 Set input level before filtering for both channels. Defaults is 1.
4368 Allowed range is from 0.015625 to 64.
4371 Set output level after filtering for both channels. Defaults is 1.
4372 Allowed range is from 0.015625 to 64.
4375 Set input balance between both channels. Default is 0.
4376 Allowed range is from -1 to 1.
4379 Set output balance between both channels. Default is 0.
4380 Allowed range is from -1 to 1.
4383 Enable softclipping. Results in analog distortion instead of harsh digital 0dB
4384 clipping. Disabled by default.
4387 Mute the left channel. Disabled by default.
4390 Mute the right channel. Disabled by default.
4393 Change the phase of the left channel. Disabled by default.
4396 Change the phase of the right channel. Disabled by default.
4399 Set stereo mode. Available values are:
4403 Left/Right to Left/Right, this is default.
4406 Left/Right to Mid/Side.
4409 Mid/Side to Left/Right.
4412 Left/Right to Left/Left.
4415 Left/Right to Right/Right.
4418 Left/Right to Left + Right.
4421 Left/Right to Right/Left.
4424 Mid/Side to Left/Left.
4427 Mid/Side to Right/Right.
4431 Set level of side signal. Default is 1.
4432 Allowed range is from 0.015625 to 64.
4435 Set balance of side signal. Default is 0.
4436 Allowed range is from -1 to 1.
4439 Set level of the middle signal. Default is 1.
4440 Allowed range is from 0.015625 to 64.
4443 Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
4446 Set stereo base between mono and inversed channels. Default is 0.
4447 Allowed range is from -1 to 1.
4450 Set delay in milliseconds how much to delay left from right channel and
4451 vice versa. Default is 0. Allowed range is from -20 to 20.
4454 Set S/C level. Default is 1. Allowed range is from 1 to 100.
4457 Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
4459 @item bmode_in, bmode_out
4460 Set balance mode for balance_in/balance_out option.
4462 Can be one of the following:
4466 Classic balance mode. Attenuate one channel at time.
4467 Gain is raised up to 1.
4470 Similar as classic mode above but gain is raised up to 2.
4473 Equal power distribution, from -6dB to +6dB range.
4477 @subsection Examples
4481 Apply karaoke like effect:
4483 stereotools=mlev=0.015625
4487 Convert M/S signal to L/R:
4489 "stereotools=mode=ms>lr"
4493 @section stereowiden
4495 This filter enhance the stereo effect by suppressing signal common to both
4496 channels and by delaying the signal of left into right and vice versa,
4497 thereby widening the stereo effect.
4499 The filter accepts the following options:
4503 Time in milliseconds of the delay of left signal into right and vice versa.
4504 Default is 20 milliseconds.
4507 Amount of gain in delayed signal into right and vice versa. Gives a delay
4508 effect of left signal in right output and vice versa which gives widening
4509 effect. Default is 0.3.
4512 Cross feed of left into right with inverted phase. This helps in suppressing
4513 the mono. If the value is 1 it will cancel all the signal common to both
4514 channels. Default is 0.3.
4517 Set level of input signal of original channel. Default is 0.8.
4520 @section superequalizer
4521 Apply 18 band equalizer.
4523 The filter accepts the following options:
4530 Set 131Hz band gain.
4532 Set 185Hz band gain.
4534 Set 262Hz band gain.
4536 Set 370Hz band gain.
4538 Set 523Hz band gain.
4540 Set 740Hz band gain.
4542 Set 1047Hz band gain.
4544 Set 1480Hz band gain.
4546 Set 2093Hz band gain.
4548 Set 2960Hz band gain.
4550 Set 4186Hz band gain.
4552 Set 5920Hz band gain.
4554 Set 8372Hz band gain.
4556 Set 11840Hz band gain.
4558 Set 16744Hz band gain.
4560 Set 20000Hz band gain.
4564 Apply audio surround upmix filter.
4566 This filter allows to produce multichannel output from audio stream.
4568 The filter accepts the following options:
4572 Set output channel layout. By default, this is @var{5.1}.
4574 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4575 for the required syntax.
4578 Set input channel layout. By default, this is @var{stereo}.
4580 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4581 for the required syntax.
4584 Set input volume level. By default, this is @var{1}.
4587 Set output volume level. By default, this is @var{1}.
4590 Enable LFE channel output if output channel layout has it. By default, this is enabled.
4593 Set LFE low cut off frequency. By default, this is @var{128} Hz.
4596 Set LFE high cut off frequency. By default, this is @var{256} Hz.
4599 Set front center input volume. By default, this is @var{1}.
4602 Set front center output volume. By default, this is @var{1}.
4605 Set LFE input volume. By default, this is @var{1}.
4608 Set LFE output volume. By default, this is @var{1}.
4611 @section treble, highshelf
4613 Boost or cut treble (upper) frequencies of the audio using a two-pole
4614 shelving filter with a response similar to that of a standard
4615 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
4617 The filter accepts the following options:
4621 Give the gain at whichever is the lower of ~22 kHz and the
4622 Nyquist frequency. Its useful range is about -20 (for a large cut)
4623 to +20 (for a large boost). Beware of clipping when using a positive gain.
4626 Set the filter's central frequency and so can be used
4627 to extend or reduce the frequency range to be boosted or cut.
4628 The default value is @code{3000} Hz.
4631 Set method to specify band-width of filter.
4646 Determine how steep is the filter's shelf transition.
4649 Specify which channels to filter, by default all available are filtered.
4652 @subsection Commands
4654 This filter supports the following commands:
4657 Change treble frequency.
4658 Syntax for the command is : "@var{frequency}"
4661 Change treble width_type.
4662 Syntax for the command is : "@var{width_type}"
4665 Change treble width.
4666 Syntax for the command is : "@var{width}"
4670 Syntax for the command is : "@var{gain}"
4675 Sinusoidal amplitude modulation.
4677 The filter accepts the following options:
4681 Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
4682 (20 Hz or lower) will result in a tremolo effect.
4683 This filter may also be used as a ring modulator by specifying
4684 a modulation frequency higher than 20 Hz.
4685 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
4688 Depth of modulation as a percentage. Range is 0.0 - 1.0.
4689 Default value is 0.5.
4694 Sinusoidal phase modulation.
4696 The filter accepts the following options:
4700 Modulation frequency in Hertz.
4701 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
4704 Depth of modulation as a percentage. Range is 0.0 - 1.0.
4705 Default value is 0.5.
4710 Adjust the input audio volume.
4712 It accepts the following parameters:
4716 Set audio volume expression.
4718 Output values are clipped to the maximum value.
4720 The output audio volume is given by the relation:
4722 @var{output_volume} = @var{volume} * @var{input_volume}
4725 The default value for @var{volume} is "1.0".
4728 This parameter represents the mathematical precision.
4730 It determines which input sample formats will be allowed, which affects the
4731 precision of the volume scaling.
4735 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
4737 32-bit floating-point; this limits input sample format to FLT. (default)
4739 64-bit floating-point; this limits input sample format to DBL.
4743 Choose the behaviour on encountering ReplayGain side data in input frames.
4747 Remove ReplayGain side data, ignoring its contents (the default).
4750 Ignore ReplayGain side data, but leave it in the frame.
4753 Prefer the track gain, if present.
4756 Prefer the album gain, if present.
4759 @item replaygain_preamp
4760 Pre-amplification gain in dB to apply to the selected replaygain gain.
4762 Default value for @var{replaygain_preamp} is 0.0.
4765 Set when the volume expression is evaluated.
4767 It accepts the following values:
4770 only evaluate expression once during the filter initialization, or
4771 when the @samp{volume} command is sent
4774 evaluate expression for each incoming frame
4777 Default value is @samp{once}.
4780 The volume expression can contain the following parameters.
4784 frame number (starting at zero)
4787 @item nb_consumed_samples
4788 number of samples consumed by the filter
4790 number of samples in the current frame
4792 original frame position in the file
4798 PTS at start of stream
4800 time at start of stream
4806 last set volume value
4809 Note that when @option{eval} is set to @samp{once} only the
4810 @var{sample_rate} and @var{tb} variables are available, all other
4811 variables will evaluate to NAN.
4813 @subsection Commands
4815 This filter supports the following commands:
4818 Modify the volume expression.
4819 The command accepts the same syntax of the corresponding option.
4821 If the specified expression is not valid, it is kept at its current
4823 @item replaygain_noclip
4824 Prevent clipping by limiting the gain applied.
4826 Default value for @var{replaygain_noclip} is 1.
4830 @subsection Examples
4834 Halve the input audio volume:
4838 volume=volume=-6.0206dB
4841 In all the above example the named key for @option{volume} can be
4842 omitted, for example like in:
4848 Increase input audio power by 6 decibels using fixed-point precision:
4850 volume=volume=6dB:precision=fixed
4854 Fade volume after time 10 with an annihilation period of 5 seconds:
4856 volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
4860 @section volumedetect
4862 Detect the volume of the input video.
4864 The filter has no parameters. The input is not modified. Statistics about
4865 the volume will be printed in the log when the input stream end is reached.
4867 In particular it will show the mean volume (root mean square), maximum
4868 volume (on a per-sample basis), and the beginning of a histogram of the
4869 registered volume values (from the maximum value to a cumulated 1/1000 of
4872 All volumes are in decibels relative to the maximum PCM value.
4874 @subsection Examples
4876 Here is an excerpt of the output:
4878 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
4879 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
4880 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
4881 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
4882 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
4883 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
4884 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
4885 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
4886 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
4892 The mean square energy is approximately -27 dB, or 10^-2.7.
4894 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
4896 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
4899 In other words, raising the volume by +4 dB does not cause any clipping,
4900 raising it by +5 dB causes clipping for 6 samples, etc.
4902 @c man end AUDIO FILTERS
4904 @chapter Audio Sources
4905 @c man begin AUDIO SOURCES
4907 Below is a description of the currently available audio sources.
4911 Buffer audio frames, and make them available to the filter chain.
4913 This source is mainly intended for a programmatic use, in particular
4914 through the interface defined in @file{libavfilter/asrc_abuffer.h}.
4916 It accepts the following parameters:
4920 The timebase which will be used for timestamps of submitted frames. It must be
4921 either a floating-point number or in @var{numerator}/@var{denominator} form.
4924 The sample rate of the incoming audio buffers.
4927 The sample format of the incoming audio buffers.
4928 Either a sample format name or its corresponding integer representation from
4929 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
4931 @item channel_layout
4932 The channel layout of the incoming audio buffers.
4933 Either a channel layout name from channel_layout_map in
4934 @file{libavutil/channel_layout.c} or its corresponding integer representation
4935 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
4938 The number of channels of the incoming audio buffers.
4939 If both @var{channels} and @var{channel_layout} are specified, then they
4944 @subsection Examples
4947 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
4950 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
4951 Since the sample format with name "s16p" corresponds to the number
4952 6 and the "stereo" channel layout corresponds to the value 0x3, this is
4955 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
4960 Generate an audio signal specified by an expression.
4962 This source accepts in input one or more expressions (one for each
4963 channel), which are evaluated and used to generate a corresponding
4966 This source accepts the following options:
4970 Set the '|'-separated expressions list for each separate channel. In case the
4971 @option{channel_layout} option is not specified, the selected channel layout
4972 depends on the number of provided expressions. Otherwise the last
4973 specified expression is applied to the remaining output channels.
4975 @item channel_layout, c
4976 Set the channel layout. The number of channels in the specified layout
4977 must be equal to the number of specified expressions.
4980 Set the minimum duration of the sourced audio. See
4981 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4982 for the accepted syntax.
4983 Note that the resulting duration may be greater than the specified
4984 duration, as the generated audio is always cut at the end of a
4987 If not specified, or the expressed duration is negative, the audio is
4988 supposed to be generated forever.
4991 Set the number of samples per channel per each output frame,
4994 @item sample_rate, s
4995 Specify the sample rate, default to 44100.
4998 Each expression in @var{exprs} can contain the following constants:
5002 number of the evaluated sample, starting from 0
5005 time of the evaluated sample expressed in seconds, starting from 0
5012 @subsection Examples
5022 Generate a sin signal with frequency of 440 Hz, set sample rate to
5025 aevalsrc="sin(440*2*PI*t):s=8000"
5029 Generate a two channels signal, specify the channel layout (Front
5030 Center + Back Center) explicitly:
5032 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
5036 Generate white noise:
5038 aevalsrc="-2+random(0)"
5042 Generate an amplitude modulated signal:
5044 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
5048 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
5050 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
5057 The null audio source, return unprocessed audio frames. It is mainly useful
5058 as a template and to be employed in analysis / debugging tools, or as
5059 the source for filters which ignore the input data (for example the sox
5062 This source accepts the following options:
5066 @item channel_layout, cl
5068 Specifies the channel layout, and can be either an integer or a string
5069 representing a channel layout. The default value of @var{channel_layout}
5072 Check the channel_layout_map definition in
5073 @file{libavutil/channel_layout.c} for the mapping between strings and
5074 channel layout values.
5076 @item sample_rate, r
5077 Specifies the sample rate, and defaults to 44100.
5080 Set the number of samples per requested frames.
5084 @subsection Examples
5088 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
5090 anullsrc=r=48000:cl=4
5094 Do the same operation with a more obvious syntax:
5096 anullsrc=r=48000:cl=mono
5100 All the parameters need to be explicitly defined.
5104 Synthesize a voice utterance using the libflite library.
5106 To enable compilation of this filter you need to configure FFmpeg with
5107 @code{--enable-libflite}.
5109 Note that versions of the flite library prior to 2.0 are not thread-safe.
5111 The filter accepts the following options:
5116 If set to 1, list the names of the available voices and exit
5117 immediately. Default value is 0.
5120 Set the maximum number of samples per frame. Default value is 512.
5123 Set the filename containing the text to speak.
5126 Set the text to speak.
5129 Set the voice to use for the speech synthesis. Default value is
5130 @code{kal}. See also the @var{list_voices} option.
5133 @subsection Examples
5137 Read from file @file{speech.txt}, and synthesize the text using the
5138 standard flite voice:
5140 flite=textfile=speech.txt
5144 Read the specified text selecting the @code{slt} voice:
5146 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
5150 Input text to ffmpeg:
5152 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
5156 Make @file{ffplay} speak the specified text, using @code{flite} and
5157 the @code{lavfi} device:
5159 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
5163 For more information about libflite, check:
5164 @url{http://www.festvox.org/flite/}
5168 Generate a noise audio signal.
5170 The filter accepts the following options:
5173 @item sample_rate, r
5174 Specify the sample rate. Default value is 48000 Hz.
5177 Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value
5181 Specify the duration of the generated audio stream. Not specifying this option
5182 results in noise with an infinite length.
5184 @item color, colour, c
5185 Specify the color of noise. Available noise colors are white, pink, brown,
5186 blue and violet. Default color is white.
5189 Specify a value used to seed the PRNG.
5192 Set the number of samples per each output frame, default is 1024.
5195 @subsection Examples
5200 Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5:
5202 anoisesrc=d=60:c=pink:r=44100:a=0.5
5208 Generate odd-tap Hilbert transform FIR coefficients.
5210 The resulting stream can be used with @ref{afir} filter for phase-shifting
5211 the signal by 90 degrees.
5213 This is used in many matrix coding schemes and for analytic signal generation.
5214 The process is often written as a multiplication by i (or j), the imaginary unit.
5216 The filter accepts the following options:
5220 @item sample_rate, s
5221 Set sample rate, default is 44100.
5224 Set length of FIR filter, default is 22051.
5227 Set number of samples per each frame.
5230 Set window function to be used when generating FIR coefficients.
5235 Generate an audio signal made of a sine wave with amplitude 1/8.
5237 The audio signal is bit-exact.
5239 The filter accepts the following options:
5244 Set the carrier frequency. Default is 440 Hz.
5246 @item beep_factor, b
5247 Enable a periodic beep every second with frequency @var{beep_factor} times
5248 the carrier frequency. Default is 0, meaning the beep is disabled.
5250 @item sample_rate, r
5251 Specify the sample rate, default is 44100.
5254 Specify the duration of the generated audio stream.
5256 @item samples_per_frame
5257 Set the number of samples per output frame.
5259 The expression can contain the following constants:
5263 The (sequential) number of the output audio frame, starting from 0.
5266 The PTS (Presentation TimeStamp) of the output audio frame,
5267 expressed in @var{TB} units.
5270 The PTS of the output audio frame, expressed in seconds.
5273 The timebase of the output audio frames.
5276 Default is @code{1024}.
5279 @subsection Examples
5284 Generate a simple 440 Hz sine wave:
5290 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
5294 sine=frequency=220:beep_factor=4:duration=5
5298 Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC
5301 sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
5305 @c man end AUDIO SOURCES
5307 @chapter Audio Sinks
5308 @c man begin AUDIO SINKS
5310 Below is a description of the currently available audio sinks.
5312 @section abuffersink
5314 Buffer audio frames, and make them available to the end of filter chain.
5316 This sink is mainly intended for programmatic use, in particular
5317 through the interface defined in @file{libavfilter/buffersink.h}
5318 or the options system.
5320 It accepts a pointer to an AVABufferSinkContext structure, which
5321 defines the incoming buffers' formats, to be passed as the opaque
5322 parameter to @code{avfilter_init_filter} for initialization.
5325 Null audio sink; do absolutely nothing with the input audio. It is
5326 mainly useful as a template and for use in analysis / debugging
5329 @c man end AUDIO SINKS
5331 @chapter Video Filters
5332 @c man begin VIDEO FILTERS
5334 When you configure your FFmpeg build, you can disable any of the
5335 existing filters using @code{--disable-filters}.
5336 The configure output will show the video filters included in your
5339 Below is a description of the currently available video filters.
5341 @section alphaextract
5343 Extract the alpha component from the input as a grayscale video. This
5344 is especially useful with the @var{alphamerge} filter.
5348 Add or replace the alpha component of the primary input with the
5349 grayscale value of a second input. This is intended for use with
5350 @var{alphaextract} to allow the transmission or storage of frame
5351 sequences that have alpha in a format that doesn't support an alpha
5354 For example, to reconstruct full frames from a normal YUV-encoded video
5355 and a separate video created with @var{alphaextract}, you might use:
5357 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
5360 Since this filter is designed for reconstruction, it operates on frame
5361 sequences without considering timestamps, and terminates when either
5362 input reaches end of stream. This will cause problems if your encoding
5363 pipeline drops frames. If you're trying to apply an image as an
5364 overlay to a video stream, consider the @var{overlay} filter instead.
5368 Amplify differences between current pixel and pixels of adjacent frames in
5369 same pixel location.
5371 This filter accepts the following options:
5375 Set frame radius. Default is 2. Allowed range is from 1 to 63.
5376 For example radius of 3 will instruct filter to calculate average of 7 frames.
5379 Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535.
5382 Set threshold for difference amplification. Any differrence greater or equal to
5383 this value will not alter source pixel. Default is 10.
5384 Allowed range is from 0 to 65535.
5387 Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
5388 This option controls maximum possible value that will decrease source pixel value.
5391 Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
5392 This option controls maximum possible value that will increase source pixel value.
5395 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
5400 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
5401 and libavformat to work. On the other hand, it is limited to ASS (Advanced
5402 Substation Alpha) subtitles files.
5404 This filter accepts the following option in addition to the common options from
5405 the @ref{subtitles} filter:
5409 Set the shaping engine
5411 Available values are:
5414 The default libass shaping engine, which is the best available.
5416 Fast, font-agnostic shaper that can do only substitutions
5418 Slower shaper using OpenType for substitutions and positioning
5421 The default is @code{auto}.
5425 Apply an Adaptive Temporal Averaging Denoiser to the video input.
5427 The filter accepts the following options:
5431 Set threshold A for 1st plane. Default is 0.02.
5432 Valid range is 0 to 0.3.
5435 Set threshold B for 1st plane. Default is 0.04.
5436 Valid range is 0 to 5.
5439 Set threshold A for 2nd plane. Default is 0.02.
5440 Valid range is 0 to 0.3.
5443 Set threshold B for 2nd plane. Default is 0.04.
5444 Valid range is 0 to 5.
5447 Set threshold A for 3rd plane. Default is 0.02.
5448 Valid range is 0 to 0.3.
5451 Set threshold B for 3rd plane. Default is 0.04.
5452 Valid range is 0 to 5.
5454 Threshold A is designed to react on abrupt changes in the input signal and
5455 threshold B is designed to react on continuous changes in the input signal.
5458 Set number of frames filter will use for averaging. Default is 9. Must be odd
5459 number in range [5, 129].
5462 Set what planes of frame filter will use for averaging. Default is all.
5467 Apply average blur filter.
5469 The filter accepts the following options:
5473 Set horizontal radius size.
5476 Set which planes to filter. By default all planes are filtered.
5479 Set vertical radius size, if zero it will be same as @code{sizeX}.
5480 Default is @code{0}.
5485 Compute the bounding box for the non-black pixels in the input frame
5488 This filter computes the bounding box containing all the pixels with a
5489 luminance value greater than the minimum allowed value.
5490 The parameters describing the bounding box are printed on the filter
5493 The filter accepts the following option:
5497 Set the minimal luminance value. Default is @code{16}.
5500 @section bitplanenoise
5502 Show and measure bit plane noise.
5504 The filter accepts the following options:
5508 Set which plane to analyze. Default is @code{1}.
5511 Filter out noisy pixels from @code{bitplane} set above.
5512 Default is disabled.
5515 @section blackdetect
5517 Detect video intervals that are (almost) completely black. Can be
5518 useful to detect chapter transitions, commercials, or invalid
5519 recordings. Output lines contains the time for the start, end and
5520 duration of the detected black interval expressed in seconds.
5522 In order to display the output lines, you need to set the loglevel at
5523 least to the AV_LOG_INFO value.
5525 The filter accepts the following options:
5528 @item black_min_duration, d
5529 Set the minimum detected black duration expressed in seconds. It must
5530 be a non-negative floating point number.
5532 Default value is 2.0.
5534 @item picture_black_ratio_th, pic_th
5535 Set the threshold for considering a picture "black".
5536 Express the minimum value for the ratio:
5538 @var{nb_black_pixels} / @var{nb_pixels}
5541 for which a picture is considered black.
5542 Default value is 0.98.
5544 @item pixel_black_th, pix_th
5545 Set the threshold for considering a pixel "black".
5547 The threshold expresses the maximum pixel luminance value for which a
5548 pixel is considered "black". The provided value is scaled according to
5549 the following equation:
5551 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
5554 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
5555 the input video format, the range is [0-255] for YUV full-range
5556 formats and [16-235] for YUV non full-range formats.
5558 Default value is 0.10.
5561 The following example sets the maximum pixel threshold to the minimum
5562 value, and detects only black intervals of 2 or more seconds:
5564 blackdetect=d=2:pix_th=0.00
5569 Detect frames that are (almost) completely black. Can be useful to
5570 detect chapter transitions or commercials. Output lines consist of
5571 the frame number of the detected frame, the percentage of blackness,
5572 the position in the file if known or -1 and the timestamp in seconds.
5574 In order to display the output lines, you need to set the loglevel at
5575 least to the AV_LOG_INFO value.
5577 This filter exports frame metadata @code{lavfi.blackframe.pblack}.
5578 The value represents the percentage of pixels in the picture that
5579 are below the threshold value.
5581 It accepts the following parameters:
5586 The percentage of the pixels that have to be below the threshold; it defaults to
5589 @item threshold, thresh
5590 The threshold below which a pixel value is considered black; it defaults to
5595 @section blend, tblend
5597 Blend two video frames into each other.
5599 The @code{blend} filter takes two input streams and outputs one
5600 stream, the first input is the "top" layer and second input is
5601 "bottom" layer. By default, the output terminates when the longest input terminates.
5603 The @code{tblend} (time blend) filter takes two consecutive frames
5604 from one single stream, and outputs the result obtained by blending
5605 the new frame on top of the old frame.
5607 A description of the accepted options follows.
5615 Set blend mode for specific pixel component or all pixel components in case
5616 of @var{all_mode}. Default value is @code{normal}.
5618 Available values for component modes are:
5660 Set blend opacity for specific pixel component or all pixel components in case
5661 of @var{all_opacity}. Only used in combination with pixel component blend modes.
5668 Set blend expression for specific pixel component or all pixel components in case
5669 of @var{all_expr}. Note that related mode options will be ignored if those are set.
5671 The expressions can use the following variables:
5675 The sequential number of the filtered frame, starting from @code{0}.
5679 the coordinates of the current sample
5683 the width and height of currently filtered plane
5687 Width and height scale for the plane being filtered. It is the
5688 ratio between the dimensions of the current plane to the luma plane,
5689 e.g. for a @code{yuv420p} frame, the values are @code{1,1} for
5690 the luma plane and @code{0.5,0.5} for the chroma planes.
5693 Time of the current frame, expressed in seconds.
5696 Value of pixel component at current location for first video frame (top layer).
5699 Value of pixel component at current location for second video frame (bottom layer).
5703 The @code{blend} filter also supports the @ref{framesync} options.
5705 @subsection Examples
5709 Apply transition from bottom layer to top layer in first 10 seconds:
5711 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
5715 Apply linear horizontal transition from top layer to bottom layer:
5717 blend=all_expr='A*(X/W)+B*(1-X/W)'
5721 Apply 1x1 checkerboard effect:
5723 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
5727 Apply uncover left effect:
5729 blend=all_expr='if(gte(N*SW+X,W),A,B)'
5733 Apply uncover down effect:
5735 blend=all_expr='if(gte(Y-N*SH,0),A,B)'
5739 Apply uncover up-left effect:
5741 blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
5745 Split diagonally video and shows top and bottom layer on each side:
5747 blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
5751 Display differences between the current and the previous frame:
5753 tblend=all_mode=grainextract
5759 Denoise frames using Block-Matching 3D algorithm.
5761 The filter accepts the following options.
5765 Set denoising strength. Default value is 1.
5766 Allowed range is from 0 to 999.9.
5767 The denoising algorith is very sensitive to sigma, so adjust it
5768 according to the source.
5771 Set local patch size. This sets dimensions in 2D.
5774 Set sliding step for processing blocks. Default value is 4.
5775 Allowed range is from 1 to 64.
5776 Smaller values allows processing more reference blocks and is slower.
5779 Set maximal number of similar blocks for 3rd dimension. Default value is 1.
5780 When set to 1, no block matching is done. Larger values allows more blocks
5782 Allowed range is from 1 to 256.
5785 Set radius for search block matching. Default is 9.
5786 Allowed range is from 1 to INT32_MAX.
5789 Set step between two search locations for block matching. Default is 1.
5790 Allowed range is from 1 to 64. Smaller is slower.
5793 Set threshold of mean square error for block matching. Valid range is 0 to
5797 Set thresholding parameter for hard thresholding in 3D transformed domain.
5798 Larger values results in stronger hard-thresholding filtering in frequency
5802 Set filtering estimation mode. Can be @code{basic} or @code{final}.
5803 Default is @code{basic}.
5806 If enabled, filter will use 2nd stream for block matching.
5807 Default is disabled for @code{basic} value of @var{estim} option,
5808 and always enabled if value of @var{estim} is @code{final}.
5811 Set planes to filter. Default is all available except alpha.
5814 @subsection Examples
5818 Basic filtering with bm3d:
5820 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
5824 Same as above, but filtering only luma:
5826 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
5830 Same as above, but with both estimation modes:
5832 split[a][b],[a]bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
5836 Same as above, but prefilter with @ref{nlmeans} filter instead:
5838 split[a][b],[a]nlmeans=s=3:r=7:p=3[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
5844 Apply a boxblur algorithm to the input video.
5846 It accepts the following parameters:
5850 @item luma_radius, lr
5851 @item luma_power, lp
5852 @item chroma_radius, cr
5853 @item chroma_power, cp
5854 @item alpha_radius, ar
5855 @item alpha_power, ap
5859 A description of the accepted options follows.
5862 @item luma_radius, lr
5863 @item chroma_radius, cr
5864 @item alpha_radius, ar
5865 Set an expression for the box radius in pixels used for blurring the
5866 corresponding input plane.
5868 The radius value must be a non-negative number, and must not be
5869 greater than the value of the expression @code{min(w,h)/2} for the
5870 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
5873 Default value for @option{luma_radius} is "2". If not specified,
5874 @option{chroma_radius} and @option{alpha_radius} default to the
5875 corresponding value set for @option{luma_radius}.
5877 The expressions can contain the following constants:
5881 The input width and height in pixels.
5885 The input chroma image width and height in pixels.
5889 The horizontal and vertical chroma subsample values. For example, for the
5890 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
5893 @item luma_power, lp
5894 @item chroma_power, cp
5895 @item alpha_power, ap
5896 Specify how many times the boxblur filter is applied to the
5897 corresponding plane.
5899 Default value for @option{luma_power} is 2. If not specified,
5900 @option{chroma_power} and @option{alpha_power} default to the
5901 corresponding value set for @option{luma_power}.
5903 A value of 0 will disable the effect.
5906 @subsection Examples
5910 Apply a boxblur filter with the luma, chroma, and alpha radii
5913 boxblur=luma_radius=2:luma_power=1
5918 Set the luma radius to 2, and alpha and chroma radius to 0:
5920 boxblur=2:1:cr=0:ar=0
5924 Set the luma and chroma radii to a fraction of the video dimension:
5926 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
5932 Deinterlace the input video ("bwdif" stands for "Bob Weaver
5933 Deinterlacing Filter").
5935 Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
5936 interpolation algorithms.
5937 It accepts the following parameters:
5941 The interlacing mode to adopt. It accepts one of the following values:
5945 Output one frame for each frame.
5947 Output one frame for each field.
5950 The default value is @code{send_field}.
5953 The picture field parity assumed for the input interlaced video. It accepts one
5954 of the following values:
5958 Assume the top field is first.
5960 Assume the bottom field is first.
5962 Enable automatic detection of field parity.
5965 The default value is @code{auto}.
5966 If the interlacing is unknown or the decoder does not export this information,
5967 top field first will be assumed.
5970 Specify which frames to deinterlace. Accept one of the following
5975 Deinterlace all frames.
5977 Only deinterlace frames marked as interlaced.
5980 The default value is @code{all}.
5984 YUV colorspace color/chroma keying.
5986 The filter accepts the following options:
5990 The color which will be replaced with transparency.
5993 Similarity percentage with the key color.
5995 0.01 matches only the exact key color, while 1.0 matches everything.
6000 0.0 makes pixels either fully transparent, or not transparent at all.
6002 Higher values result in semi-transparent pixels, with a higher transparency
6003 the more similar the pixels color is to the key color.
6006 Signals that the color passed is already in YUV instead of RGB.
6008 Literal colors like "green" or "red" don't make sense with this enabled anymore.
6009 This can be used to pass exact YUV values as hexadecimal numbers.
6012 @subsection Examples
6016 Make every green pixel in the input image transparent:
6018 ffmpeg -i input.png -vf chromakey=green out.png
6022 Overlay a greenscreen-video on top of a static black background.
6024 ffmpeg -f lavfi -i color=c=black:s=1280x720 -i video.mp4 -shortest -filter_complex "[1:v]chromakey=0x70de77:0.1:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.mkv
6030 Display CIE color diagram with pixels overlaid onto it.
6032 The filter accepts the following options:
6047 @item uhdtv, rec2020
6060 Set what gamuts to draw.
6062 See @code{system} option for available values.
6065 Set ciescope size, by default set to 512.
6068 Set intensity used to map input pixel values to CIE diagram.
6071 Set contrast used to draw tongue colors that are out of active color system gamut.
6074 Correct gamma displayed on scope, by default enabled.
6077 Show white point on CIE diagram, by default disabled.
6080 Set input gamma. Used only with XYZ input color space.
6085 Visualize information exported by some codecs.
6087 Some codecs can export information through frames using side-data or other
6088 means. For example, some MPEG based codecs export motion vectors through the
6089 @var{export_mvs} flag in the codec @option{flags2} option.
6091 The filter accepts the following option:
6095 Set motion vectors to visualize.
6097 Available flags for @var{mv} are:
6101 forward predicted MVs of P-frames
6103 forward predicted MVs of B-frames
6105 backward predicted MVs of B-frames
6109 Display quantization parameters using the chroma planes.
6112 Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
6114 Available flags for @var{mv_type} are:
6118 forward predicted MVs
6120 backward predicted MVs
6123 @item frame_type, ft
6124 Set frame type to visualize motion vectors of.
6126 Available flags for @var{frame_type} are:
6130 intra-coded frames (I-frames)
6132 predicted frames (P-frames)
6134 bi-directionally predicted frames (B-frames)
6138 @subsection Examples
6142 Visualize forward predicted MVs of all frames using @command{ffplay}:
6144 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
6148 Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
6150 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
6154 @section colorbalance
6155 Modify intensity of primary colors (red, green and blue) of input frames.
6157 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
6158 regions for the red-cyan, green-magenta or blue-yellow balance.
6160 A positive adjustment value shifts the balance towards the primary color, a negative
6161 value towards the complementary color.
6163 The filter accepts the following options:
6169 Adjust red, green and blue shadows (darkest pixels).
6174 Adjust red, green and blue midtones (medium pixels).
6179 Adjust red, green and blue highlights (brightest pixels).
6181 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
6184 @subsection Examples
6188 Add red color cast to shadows:
6195 RGB colorspace color keying.
6197 The filter accepts the following options:
6201 The color which will be replaced with transparency.
6204 Similarity percentage with the key color.
6206 0.01 matches only the exact key color, while 1.0 matches everything.
6211 0.0 makes pixels either fully transparent, or not transparent at all.
6213 Higher values result in semi-transparent pixels, with a higher transparency
6214 the more similar the pixels color is to the key color.
6217 @subsection Examples
6221 Make every green pixel in the input image transparent:
6223 ffmpeg -i input.png -vf colorkey=green out.png
6227 Overlay a greenscreen-video on top of a static background image.
6229 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
6233 @section colorlevels
6235 Adjust video input frames using levels.
6237 The filter accepts the following options:
6244 Adjust red, green, blue and alpha input black point.
6245 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
6251 Adjust red, green, blue and alpha input white point.
6252 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
6254 Input levels are used to lighten highlights (bright tones), darken shadows
6255 (dark tones), change the balance of bright and dark tones.
6261 Adjust red, green, blue and alpha output black point.
6262 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
6268 Adjust red, green, blue and alpha output white point.
6269 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
6271 Output levels allows manual selection of a constrained output level range.
6274 @subsection Examples
6278 Make video output darker:
6280 colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
6286 colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
6290 Make video output lighter:
6292 colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
6296 Increase brightness:
6298 colorlevels=romin=0.5:gomin=0.5:bomin=0.5
6302 @section colorchannelmixer
6304 Adjust video input frames by re-mixing color channels.
6306 This filter modifies a color channel by adding the values associated to
6307 the other channels of the same pixels. For example if the value to
6308 modify is red, the output value will be:
6310 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
6313 The filter accepts the following options:
6320 Adjust contribution of input red, green, blue and alpha channels for output red channel.
6321 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
6327 Adjust contribution of input red, green, blue and alpha channels for output green channel.
6328 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
6334 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
6335 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
6341 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
6342 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
6344 Allowed ranges for options are @code{[-2.0, 2.0]}.
6347 @subsection Examples
6351 Convert source to grayscale:
6353 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
6356 Simulate sepia tones:
6358 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
6362 @section colormatrix
6364 Convert color matrix.
6366 The filter accepts the following options:
6371 Specify the source and destination color matrix. Both values must be
6374 The accepted values are:
6402 For example to convert from BT.601 to SMPTE-240M, use the command:
6404 colormatrix=bt601:smpte240m
6409 Convert colorspace, transfer characteristics or color primaries.
6410 Input video needs to have an even size.
6412 The filter accepts the following options:
6417 Specify all color properties at once.
6419 The accepted values are:
6449 Specify output colorspace.
6451 The accepted values are:
6460 BT.470BG or BT.601-6 625
6463 SMPTE-170M or BT.601-6 525
6472 BT.2020 with non-constant luminance
6478 Specify output transfer characteristics.
6480 The accepted values are:
6492 Constant gamma of 2.2
6495 Constant gamma of 2.8
6498 SMPTE-170M, BT.601-6 625 or BT.601-6 525
6516 BT.2020 for 10-bits content
6519 BT.2020 for 12-bits content
6525 Specify output color primaries.
6527 The accepted values are:
6536 BT.470BG or BT.601-6 625
6539 SMPTE-170M or BT.601-6 525
6563 Specify output color range.
6565 The accepted values are:
6568 TV (restricted) range
6571 MPEG (restricted) range
6582 Specify output color format.
6584 The accepted values are:
6587 YUV 4:2:0 planar 8-bits
6590 YUV 4:2:0 planar 10-bits
6593 YUV 4:2:0 planar 12-bits
6596 YUV 4:2:2 planar 8-bits
6599 YUV 4:2:2 planar 10-bits
6602 YUV 4:2:2 planar 12-bits
6605 YUV 4:4:4 planar 8-bits
6608 YUV 4:4:4 planar 10-bits
6611 YUV 4:4:4 planar 12-bits
6616 Do a fast conversion, which skips gamma/primary correction. This will take
6617 significantly less CPU, but will be mathematically incorrect. To get output
6618 compatible with that produced by the colormatrix filter, use fast=1.
6621 Specify dithering mode.
6623 The accepted values are:
6629 Floyd-Steinberg dithering
6633 Whitepoint adaptation mode.
6635 The accepted values are:
6638 Bradford whitepoint adaptation
6641 von Kries whitepoint adaptation
6644 identity whitepoint adaptation (i.e. no whitepoint adaptation)
6648 Override all input properties at once. Same accepted values as @ref{all}.
6651 Override input colorspace. Same accepted values as @ref{space}.
6654 Override input color primaries. Same accepted values as @ref{primaries}.
6657 Override input transfer characteristics. Same accepted values as @ref{trc}.
6660 Override input color range. Same accepted values as @ref{range}.
6664 The filter converts the transfer characteristics, color space and color
6665 primaries to the specified user values. The output value, if not specified,
6666 is set to a default value based on the "all" property. If that property is
6667 also not specified, the filter will log an error. The output color range and
6668 format default to the same value as the input color range and format. The
6669 input transfer characteristics, color space, color primaries and color range
6670 should be set on the input data. If any of these are missing, the filter will
6671 log an error and no conversion will take place.
6673 For example to convert the input to SMPTE-240M, use the command:
6675 colorspace=smpte240m
6678 @section convolution
6680 Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
6682 The filter accepts the following options:
6689 Set matrix for each plane.
6690 Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode,
6691 and from 1 to 49 odd number of signed integers in @var{row} mode.
6697 Set multiplier for calculated value for each plane.
6698 If unset or 0, it will be sum of all matrix elements.
6704 Set bias for each plane. This value is added to the result of the multiplication.
6705 Useful for making the overall image brighter or darker. Default is 0.0.
6711 Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}.
6712 Default is @var{square}.
6715 @subsection Examples
6721 convolution="0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0"
6727 convolution="1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9"
6733 convolution="0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128"
6739 convolution="0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128"
6743 Apply laplacian edge detector which includes diagonals:
6745 convolution="1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0"
6751 convolution="-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2"
6757 Apply 2D convolution of video stream in frequency domain using second stream
6760 The filter accepts the following options:
6764 Set which planes to process.
6767 Set which impulse video frames will be processed, can be @var{first}
6768 or @var{all}. Default is @var{all}.
6771 The @code{convolve} filter also supports the @ref{framesync} options.
6775 Copy the input video source unchanged to the output. This is mainly useful for
6780 Video filtering on GPU using Apple's CoreImage API on OSX.
6782 Hardware acceleration is based on an OpenGL context. Usually, this means it is
6783 processed by video hardware. However, software-based OpenGL implementations
6784 exist which means there is no guarantee for hardware processing. It depends on
6787 There are many filters and image generators provided by Apple that come with a
6788 large variety of options. The filter has to be referenced by its name along
6791 The coreimage filter accepts the following options:
6794 List all available filters and generators along with all their respective
6795 options as well as possible minimum and maximum values along with the default
6802 Specify all filters by their respective name and options.
6803 Use @var{list_filters} to determine all valid filter names and options.
6804 Numerical options are specified by a float value and are automatically clamped
6805 to their respective value range. Vector and color options have to be specified
6806 by a list of space separated float values. Character escaping has to be done.
6807 A special option name @code{default} is available to use default options for a
6810 It is required to specify either @code{default} or at least one of the filter options.
6811 All omitted options are used with their default values.
6812 The syntax of the filter string is as follows:
6814 filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
6818 Specify a rectangle where the output of the filter chain is copied into the
6819 input image. It is given by a list of space separated float values:
6821 output_rect=x\ y\ width\ height
6823 If not given, the output rectangle equals the dimensions of the input image.
6824 The output rectangle is automatically cropped at the borders of the input
6825 image. Negative values are valid for each component.
6827 output_rect=25\ 25\ 100\ 100
6831 Several filters can be chained for successive processing without GPU-HOST
6832 transfers allowing for fast processing of complex filter chains.
6833 Currently, only filters with zero (generators) or exactly one (filters) input
6834 image and one output image are supported. Also, transition filters are not yet
6837 Some filters generate output images with additional padding depending on the
6838 respective filter kernel. The padding is automatically removed to ensure the
6839 filter output has the same size as the input image.
6841 For image generators, the size of the output image is determined by the
6842 previous output image of the filter chain or the input image of the whole
6843 filterchain, respectively. The generators do not use the pixel information of
6844 this image to generate their output. However, the generated output is
6845 blended onto this image, resulting in partial or complete coverage of the
6848 The @ref{coreimagesrc} video source can be used for generating input images
6849 which are directly fed into the filter chain. By using it, providing input
6850 images by another video source or an input video is not required.
6852 @subsection Examples
6857 List all filters available:
6859 coreimage=list_filters=true
6863 Use the CIBoxBlur filter with default options to blur an image:
6865 coreimage=filter=CIBoxBlur@@default
6869 Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
6870 its center at 100x100 and a radius of 50 pixels:
6872 coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
6876 Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
6877 given as complete and escaped command-line for Apple's standard bash shell:
6879 ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
6885 Crop the input video to given dimensions.
6887 It accepts the following parameters:
6891 The width of the output video. It defaults to @code{iw}.
6892 This expression is evaluated only once during the filter
6893 configuration, or when the @samp{w} or @samp{out_w} command is sent.
6896 The height of the output video. It defaults to @code{ih}.
6897 This expression is evaluated only once during the filter
6898 configuration, or when the @samp{h} or @samp{out_h} command is sent.
6901 The horizontal position, in the input video, of the left edge of the output
6902 video. It defaults to @code{(in_w-out_w)/2}.
6903 This expression is evaluated per-frame.
6906 The vertical position, in the input video, of the top edge of the output video.
6907 It defaults to @code{(in_h-out_h)/2}.
6908 This expression is evaluated per-frame.
6911 If set to 1 will force the output display aspect ratio
6912 to be the same of the input, by changing the output sample aspect
6913 ratio. It defaults to 0.
6916 Enable exact cropping. If enabled, subsampled videos will be cropped at exact
6917 width/height/x/y as specified and will not be rounded to nearest smaller value.
6921 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
6922 expressions containing the following constants:
6927 The computed values for @var{x} and @var{y}. They are evaluated for
6932 The input width and height.
6936 These are the same as @var{in_w} and @var{in_h}.
6940 The output (cropped) width and height.
6944 These are the same as @var{out_w} and @var{out_h}.
6947 same as @var{iw} / @var{ih}
6950 input sample aspect ratio
6953 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
6957 horizontal and vertical chroma subsample values. For example for the
6958 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
6961 The number of the input frame, starting from 0.
6964 the position in the file of the input frame, NAN if unknown
6967 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
6971 The expression for @var{out_w} may depend on the value of @var{out_h},
6972 and the expression for @var{out_h} may depend on @var{out_w}, but they
6973 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
6974 evaluated after @var{out_w} and @var{out_h}.
6976 The @var{x} and @var{y} parameters specify the expressions for the
6977 position of the top-left corner of the output (non-cropped) area. They
6978 are evaluated for each frame. If the evaluated value is not valid, it
6979 is approximated to the nearest valid value.
6981 The expression for @var{x} may depend on @var{y}, and the expression
6982 for @var{y} may depend on @var{x}.
6984 @subsection Examples
6988 Crop area with size 100x100 at position (12,34).
6993 Using named options, the example above becomes:
6995 crop=w=100:h=100:x=12:y=34
6999 Crop the central input area with size 100x100:
7005 Crop the central input area with size 2/3 of the input video:
7007 crop=2/3*in_w:2/3*in_h
7011 Crop the input video central square:
7018 Delimit the rectangle with the top-left corner placed at position
7019 100:100 and the right-bottom corner corresponding to the right-bottom
7020 corner of the input image.
7022 crop=in_w-100:in_h-100:100:100
7026 Crop 10 pixels from the left and right borders, and 20 pixels from
7027 the top and bottom borders
7029 crop=in_w-2*10:in_h-2*20
7033 Keep only the bottom right quarter of the input image:
7035 crop=in_w/2:in_h/2:in_w/2:in_h/2
7039 Crop height for getting Greek harmony:
7041 crop=in_w:1/PHI*in_w
7045 Apply trembling effect:
7047 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)
7051 Apply erratic camera effect depending on timestamp:
7053 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)"
7057 Set x depending on the value of y:
7059 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
7063 @subsection Commands
7065 This filter supports the following commands:
7071 Set width/height of the output video and the horizontal/vertical position
7073 The command accepts the same syntax of the corresponding option.
7075 If the specified expression is not valid, it is kept at its current
7081 Auto-detect the crop size.
7083 It calculates the necessary cropping parameters and prints the
7084 recommended parameters via the logging system. The detected dimensions
7085 correspond to the non-black area of the input video.
7087 It accepts the following parameters:
7092 Set higher black value threshold, which can be optionally specified
7093 from nothing (0) to everything (255 for 8-bit based formats). An intensity
7094 value greater to the set value is considered non-black. It defaults to 24.
7095 You can also specify a value between 0.0 and 1.0 which will be scaled depending
7096 on the bitdepth of the pixel format.
7099 The value which the width/height should be divisible by. It defaults to
7100 16. The offset is automatically adjusted to center the video. Use 2 to
7101 get only even dimensions (needed for 4:2:2 video). 16 is best when
7102 encoding to most video codecs.
7104 @item reset_count, reset
7105 Set the counter that determines after how many frames cropdetect will
7106 reset the previously detected largest video area and start over to
7107 detect the current optimal crop area. Default value is 0.
7109 This can be useful when channel logos distort the video area. 0
7110 indicates 'never reset', and returns the largest area encountered during
7117 Delay video filtering until a given wallclock timestamp. The filter first
7118 passes on @option{preroll} amount of frames, then it buffers at most
7119 @option{buffer} amount of frames and waits for the cue. After reaching the cue
7120 it forwards the buffered frames and also any subsequent frames coming in its
7123 The filter can be used synchronize the output of multiple ffmpeg processes for
7124 realtime output devices like decklink. By putting the delay in the filtering
7125 chain and pre-buffering frames the process can pass on data to output almost
7126 immediately after the target wallclock timestamp is reached.
7128 Perfect frame accuracy cannot be guaranteed, but the result is good enough for
7134 The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0.
7137 The duration of content to pass on as preroll expressed in seconds. Default is 0.
7140 The maximum duration of content to buffer before waiting for the cue expressed
7141 in seconds. Default is 0.
7148 Apply color adjustments using curves.
7150 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
7151 component (red, green and blue) has its values defined by @var{N} key points
7152 tied from each other using a smooth curve. The x-axis represents the pixel
7153 values from the input frame, and the y-axis the new pixel values to be set for
7156 By default, a component curve is defined by the two points @var{(0;0)} and
7157 @var{(1;1)}. This creates a straight line where each original pixel value is
7158 "adjusted" to its own value, which means no change to the image.
7160 The filter allows you to redefine these two points and add some more. A new
7161 curve (using a natural cubic spline interpolation) will be define to pass
7162 smoothly through all these new coordinates. The new defined points needs to be
7163 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
7164 be in the @var{[0;1]} interval. If the computed curves happened to go outside
7165 the vector spaces, the values will be clipped accordingly.
7167 The filter accepts the following options:
7171 Select one of the available color presets. This option can be used in addition
7172 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
7173 options takes priority on the preset values.
7174 Available presets are:
7177 @item color_negative
7180 @item increase_contrast
7182 @item linear_contrast
7183 @item medium_contrast
7185 @item strong_contrast
7188 Default is @code{none}.
7190 Set the master key points. These points will define a second pass mapping. It
7191 is sometimes called a "luminance" or "value" mapping. It can be used with
7192 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
7193 post-processing LUT.
7195 Set the key points for the red component.
7197 Set the key points for the green component.
7199 Set the key points for the blue component.
7201 Set the key points for all components (not including master).
7202 Can be used in addition to the other key points component
7203 options. In this case, the unset component(s) will fallback on this
7204 @option{all} setting.
7206 Specify a Photoshop curves file (@code{.acv}) to import the settings from.
7208 Save Gnuplot script of the curves in specified file.
7211 To avoid some filtergraph syntax conflicts, each key points list need to be
7212 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
7214 @subsection Examples
7218 Increase slightly the middle level of blue:
7220 curves=blue='0/0 0.5/0.58 1/1'
7226 curves=r='0/0.11 .42/.51 1/0.95':g='0/0 0.50/0.48 1/1':b='0/0.22 .49/.44 1/0.8'
7228 Here we obtain the following coordinates for each components:
7231 @code{(0;0.11) (0.42;0.51) (1;0.95)}
7233 @code{(0;0) (0.50;0.48) (1;1)}
7235 @code{(0;0.22) (0.49;0.44) (1;0.80)}
7239 The previous example can also be achieved with the associated built-in preset:
7241 curves=preset=vintage
7251 Use a Photoshop preset and redefine the points of the green component:
7253 curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
7257 Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
7258 and @command{gnuplot}:
7260 ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
7261 gnuplot -p /tmp/curves.plt
7267 Video data analysis filter.
7269 This filter shows hexadecimal pixel values of part of video.
7271 The filter accepts the following options:
7275 Set output video size.
7278 Set x offset from where to pick pixels.
7281 Set y offset from where to pick pixels.
7284 Set scope mode, can be one of the following:
7287 Draw hexadecimal pixel values with white color on black background.
7290 Draw hexadecimal pixel values with input video pixel color on black
7294 Draw hexadecimal pixel values on color background picked from input video,
7295 the text color is picked in such way so its always visible.
7299 Draw rows and columns numbers on left and top of video.
7302 Set background opacity.
7307 Denoise frames using 2D DCT (frequency domain filtering).
7309 This filter is not designed for real time.
7311 The filter accepts the following options:
7315 Set the noise sigma constant.
7317 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
7318 coefficient (absolute value) below this threshold with be dropped.
7320 If you need a more advanced filtering, see @option{expr}.
7322 Default is @code{0}.
7325 Set number overlapping pixels for each block. Since the filter can be slow, you
7326 may want to reduce this value, at the cost of a less effective filter and the
7327 risk of various artefacts.
7329 If the overlapping value doesn't permit processing the whole input width or
7330 height, a warning will be displayed and according borders won't be denoised.
7332 Default value is @var{blocksize}-1, which is the best possible setting.
7335 Set the coefficient factor expression.
7337 For each coefficient of a DCT block, this expression will be evaluated as a
7338 multiplier value for the coefficient.
7340 If this is option is set, the @option{sigma} option will be ignored.
7342 The absolute value of the coefficient can be accessed through the @var{c}
7346 Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
7347 @var{blocksize}, which is the width and height of the processed blocks.
7349 The default value is @var{3} (8x8) and can be raised to @var{4} for a
7350 @var{blocksize} of 16x16. Note that changing this setting has huge consequences
7351 on the speed processing. Also, a larger block size does not necessarily means a
7355 @subsection Examples
7357 Apply a denoise with a @option{sigma} of @code{4.5}:
7362 The same operation can be achieved using the expression system:
7364 dctdnoiz=e='gte(c, 4.5*3)'
7367 Violent denoise using a block size of @code{16x16}:
7374 Remove banding artifacts from input video.
7375 It works by replacing banded pixels with average value of referenced pixels.
7377 The filter accepts the following options:
7384 Set banding detection threshold for each plane. Default is 0.02.
7385 Valid range is 0.00003 to 0.5.
7386 If difference between current pixel and reference pixel is less than threshold,
7387 it will be considered as banded.
7390 Banding detection range in pixels. Default is 16. If positive, random number
7391 in range 0 to set value will be used. If negative, exact absolute value
7393 The range defines square of four pixels around current pixel.
7396 Set direction in radians from which four pixel will be compared. If positive,
7397 random direction from 0 to set direction will be picked. If negative, exact of
7398 absolute value will be picked. For example direction 0, -PI or -2*PI radians
7399 will pick only pixels on same row and -PI/2 will pick only pixels on same
7403 If enabled, current pixel is compared with average value of all four
7404 surrounding pixels. The default is enabled. If disabled current pixel is
7405 compared with all four surrounding pixels. The pixel is considered banded
7406 if only all four differences with surrounding pixels are less than threshold.
7409 If enabled, current pixel is changed if and only if all pixel components are banded,
7410 e.g. banding detection threshold is triggered for all color components.
7411 The default is disabled.
7416 Remove blocking artifacts from input video.
7418 The filter accepts the following options:
7422 Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}.
7423 This controls what kind of deblocking is applied.
7426 Set size of block, allowed range is from 4 to 512. Default is @var{8}.
7432 Set blocking detection thresholds. Allowed range is 0 to 1.
7433 Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest.
7434 Using higher threshold gives more deblocking strength.
7435 Setting @var{alpha} controls threshold detection at exact edge of block.
7436 Remaining options controls threshold detection near the edge. Each one for
7437 below/above or left/right. Setting any of those to @var{0} disables
7441 Set planes to filter. Default is to filter all available planes.
7444 @subsection Examples
7448 Deblock using weak filter and block size of 4 pixels.
7450 deblock=filter=weak:block=4
7454 Deblock using strong filter, block size of 4 pixels and custom thresholds for
7455 deblocking more edges.
7457 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
7461 Similar as above, but filter only first plane.
7463 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
7467 Similar as above, but filter only second and third plane.
7469 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
7476 Drop duplicated frames at regular intervals.
7478 The filter accepts the following options:
7482 Set the number of frames from which one will be dropped. Setting this to
7483 @var{N} means one frame in every batch of @var{N} frames will be dropped.
7484 Default is @code{5}.
7487 Set the threshold for duplicate detection. If the difference metric for a frame
7488 is less than or equal to this value, then it is declared as duplicate. Default
7492 Set scene change threshold. Default is @code{15}.
7496 Set the size of the x and y-axis blocks used during metric calculations.
7497 Larger blocks give better noise suppression, but also give worse detection of
7498 small movements. Must be a power of two. Default is @code{32}.
7501 Mark main input as a pre-processed input and activate clean source input
7502 stream. This allows the input to be pre-processed with various filters to help
7503 the metrics calculation while keeping the frame selection lossless. When set to
7504 @code{1}, the first stream is for the pre-processed input, and the second
7505 stream is the clean source from where the kept frames are chosen. Default is
7509 Set whether or not chroma is considered in the metric calculations. Default is
7515 Apply 2D deconvolution of video stream in frequency domain using second stream
7518 The filter accepts the following options:
7522 Set which planes to process.
7525 Set which impulse video frames will be processed, can be @var{first}
7526 or @var{all}. Default is @var{all}.
7529 Set noise when doing divisions. Default is @var{0.0000001}. Useful when width
7530 and height are not same and not power of 2 or if stream prior to convolving
7534 The @code{deconvolve} filter also supports the @ref{framesync} options.
7538 Apply deflate effect to the video.
7540 This filter replaces the pixel by the local(3x3) average by taking into account
7541 only values lower than the pixel.
7543 It accepts the following options:
7550 Limit the maximum change for each plane, default is 65535.
7551 If 0, plane will remain unchanged.
7556 Remove temporal frame luminance variations.
7558 It accepts the following options:
7562 Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129.
7565 Set averaging mode to smooth temporal luminance variations.
7567 Available values are:
7592 Do not actually modify frame. Useful when one only wants metadata.
7597 Remove judder produced by partially interlaced telecined content.
7599 Judder can be introduced, for instance, by @ref{pullup} filter. If the original
7600 source was partially telecined content then the output of @code{pullup,dejudder}
7601 will have a variable frame rate. May change the recorded frame rate of the
7602 container. Aside from that change, this filter will not affect constant frame
7605 The option available in this filter is:
7609 Specify the length of the window over which the judder repeats.
7611 Accepts any integer greater than 1. Useful values are:
7615 If the original was telecined from 24 to 30 fps (Film to NTSC).
7618 If the original was telecined from 25 to 30 fps (PAL to NTSC).
7621 If a mixture of the two.
7624 The default is @samp{4}.
7629 Suppress a TV station logo by a simple interpolation of the surrounding
7630 pixels. Just set a rectangle covering the logo and watch it disappear
7631 (and sometimes something even uglier appear - your mileage may vary).
7633 It accepts the following parameters:
7638 Specify the top left corner coordinates of the logo. They must be
7643 Specify the width and height of the logo to clear. They must be
7647 Specify the thickness of the fuzzy edge of the rectangle (added to
7648 @var{w} and @var{h}). The default value is 1. This option is
7649 deprecated, setting higher values should no longer be necessary and
7653 When set to 1, a green rectangle is drawn on the screen to simplify
7654 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
7655 The default value is 0.
7657 The rectangle is drawn on the outermost pixels which will be (partly)
7658 replaced with interpolated values. The values of the next pixels
7659 immediately outside this rectangle in each direction will be used to
7660 compute the interpolated pixel values inside the rectangle.
7664 @subsection Examples
7668 Set a rectangle covering the area with top left corner coordinates 0,0
7669 and size 100x77, and a band of size 10:
7671 delogo=x=0:y=0:w=100:h=77:band=10
7678 Attempt to fix small changes in horizontal and/or vertical shift. This
7679 filter helps remove camera shake from hand-holding a camera, bumping a
7680 tripod, moving on a vehicle, etc.
7682 The filter accepts the following options:
7690 Specify a rectangular area where to limit the search for motion
7692 If desired the search for motion vectors can be limited to a
7693 rectangular area of the frame defined by its top left corner, width
7694 and height. These parameters have the same meaning as the drawbox
7695 filter which can be used to visualise the position of the bounding
7698 This is useful when simultaneous movement of subjects within the frame
7699 might be confused for camera motion by the motion vector search.
7701 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
7702 then the full frame is used. This allows later options to be set
7703 without specifying the bounding box for the motion vector search.
7705 Default - search the whole frame.
7709 Specify the maximum extent of movement in x and y directions in the
7710 range 0-64 pixels. Default 16.
7713 Specify how to generate pixels to fill blanks at the edge of the
7714 frame. Available values are:
7717 Fill zeroes at blank locations
7719 Original image at blank locations
7721 Extruded edge value at blank locations
7723 Mirrored edge at blank locations
7725 Default value is @samp{mirror}.
7728 Specify the blocksize to use for motion search. Range 4-128 pixels,
7732 Specify the contrast threshold for blocks. Only blocks with more than
7733 the specified contrast (difference between darkest and lightest
7734 pixels) will be considered. Range 1-255, default 125.
7737 Specify the search strategy. Available values are:
7740 Set exhaustive search
7742 Set less exhaustive search.
7744 Default value is @samp{exhaustive}.
7747 If set then a detailed log of the motion search is written to the
7754 Remove unwanted contamination of foreground colors, caused by reflected color of
7755 greenscreen or bluescreen.
7757 This filter accepts the following options:
7761 Set what type of despill to use.
7764 Set how spillmap will be generated.
7767 Set how much to get rid of still remaining spill.
7770 Controls amount of red in spill area.
7773 Controls amount of green in spill area.
7774 Should be -1 for greenscreen.
7777 Controls amount of blue in spill area.
7778 Should be -1 for bluescreen.
7781 Controls brightness of spill area, preserving colors.
7784 Modify alpha from generated spillmap.
7789 Apply an exact inverse of the telecine operation. It requires a predefined
7790 pattern specified using the pattern option which must be the same as that passed
7791 to the telecine filter.
7793 This filter accepts the following options:
7802 The default value is @code{top}.
7806 A string of numbers representing the pulldown pattern you wish to apply.
7807 The default value is @code{23}.
7810 A number representing position of the first frame with respect to the telecine
7811 pattern. This is to be used if the stream is cut. The default value is @code{0}.
7816 Apply dilation effect to the video.
7818 This filter replaces the pixel by the local(3x3) maximum.
7820 It accepts the following options:
7827 Limit the maximum change for each plane, default is 65535.
7828 If 0, plane will remain unchanged.
7831 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
7834 Flags to local 3x3 coordinates maps like this:
7843 Displace pixels as indicated by second and third input stream.
7845 It takes three input streams and outputs one stream, the first input is the
7846 source, and second and third input are displacement maps.
7848 The second input specifies how much to displace pixels along the
7849 x-axis, while the third input specifies how much to displace pixels
7851 If one of displacement map streams terminates, last frame from that
7852 displacement map will be used.
7854 Note that once generated, displacements maps can be reused over and over again.
7856 A description of the accepted options follows.
7860 Set displace behavior for pixels that are out of range.
7862 Available values are:
7865 Missing pixels are replaced by black pixels.
7868 Adjacent pixels will spread out to replace missing pixels.
7871 Out of range pixels are wrapped so they point to pixels of other side.
7874 Out of range pixels will be replaced with mirrored pixels.
7876 Default is @samp{smear}.
7880 @subsection Examples
7884 Add ripple effect to rgb input of video size hd720:
7886 ffmpeg -i INPUT -f lavfi -i nullsrc=s=hd720,lutrgb=128:128:128 -f lavfi -i nullsrc=s=hd720,geq='r=128+30*sin(2*PI*X/400+T):g=128+30*sin(2*PI*X/400+T):b=128+30*sin(2*PI*X/400+T)' -lavfi '[0][1][2]displace' OUTPUT
7890 Add wave effect to rgb input of video size hd720:
7892 ffmpeg -i INPUT -f lavfi -i nullsrc=hd720,geq='r=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):g=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):b=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T))' -lavfi '[1]split[x][y],[0][x][y]displace' OUTPUT
7898 Draw a colored box on the input image.
7900 It accepts the following parameters:
7905 The expressions which specify the top left corner coordinates of the box. It defaults to 0.
7909 The expressions which specify the width and height of the box; if 0 they are interpreted as
7910 the input width and height. It defaults to 0.
7913 Specify the color of the box to write. For the general syntax of this option,
7914 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
7915 value @code{invert} is used, the box edge color is the same as the
7916 video with inverted luma.
7919 The expression which sets the thickness of the box edge.
7920 A value of @code{fill} will create a filled box. Default value is @code{3}.
7922 See below for the list of accepted constants.
7925 Applicable if the input has alpha. With value @code{1}, the pixels of the painted box
7926 will overwrite the video's color and alpha pixels.
7927 Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact.
7930 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
7931 following constants:
7935 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
7939 horizontal and vertical chroma subsample values. For example for the
7940 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
7944 The input width and height.
7947 The input sample aspect ratio.
7951 The x and y offset coordinates where the box is drawn.
7955 The width and height of the drawn box.
7958 The thickness of the drawn box.
7960 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
7961 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
7965 @subsection Examples
7969 Draw a black box around the edge of the input image:
7975 Draw a box with color red and an opacity of 50%:
7977 drawbox=10:20:200:60:red@@0.5
7980 The previous example can be specified as:
7982 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
7986 Fill the box with pink color:
7988 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill
7992 Draw a 2-pixel red 2.40:1 mask:
7994 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
8000 Draw a grid on the input image.
8002 It accepts the following parameters:
8007 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
8011 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
8012 input width and height, respectively, minus @code{thickness}, so image gets
8013 framed. Default to 0.
8016 Specify the color of the grid. For the general syntax of this option,
8017 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
8018 value @code{invert} is used, the grid color is the same as the
8019 video with inverted luma.
8022 The expression which sets the thickness of the grid line. Default value is @code{1}.
8024 See below for the list of accepted constants.
8027 Applicable if the input has alpha. With @code{1} the pixels of the painted grid
8028 will overwrite the video's color and alpha pixels.
8029 Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact.
8032 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
8033 following constants:
8037 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
8041 horizontal and vertical chroma subsample values. For example for the
8042 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8046 The input grid cell width and height.
8049 The input sample aspect ratio.
8053 The x and y coordinates of some point of grid intersection (meant to configure offset).
8057 The width and height of the drawn cell.
8060 The thickness of the drawn cell.
8062 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
8063 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
8067 @subsection Examples
8071 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
8073 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
8077 Draw a white 3x3 grid with an opacity of 50%:
8079 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
8086 Draw a text string or text from a specified file on top of a video, using the
8087 libfreetype library.
8089 To enable compilation of this filter, you need to configure FFmpeg with
8090 @code{--enable-libfreetype}.
8091 To enable default font fallback and the @var{font} option you need to
8092 configure FFmpeg with @code{--enable-libfontconfig}.
8093 To enable the @var{text_shaping} option, you need to configure FFmpeg with
8094 @code{--enable-libfribidi}.
8098 It accepts the following parameters:
8103 Used to draw a box around text using the background color.
8104 The value must be either 1 (enable) or 0 (disable).
8105 The default value of @var{box} is 0.
8108 Set the width of the border to be drawn around the box using @var{boxcolor}.
8109 The default value of @var{boxborderw} is 0.
8112 The color to be used for drawing box around text. For the syntax of this
8113 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
8115 The default value of @var{boxcolor} is "white".
8118 Set the line spacing in pixels of the border to be drawn around the box using @var{box}.
8119 The default value of @var{line_spacing} is 0.
8122 Set the width of the border to be drawn around the text using @var{bordercolor}.
8123 The default value of @var{borderw} is 0.
8126 Set the color to be used for drawing border around text. For the syntax of this
8127 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
8129 The default value of @var{bordercolor} is "black".
8132 Select how the @var{text} is expanded. Can be either @code{none},
8133 @code{strftime} (deprecated) or
8134 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
8138 Set a start time for the count. Value is in microseconds. Only applied
8139 in the deprecated strftime expansion mode. To emulate in normal expansion
8140 mode use the @code{pts} function, supplying the start time (in seconds)
8141 as the second argument.
8144 If true, check and fix text coords to avoid clipping.
8147 The color to be used for drawing fonts. For the syntax of this option, check
8148 the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
8150 The default value of @var{fontcolor} is "black".
8152 @item fontcolor_expr
8153 String which is expanded the same way as @var{text} to obtain dynamic
8154 @var{fontcolor} value. By default this option has empty value and is not
8155 processed. When this option is set, it overrides @var{fontcolor} option.
8158 The font family to be used for drawing text. By default Sans.
8161 The font file to be used for drawing text. The path must be included.
8162 This parameter is mandatory if the fontconfig support is disabled.
8165 Draw the text applying alpha blending. The value can
8166 be a number between 0.0 and 1.0.
8167 The expression accepts the same variables @var{x, y} as well.
8168 The default value is 1.
8169 Please see @var{fontcolor_expr}.
8172 The font size to be used for drawing text.
8173 The default value of @var{fontsize} is 16.
8176 If set to 1, attempt to shape the text (for example, reverse the order of
8177 right-to-left text and join Arabic characters) before drawing it.
8178 Otherwise, just draw the text exactly as given.
8179 By default 1 (if supported).
8182 The flags to be used for loading the fonts.
8184 The flags map the corresponding flags supported by libfreetype, and are
8185 a combination of the following values:
8192 @item vertical_layout
8193 @item force_autohint
8196 @item ignore_global_advance_width
8198 @item ignore_transform
8204 Default value is "default".
8206 For more information consult the documentation for the FT_LOAD_*
8210 The color to be used for drawing a shadow behind the drawn text. For the
8211 syntax of this option, check the @ref{color syntax,,"Color" section in the
8212 ffmpeg-utils manual,ffmpeg-utils}.
8214 The default value of @var{shadowcolor} is "black".
8218 The x and y offsets for the text shadow position with respect to the
8219 position of the text. They can be either positive or negative
8220 values. The default value for both is "0".
8223 The starting frame number for the n/frame_num variable. The default value
8227 The size in number of spaces to use for rendering the tab.
8231 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
8232 format. It can be used with or without text parameter. @var{timecode_rate}
8233 option must be specified.
8235 @item timecode_rate, rate, r
8236 Set the timecode frame rate (timecode only). Value will be rounded to nearest
8237 integer. Minimum value is "1".
8238 Drop-frame timecode is supported for frame rates 30 & 60.
8241 If set to 1, the output of the timecode option will wrap around at 24 hours.
8242 Default is 0 (disabled).
8245 The text string to be drawn. The text must be a sequence of UTF-8
8247 This parameter is mandatory if no file is specified with the parameter
8251 A text file containing text to be drawn. The text must be a sequence
8252 of UTF-8 encoded characters.
8254 This parameter is mandatory if no text string is specified with the
8255 parameter @var{text}.
8257 If both @var{text} and @var{textfile} are specified, an error is thrown.
8260 If set to 1, the @var{textfile} will be reloaded before each frame.
8261 Be sure to update it atomically, or it may be read partially, or even fail.
8265 The expressions which specify the offsets where text will be drawn
8266 within the video frame. They are relative to the top/left border of the
8269 The default value of @var{x} and @var{y} is "0".
8271 See below for the list of accepted constants and functions.
8274 The parameters for @var{x} and @var{y} are expressions containing the
8275 following constants and functions:
8279 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
8283 horizontal and vertical chroma subsample values. For example for the
8284 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8287 the height of each text line
8295 @item max_glyph_a, ascent
8296 the maximum distance from the baseline to the highest/upper grid
8297 coordinate used to place a glyph outline point, for all the rendered
8299 It is a positive value, due to the grid's orientation with the Y axis
8302 @item max_glyph_d, descent
8303 the maximum distance from the baseline to the lowest grid coordinate
8304 used to place a glyph outline point, for all the rendered glyphs.
8305 This is a negative value, due to the grid's orientation, with the Y axis
8309 maximum glyph height, that is the maximum height for all the glyphs
8310 contained in the rendered text, it is equivalent to @var{ascent} -
8314 maximum glyph width, that is the maximum width for all the glyphs
8315 contained in the rendered text
8318 the number of input frame, starting from 0
8320 @item rand(min, max)
8321 return a random number included between @var{min} and @var{max}
8324 The input sample aspect ratio.
8327 timestamp expressed in seconds, NAN if the input timestamp is unknown
8330 the height of the rendered text
8333 the width of the rendered text
8337 the x and y offset coordinates where the text is drawn.
8339 These parameters allow the @var{x} and @var{y} expressions to refer
8340 each other, so you can for example specify @code{y=x/dar}.
8343 @anchor{drawtext_expansion}
8344 @subsection Text expansion
8346 If @option{expansion} is set to @code{strftime},
8347 the filter recognizes strftime() sequences in the provided text and
8348 expands them accordingly. Check the documentation of strftime(). This
8349 feature is deprecated.
8351 If @option{expansion} is set to @code{none}, the text is printed verbatim.
8353 If @option{expansion} is set to @code{normal} (which is the default),
8354 the following expansion mechanism is used.
8356 The backslash character @samp{\}, followed by any character, always expands to
8357 the second character.
8359 Sequences of the form @code{%@{...@}} are expanded. The text between the
8360 braces is a function name, possibly followed by arguments separated by ':'.
8361 If the arguments contain special characters or delimiters (':' or '@}'),
8362 they should be escaped.
8364 Note that they probably must also be escaped as the value for the
8365 @option{text} option in the filter argument string and as the filter
8366 argument in the filtergraph description, and possibly also for the shell,
8367 that makes up to four levels of escaping; using a text file avoids these
8370 The following functions are available:
8375 The expression evaluation result.
8377 It must take one argument specifying the expression to be evaluated,
8378 which accepts the same constants and functions as the @var{x} and
8379 @var{y} values. Note that not all constants should be used, for
8380 example the text size is not known when evaluating the expression, so
8381 the constants @var{text_w} and @var{text_h} will have an undefined
8384 @item expr_int_format, eif
8385 Evaluate the expression's value and output as formatted integer.
8387 The first argument is the expression to be evaluated, just as for the @var{expr} function.
8388 The second argument specifies the output format. Allowed values are @samp{x},
8389 @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
8390 @code{printf} function.
8391 The third parameter is optional and sets the number of positions taken by the output.
8392 It can be used to add padding with zeros from the left.
8395 The time at which the filter is running, expressed in UTC.
8396 It can accept an argument: a strftime() format string.
8399 The time at which the filter is running, expressed in the local time zone.
8400 It can accept an argument: a strftime() format string.
8403 Frame metadata. Takes one or two arguments.
8405 The first argument is mandatory and specifies the metadata key.
8407 The second argument is optional and specifies a default value, used when the
8408 metadata key is not found or empty.
8411 The frame number, starting from 0.
8414 A 1 character description of the current picture type.
8417 The timestamp of the current frame.
8418 It can take up to three arguments.
8420 The first argument is the format of the timestamp; it defaults to @code{flt}
8421 for seconds as a decimal number with microsecond accuracy; @code{hms} stands
8422 for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
8423 @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
8424 @code{localtime} stands for the timestamp of the frame formatted as
8425 local time zone time.
8427 The second argument is an offset added to the timestamp.
8429 If the format is set to @code{hms}, a third argument @code{24HH} may be
8430 supplied to present the hour part of the formatted timestamp in 24h format
8433 If the format is set to @code{localtime} or @code{gmtime},
8434 a third argument may be supplied: a strftime() format string.
8435 By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
8438 @subsection Examples
8442 Draw "Test Text" with font FreeSerif, using the default values for the
8443 optional parameters.
8446 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
8450 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
8451 and y=50 (counting from the top-left corner of the screen), text is
8452 yellow with a red box around it. Both the text and the box have an
8456 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
8457 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
8460 Note that the double quotes are not necessary if spaces are not used
8461 within the parameter list.
8464 Show the text at the center of the video frame:
8466 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
8470 Show the text at a random position, switching to a new position every 30 seconds:
8472 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=if(eq(mod(t\,30)\,0)\,rand(0\,(w-text_w))\,x):y=if(eq(mod(t\,30)\,0)\,rand(0\,(h-text_h))\,y)"
8476 Show a text line sliding from right to left in the last row of the video
8477 frame. The file @file{LONG_LINE} is assumed to contain a single line
8480 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
8484 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
8486 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
8490 Draw a single green letter "g", at the center of the input video.
8491 The glyph baseline is placed at half screen height.
8493 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
8497 Show text for 1 second every 3 seconds:
8499 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
8503 Use fontconfig to set the font. Note that the colons need to be escaped.
8505 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
8509 Print the date of a real-time encoding (see strftime(3)):
8511 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
8515 Show text fading in and out (appearing/disappearing):
8518 DS=1.0 # display start
8519 DE=10.0 # display end
8520 FID=1.5 # fade in duration
8521 FOD=5 # fade out duration
8522 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 @}"
8526 Horizontally align multiple separate texts. Note that @option{max_glyph_a}
8527 and the @option{fontsize} value are included in the @option{y} offset.
8529 drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
8530 drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
8535 For more information about libfreetype, check:
8536 @url{http://www.freetype.org/}.
8538 For more information about fontconfig, check:
8539 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
8541 For more information about libfribidi, check:
8542 @url{http://fribidi.org/}.
8546 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
8548 The filter accepts the following options:
8553 Set low and high threshold values used by the Canny thresholding
8556 The high threshold selects the "strong" edge pixels, which are then
8557 connected through 8-connectivity with the "weak" edge pixels selected
8558 by the low threshold.
8560 @var{low} and @var{high} threshold values must be chosen in the range
8561 [0,1], and @var{low} should be lesser or equal to @var{high}.
8563 Default value for @var{low} is @code{20/255}, and default value for @var{high}
8567 Define the drawing mode.
8571 Draw white/gray wires on black background.
8574 Mix the colors to create a paint/cartoon effect.
8577 Apply Canny edge detector on all selected planes.
8579 Default value is @var{wires}.
8582 Select planes for filtering. By default all available planes are filtered.
8585 @subsection Examples
8589 Standard edge detection with custom values for the hysteresis thresholding:
8591 edgedetect=low=0.1:high=0.4
8595 Painting effect without thresholding:
8597 edgedetect=mode=colormix:high=0
8602 Set brightness, contrast, saturation and approximate gamma adjustment.
8604 The filter accepts the following options:
8608 Set the contrast expression. The value must be a float value in range
8609 @code{-2.0} to @code{2.0}. The default value is "1".
8612 Set the brightness expression. The value must be a float value in
8613 range @code{-1.0} to @code{1.0}. The default value is "0".
8616 Set the saturation expression. The value must be a float in
8617 range @code{0.0} to @code{3.0}. The default value is "1".
8620 Set the gamma expression. The value must be a float in range
8621 @code{0.1} to @code{10.0}. The default value is "1".
8624 Set the gamma expression for red. The value must be a float in
8625 range @code{0.1} to @code{10.0}. The default value is "1".
8628 Set the gamma expression for green. The value must be a float in range
8629 @code{0.1} to @code{10.0}. The default value is "1".
8632 Set the gamma expression for blue. The value must be a float in range
8633 @code{0.1} to @code{10.0}. The default value is "1".
8636 Set the gamma weight expression. It can be used to reduce the effect
8637 of a high gamma value on bright image areas, e.g. keep them from
8638 getting overamplified and just plain white. The value must be a float
8639 in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
8640 gamma correction all the way down while @code{1.0} leaves it at its
8641 full strength. Default is "1".
8644 Set when the expressions for brightness, contrast, saturation and
8645 gamma expressions are evaluated.
8647 It accepts the following values:
8650 only evaluate expressions once during the filter initialization or
8651 when a command is processed
8654 evaluate expressions for each incoming frame
8657 Default value is @samp{init}.
8660 The expressions accept the following parameters:
8663 frame count of the input frame starting from 0
8666 byte position of the corresponding packet in the input file, NAN if
8670 frame rate of the input video, NAN if the input frame rate is unknown
8673 timestamp expressed in seconds, NAN if the input timestamp is unknown
8676 @subsection Commands
8677 The filter supports the following commands:
8681 Set the contrast expression.
8684 Set the brightness expression.
8687 Set the saturation expression.
8690 Set the gamma expression.
8693 Set the gamma_r expression.
8696 Set gamma_g expression.
8699 Set gamma_b expression.
8702 Set gamma_weight expression.
8704 The command accepts the same syntax of the corresponding option.
8706 If the specified expression is not valid, it is kept at its current
8713 Apply erosion effect to the video.
8715 This filter replaces the pixel by the local(3x3) minimum.
8717 It accepts the following options:
8724 Limit the maximum change for each plane, default is 65535.
8725 If 0, plane will remain unchanged.
8728 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
8731 Flags to local 3x3 coordinates maps like this:
8738 @section extractplanes
8740 Extract color channel components from input video stream into
8741 separate grayscale video streams.
8743 The filter accepts the following option:
8747 Set plane(s) to extract.
8749 Available values for planes are:
8760 Choosing planes not available in the input will result in an error.
8761 That means you cannot select @code{r}, @code{g}, @code{b} planes
8762 with @code{y}, @code{u}, @code{v} planes at same time.
8765 @subsection Examples
8769 Extract luma, u and v color channel component from input video frame
8770 into 3 grayscale outputs:
8772 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
8778 Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
8780 For each input image, the filter will compute the optimal mapping from
8781 the input to the output given the codebook length, that is the number
8782 of distinct output colors.
8784 This filter accepts the following options.
8787 @item codebook_length, l
8788 Set codebook length. The value must be a positive integer, and
8789 represents the number of distinct output colors. Default value is 256.
8792 Set the maximum number of iterations to apply for computing the optimal
8793 mapping. The higher the value the better the result and the higher the
8794 computation time. Default value is 1.
8797 Set a random seed, must be an integer included between 0 and
8798 UINT32_MAX. If not specified, or if explicitly set to -1, the filter
8799 will try to use a good random seed on a best effort basis.
8802 Set pal8 output pixel format. This option does not work with codebook
8803 length greater than 256.
8808 Measure graylevel entropy in histogram of color channels of video frames.
8810 It accepts the following parameters:
8814 Can be either @var{normal} or @var{diff}. Default is @var{normal}.
8816 @var{diff} mode measures entropy of histogram delta values, absolute differences
8817 between neighbour histogram values.
8822 Apply a fade-in/out effect to the input video.
8824 It accepts the following parameters:
8828 The effect type can be either "in" for a fade-in, or "out" for a fade-out
8830 Default is @code{in}.
8832 @item start_frame, s
8833 Specify the number of the frame to start applying the fade
8834 effect at. Default is 0.
8837 The number of frames that the fade effect lasts. At the end of the
8838 fade-in effect, the output video will have the same intensity as the input video.
8839 At the end of the fade-out transition, the output video will be filled with the
8840 selected @option{color}.
8844 If set to 1, fade only alpha channel, if one exists on the input.
8847 @item start_time, st
8848 Specify the timestamp (in seconds) of the frame to start to apply the fade
8849 effect. If both start_frame and start_time are specified, the fade will start at
8850 whichever comes last. Default is 0.
8853 The number of seconds for which the fade effect has to last. At the end of the
8854 fade-in effect the output video will have the same intensity as the input video,
8855 at the end of the fade-out transition the output video will be filled with the
8856 selected @option{color}.
8857 If both duration and nb_frames are specified, duration is used. Default is 0
8858 (nb_frames is used by default).
8861 Specify the color of the fade. Default is "black".
8864 @subsection Examples
8868 Fade in the first 30 frames of video:
8873 The command above is equivalent to:
8879 Fade out the last 45 frames of a 200-frame video:
8882 fade=type=out:start_frame=155:nb_frames=45
8886 Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
8888 fade=in:0:25, fade=out:975:25
8892 Make the first 5 frames yellow, then fade in from frame 5-24:
8894 fade=in:5:20:color=yellow
8898 Fade in alpha over first 25 frames of video:
8900 fade=in:0:25:alpha=1
8904 Make the first 5.5 seconds black, then fade in for 0.5 seconds:
8906 fade=t=in:st=5.5:d=0.5
8912 Apply arbitrary expressions to samples in frequency domain
8916 Adjust the dc value (gain) of the luma plane of the image. The filter
8917 accepts an integer value in range @code{0} to @code{1000}. The default
8918 value is set to @code{0}.
8921 Adjust the dc value (gain) of the 1st chroma plane of the image. The
8922 filter accepts an integer value in range @code{0} to @code{1000}. The
8923 default value is set to @code{0}.
8926 Adjust the dc value (gain) of the 2nd chroma plane of the image. The
8927 filter accepts an integer value in range @code{0} to @code{1000}. The
8928 default value is set to @code{0}.
8931 Set the frequency domain weight expression for the luma plane.
8934 Set the frequency domain weight expression for the 1st chroma plane.
8937 Set the frequency domain weight expression for the 2nd chroma plane.
8940 Set when the expressions are evaluated.
8942 It accepts the following values:
8945 Only evaluate expressions once during the filter initialization.
8948 Evaluate expressions for each incoming frame.
8951 Default value is @samp{init}.
8953 The filter accepts the following variables:
8956 The coordinates of the current sample.
8960 The width and height of the image.
8963 The number of input frame, starting from 0.
8966 @subsection Examples
8972 fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
8978 fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
8984 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
8990 fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
8996 Denoise frames using 3D FFT (frequency domain filtering).
8998 The filter accepts the following options:
9002 Set the noise sigma constant. This sets denoising strength.
9003 Default value is 1. Allowed range is from 0 to 30.
9004 Using very high sigma with low overlap may give blocking artifacts.
9007 Set amount of denoising. By default all detected noise is reduced.
9008 Default value is 1. Allowed range is from 0 to 1.
9011 Set size of block, Default is 4, can be 3, 4, 5 or 6.
9012 Actual size of block in pixels is 2 to power of @var{block}, so by default
9013 block size in pixels is 2^4 which is 16.
9016 Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8.
9019 Set number of previous frames to use for denoising. By default is set to 0.
9022 Set number of next frames to to use for denoising. By default is set to 0.
9025 Set planes which will be filtered, by default are all available filtered
9031 Extract a single field from an interlaced image using stride
9032 arithmetic to avoid wasting CPU time. The output frames are marked as
9035 The filter accepts the following options:
9039 Specify whether to extract the top (if the value is @code{0} or
9040 @code{top}) or the bottom field (if the value is @code{1} or
9046 Create new frames by copying the top and bottom fields from surrounding frames
9047 supplied as numbers by the hint file.
9051 Set file containing hints: absolute/relative frame numbers.
9053 There must be one line for each frame in a clip. Each line must contain two
9054 numbers separated by the comma, optionally followed by @code{-} or @code{+}.
9055 Numbers supplied on each line of file can not be out of [N-1,N+1] where N
9056 is current frame number for @code{absolute} mode or out of [-1, 1] range
9057 for @code{relative} mode. First number tells from which frame to pick up top
9058 field and second number tells from which frame to pick up bottom field.
9060 If optionally followed by @code{+} output frame will be marked as interlaced,
9061 else if followed by @code{-} output frame will be marked as progressive, else
9062 it will be marked same as input frame.
9063 If line starts with @code{#} or @code{;} that line is skipped.
9066 Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
9069 Example of first several lines of @code{hint} file for @code{relative} mode:
9072 1,0 - # second frame, use third's frame top field and second's frame bottom field
9073 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
9090 Field matching filter for inverse telecine. It is meant to reconstruct the
9091 progressive frames from a telecined stream. The filter does not drop duplicated
9092 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
9093 followed by a decimation filter such as @ref{decimate} in the filtergraph.
9095 The separation of the field matching and the decimation is notably motivated by
9096 the possibility of inserting a de-interlacing filter fallback between the two.
9097 If the source has mixed telecined and real interlaced content,
9098 @code{fieldmatch} will not be able to match fields for the interlaced parts.
9099 But these remaining combed frames will be marked as interlaced, and thus can be
9100 de-interlaced by a later filter such as @ref{yadif} before decimation.
9102 In addition to the various configuration options, @code{fieldmatch} can take an
9103 optional second stream, activated through the @option{ppsrc} option. If
9104 enabled, the frames reconstruction will be based on the fields and frames from
9105 this second stream. This allows the first input to be pre-processed in order to
9106 help the various algorithms of the filter, while keeping the output lossless
9107 (assuming the fields are matched properly). Typically, a field-aware denoiser,
9108 or brightness/contrast adjustments can help.
9110 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
9111 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
9112 which @code{fieldmatch} is based on. While the semantic and usage are very
9113 close, some behaviour and options names can differ.
9115 The @ref{decimate} filter currently only works for constant frame rate input.
9116 If your input has mixed telecined (30fps) and progressive content with a lower
9117 framerate like 24fps use the following filterchain to produce the necessary cfr
9118 stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
9120 The filter accepts the following options:
9124 Specify the assumed field order of the input stream. Available values are:
9128 Auto detect parity (use FFmpeg's internal parity value).
9130 Assume bottom field first.
9132 Assume top field first.
9135 Note that it is sometimes recommended not to trust the parity announced by the
9138 Default value is @var{auto}.
9141 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
9142 sense that it won't risk creating jerkiness due to duplicate frames when
9143 possible, but if there are bad edits or blended fields it will end up
9144 outputting combed frames when a good match might actually exist. On the other
9145 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
9146 but will almost always find a good frame if there is one. The other values are
9147 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
9148 jerkiness and creating duplicate frames versus finding good matches in sections
9149 with bad edits, orphaned fields, blended fields, etc.
9151 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
9153 Available values are:
9157 2-way matching (p/c)
9159 2-way matching, and trying 3rd match if still combed (p/c + n)
9161 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
9163 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
9164 still combed (p/c + n + u/b)
9166 3-way matching (p/c/n)
9168 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
9169 detected as combed (p/c/n + u/b)
9172 The parenthesis at the end indicate the matches that would be used for that
9173 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
9176 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
9179 Default value is @var{pc_n}.
9182 Mark the main input stream as a pre-processed input, and enable the secondary
9183 input stream as the clean source to pick the fields from. See the filter
9184 introduction for more details. It is similar to the @option{clip2} feature from
9187 Default value is @code{0} (disabled).
9190 Set the field to match from. It is recommended to set this to the same value as
9191 @option{order} unless you experience matching failures with that setting. In
9192 certain circumstances changing the field that is used to match from can have a
9193 large impact on matching performance. Available values are:
9197 Automatic (same value as @option{order}).
9199 Match from the bottom field.
9201 Match from the top field.
9204 Default value is @var{auto}.
9207 Set whether or not chroma is included during the match comparisons. In most
9208 cases it is recommended to leave this enabled. You should set this to @code{0}
9209 only if your clip has bad chroma problems such as heavy rainbowing or other
9210 artifacts. Setting this to @code{0} could also be used to speed things up at
9211 the cost of some accuracy.
9213 Default value is @code{1}.
9217 These define an exclusion band which excludes the lines between @option{y0} and
9218 @option{y1} from being included in the field matching decision. An exclusion
9219 band can be used to ignore subtitles, a logo, or other things that may
9220 interfere with the matching. @option{y0} sets the starting scan line and
9221 @option{y1} sets the ending line; all lines in between @option{y0} and
9222 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
9223 @option{y0} and @option{y1} to the same value will disable the feature.
9224 @option{y0} and @option{y1} defaults to @code{0}.
9227 Set the scene change detection threshold as a percentage of maximum change on
9228 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
9229 detection is only relevant in case @option{combmatch}=@var{sc}. The range for
9230 @option{scthresh} is @code{[0.0, 100.0]}.
9232 Default value is @code{12.0}.
9235 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
9236 account the combed scores of matches when deciding what match to use as the
9237 final match. Available values are:
9241 No final matching based on combed scores.
9243 Combed scores are only used when a scene change is detected.
9245 Use combed scores all the time.
9248 Default is @var{sc}.
9251 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
9252 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
9253 Available values are:
9257 No forced calculation.
9259 Force p/c/n calculations.
9261 Force p/c/n/u/b calculations.
9264 Default value is @var{none}.
9267 This is the area combing threshold used for combed frame detection. This
9268 essentially controls how "strong" or "visible" combing must be to be detected.
9269 Larger values mean combing must be more visible and smaller values mean combing
9270 can be less visible or strong and still be detected. Valid settings are from
9271 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
9272 be detected as combed). This is basically a pixel difference value. A good
9273 range is @code{[8, 12]}.
9275 Default value is @code{9}.
9278 Sets whether or not chroma is considered in the combed frame decision. Only
9279 disable this if your source has chroma problems (rainbowing, etc.) that are
9280 causing problems for the combed frame detection with chroma enabled. Actually,
9281 using @option{chroma}=@var{0} is usually more reliable, except for the case
9282 where there is chroma only combing in the source.
9284 Default value is @code{0}.
9288 Respectively set the x-axis and y-axis size of the window used during combed
9289 frame detection. This has to do with the size of the area in which
9290 @option{combpel} pixels are required to be detected as combed for a frame to be
9291 declared combed. See the @option{combpel} parameter description for more info.
9292 Possible values are any number that is a power of 2 starting at 4 and going up
9295 Default value is @code{16}.
9298 The number of combed pixels inside any of the @option{blocky} by
9299 @option{blockx} size blocks on the frame for the frame to be detected as
9300 combed. While @option{cthresh} controls how "visible" the combing must be, this
9301 setting controls "how much" combing there must be in any localized area (a
9302 window defined by the @option{blockx} and @option{blocky} settings) on the
9303 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
9304 which point no frames will ever be detected as combed). This setting is known
9305 as @option{MI} in TFM/VFM vocabulary.
9307 Default value is @code{80}.
9310 @anchor{p/c/n/u/b meaning}
9311 @subsection p/c/n/u/b meaning
9313 @subsubsection p/c/n
9315 We assume the following telecined stream:
9318 Top fields: 1 2 2 3 4
9319 Bottom fields: 1 2 3 4 4
9322 The numbers correspond to the progressive frame the fields relate to. Here, the
9323 first two frames are progressive, the 3rd and 4th are combed, and so on.
9325 When @code{fieldmatch} is configured to run a matching from bottom
9326 (@option{field}=@var{bottom}) this is how this input stream get transformed:
9331 B 1 2 3 4 4 <-- matching reference
9340 As a result of the field matching, we can see that some frames get duplicated.
9341 To perform a complete inverse telecine, you need to rely on a decimation filter
9342 after this operation. See for instance the @ref{decimate} filter.
9344 The same operation now matching from top fields (@option{field}=@var{top})
9349 T 1 2 2 3 4 <-- matching reference
9359 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
9360 basically, they refer to the frame and field of the opposite parity:
9363 @item @var{p} matches the field of the opposite parity in the previous frame
9364 @item @var{c} matches the field of the opposite parity in the current frame
9365 @item @var{n} matches the field of the opposite parity in the next frame
9370 The @var{u} and @var{b} matching are a bit special in the sense that they match
9371 from the opposite parity flag. In the following examples, we assume that we are
9372 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
9373 'x' is placed above and below each matched fields.
9375 With bottom matching (@option{field}=@var{bottom}):
9380 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
9381 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
9389 With top matching (@option{field}=@var{top}):
9394 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
9395 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
9403 @subsection Examples
9405 Simple IVTC of a top field first telecined stream:
9407 fieldmatch=order=tff:combmatch=none, decimate
9410 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
9412 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
9417 Transform the field order of the input video.
9419 It accepts the following parameters:
9424 The output field order. Valid values are @var{tff} for top field first or @var{bff}
9425 for bottom field first.
9428 The default value is @samp{tff}.
9430 The transformation is done by shifting the picture content up or down
9431 by one line, and filling the remaining line with appropriate picture content.
9432 This method is consistent with most broadcast field order converters.
9434 If the input video is not flagged as being interlaced, or it is already
9435 flagged as being of the required output field order, then this filter does
9436 not alter the incoming video.
9438 It is very useful when converting to or from PAL DV material,
9439 which is bottom field first.
9443 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
9446 @section fifo, afifo
9448 Buffer input images and send them when they are requested.
9450 It is mainly useful when auto-inserted by the libavfilter
9453 It does not take parameters.
9455 @section fillborders
9457 Fill borders of the input video, without changing video stream dimensions.
9458 Sometimes video can have garbage at the four edges and you may not want to
9459 crop video input to keep size multiple of some number.
9461 This filter accepts the following options:
9465 Number of pixels to fill from left border.
9468 Number of pixels to fill from right border.
9471 Number of pixels to fill from top border.
9474 Number of pixels to fill from bottom border.
9479 It accepts the following values:
9482 fill pixels using outermost pixels
9485 fill pixels using mirroring
9488 fill pixels with constant value
9491 Default is @var{smear}.
9494 Set color for pixels in fixed mode. Default is @var{black}.
9499 Find a rectangular object
9501 It accepts the following options:
9505 Filepath of the object image, needs to be in gray8.
9508 Detection threshold, default is 0.5.
9511 Number of mipmaps, default is 3.
9513 @item xmin, ymin, xmax, ymax
9514 Specifies the rectangle in which to search.
9517 @subsection Examples
9521 Generate a representative palette of a given video using @command{ffmpeg}:
9523 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
9529 Cover a rectangular object
9531 It accepts the following options:
9535 Filepath of the optional cover image, needs to be in yuv420.
9540 It accepts the following values:
9543 cover it by the supplied image
9545 cover it by interpolating the surrounding pixels
9548 Default value is @var{blur}.
9551 @subsection Examples
9555 Generate a representative palette of a given video using @command{ffmpeg}:
9557 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
9563 Flood area with values of same pixel components with another values.
9565 It accepts the following options:
9568 Set pixel x coordinate.
9571 Set pixel y coordinate.
9574 Set source #0 component value.
9577 Set source #1 component value.
9580 Set source #2 component value.
9583 Set source #3 component value.
9586 Set destination #0 component value.
9589 Set destination #1 component value.
9592 Set destination #2 component value.
9595 Set destination #3 component value.
9601 Convert the input video to one of the specified pixel formats.
9602 Libavfilter will try to pick one that is suitable as input to
9605 It accepts the following parameters:
9609 A '|'-separated list of pixel format names, such as
9610 "pix_fmts=yuv420p|monow|rgb24".
9614 @subsection Examples
9618 Convert the input video to the @var{yuv420p} format
9620 format=pix_fmts=yuv420p
9623 Convert the input video to any of the formats in the list
9625 format=pix_fmts=yuv420p|yuv444p|yuv410p
9632 Convert the video to specified constant frame rate by duplicating or dropping
9633 frames as necessary.
9635 It accepts the following parameters:
9639 The desired output frame rate. The default is @code{25}.
9642 Assume the first PTS should be the given value, in seconds. This allows for
9643 padding/trimming at the start of stream. By default, no assumption is made
9644 about the first frame's expected PTS, so no padding or trimming is done.
9645 For example, this could be set to 0 to pad the beginning with duplicates of
9646 the first frame if a video stream starts after the audio stream or to trim any
9647 frames with a negative PTS.
9650 Timestamp (PTS) rounding method.
9652 Possible values are:
9659 round towards -infinity
9661 round towards +infinity
9665 The default is @code{near}.
9668 Action performed when reading the last frame.
9670 Possible values are:
9673 Use same timestamp rounding method as used for other frames.
9675 Pass through last frame if input duration has not been reached yet.
9677 The default is @code{round}.
9681 Alternatively, the options can be specified as a flat string:
9682 @var{fps}[:@var{start_time}[:@var{round}]].
9684 See also the @ref{setpts} filter.
9686 @subsection Examples
9690 A typical usage in order to set the fps to 25:
9696 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
9698 fps=fps=film:round=near
9704 Pack two different video streams into a stereoscopic video, setting proper
9705 metadata on supported codecs. The two views should have the same size and
9706 framerate and processing will stop when the shorter video ends. Please note
9707 that you may conveniently adjust view properties with the @ref{scale} and
9710 It accepts the following parameters:
9714 The desired packing format. Supported values are:
9719 The views are next to each other (default).
9722 The views are on top of each other.
9725 The views are packed by line.
9728 The views are packed by column.
9731 The views are temporally interleaved.
9740 # Convert left and right views into a frame-sequential video
9741 ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
9743 # Convert views into a side-by-side video with the same output resolution as the input
9744 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
9749 Change the frame rate by interpolating new video output frames from the source
9752 This filter is not designed to function correctly with interlaced media. If
9753 you wish to change the frame rate of interlaced media then you are required
9754 to deinterlace before this filter and re-interlace after this filter.
9756 A description of the accepted options follows.
9760 Specify the output frames per second. This option can also be specified
9761 as a value alone. The default is @code{50}.
9764 Specify the start of a range where the output frame will be created as a
9765 linear interpolation of two frames. The range is [@code{0}-@code{255}],
9766 the default is @code{15}.
9769 Specify the end of a range where the output frame will be created as a
9770 linear interpolation of two frames. The range is [@code{0}-@code{255}],
9771 the default is @code{240}.
9774 Specify the level at which a scene change is detected as a value between
9775 0 and 100 to indicate a new scene; a low value reflects a low
9776 probability for the current frame to introduce a new scene, while a higher
9777 value means the current frame is more likely to be one.
9778 The default is @code{8.2}.
9781 Specify flags influencing the filter process.
9783 Available value for @var{flags} is:
9786 @item scene_change_detect, scd
9787 Enable scene change detection using the value of the option @var{scene}.
9788 This flag is enabled by default.
9794 Select one frame every N-th frame.
9796 This filter accepts the following option:
9799 Select frame after every @code{step} frames.
9800 Allowed values are positive integers higher than 0. Default value is @code{1}.
9806 Apply a frei0r effect to the input video.
9808 To enable the compilation of this filter, you need to install the frei0r
9809 header and configure FFmpeg with @code{--enable-frei0r}.
9811 It accepts the following parameters:
9816 The name of the frei0r effect to load. If the environment variable
9817 @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
9818 directories specified by the colon-separated list in @env{FREI0R_PATH}.
9819 Otherwise, the standard frei0r paths are searched, in this order:
9820 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
9821 @file{/usr/lib/frei0r-1/}.
9824 A '|'-separated list of parameters to pass to the frei0r effect.
9828 A frei0r effect parameter can be a boolean (its value is either
9829 "y" or "n"), a double, a color (specified as
9830 @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
9831 numbers between 0.0 and 1.0, inclusive) or a color description as specified in the
9832 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils},
9833 a position (specified as @var{X}/@var{Y}, where
9834 @var{X} and @var{Y} are floating point numbers) and/or a string.
9836 The number and types of parameters depend on the loaded effect. If an
9837 effect parameter is not specified, the default value is set.
9839 @subsection Examples
9843 Apply the distort0r effect, setting the first two double parameters:
9845 frei0r=filter_name=distort0r:filter_params=0.5|0.01
9849 Apply the colordistance effect, taking a color as the first parameter:
9851 frei0r=colordistance:0.2/0.3/0.4
9852 frei0r=colordistance:violet
9853 frei0r=colordistance:0x112233
9857 Apply the perspective effect, specifying the top left and top right image
9860 frei0r=perspective:0.2/0.2|0.8/0.2
9864 For more information, see
9865 @url{http://frei0r.dyne.org}
9869 Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
9871 It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
9872 processing filter, one of them is performed once per block, not per pixel.
9873 This allows for much higher speed.
9875 The filter accepts the following options:
9879 Set quality. This option defines the number of levels for averaging. It accepts
9880 an integer in the range 4-5. Default value is @code{4}.
9883 Force a constant quantization parameter. It accepts an integer in range 0-63.
9884 If not set, the filter will use the QP from the video stream (if available).
9887 Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
9888 more details but also more artifacts, while higher values make the image smoother
9889 but also blurrier. Default value is @code{0} − PSNR optimal.
9892 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
9893 option may cause flicker since the B-Frames have often larger QP. Default is
9894 @code{0} (not enabled).
9900 Apply Gaussian blur filter.
9902 The filter accepts the following options:
9906 Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
9909 Set number of steps for Gaussian approximation. Defauls is @code{1}.
9912 Set which planes to filter. By default all planes are filtered.
9915 Set vertical sigma, if negative it will be same as @code{sigma}.
9916 Default is @code{-1}.
9921 The filter accepts the following options:
9925 Set the luminance expression.
9927 Set the chrominance blue expression.
9929 Set the chrominance red expression.
9931 Set the alpha expression.
9933 Set the red expression.
9935 Set the green expression.
9937 Set the blue expression.
9940 The colorspace is selected according to the specified options. If one
9941 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
9942 options is specified, the filter will automatically select a YCbCr
9943 colorspace. If one of the @option{red_expr}, @option{green_expr}, or
9944 @option{blue_expr} options is specified, it will select an RGB
9947 If one of the chrominance expression is not defined, it falls back on the other
9948 one. If no alpha expression is specified it will evaluate to opaque value.
9949 If none of chrominance expressions are specified, they will evaluate
9950 to the luminance expression.
9952 The expressions can use the following variables and functions:
9956 The sequential number of the filtered frame, starting from @code{0}.
9960 The coordinates of the current sample.
9964 The width and height of the image.
9968 Width and height scale depending on the currently filtered plane. It is the
9969 ratio between the corresponding luma plane number of pixels and the current
9970 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
9971 @code{0.5,0.5} for chroma planes.
9974 Time of the current frame, expressed in seconds.
9977 Return the value of the pixel at location (@var{x},@var{y}) of the current
9981 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
9985 Return the value of the pixel at location (@var{x},@var{y}) of the
9986 blue-difference chroma plane. Return 0 if there is no such plane.
9989 Return the value of the pixel at location (@var{x},@var{y}) of the
9990 red-difference chroma plane. Return 0 if there is no such plane.
9995 Return the value of the pixel at location (@var{x},@var{y}) of the
9996 red/green/blue component. Return 0 if there is no such component.
9999 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
10000 plane. Return 0 if there is no such plane.
10003 For functions, if @var{x} and @var{y} are outside the area, the value will be
10004 automatically clipped to the closer edge.
10006 @subsection Examples
10010 Flip the image horizontally:
10016 Generate a bidimensional sine wave, with angle @code{PI/3} and a
10017 wavelength of 100 pixels:
10019 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
10023 Generate a fancy enigmatic moving light:
10025 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
10029 Generate a quick emboss effect:
10031 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
10035 Modify RGB components depending on pixel position:
10037 geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
10041 Create a radial gradient that is the same size as the input (also see
10042 the @ref{vignette} filter):
10044 geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
10050 Fix the banding artifacts that are sometimes introduced into nearly flat
10051 regions by truncation to 8-bit color depth.
10052 Interpolate the gradients that should go where the bands are, and
10055 It is designed for playback only. Do not use it prior to
10056 lossy compression, because compression tends to lose the dither and
10057 bring back the bands.
10059 It accepts the following parameters:
10064 The maximum amount by which the filter will change any one pixel. This is also
10065 the threshold for detecting nearly flat regions. Acceptable values range from
10066 .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
10070 The neighborhood to fit the gradient to. A larger radius makes for smoother
10071 gradients, but also prevents the filter from modifying the pixels near detailed
10072 regions. Acceptable values are 8-32; the default value is 16. Out-of-range
10073 values will be clipped to the valid range.
10077 Alternatively, the options can be specified as a flat string:
10078 @var{strength}[:@var{radius}]
10080 @subsection Examples
10084 Apply the filter with a @code{3.5} strength and radius of @code{8}:
10090 Specify radius, omitting the strength (which will fall-back to the default
10099 A color constancy variation filter which estimates scene illumination via grey edge algorithm
10100 and corrects the scene colors accordingly.
10102 See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf}
10104 The filter accepts the following options:
10108 The order of differentiation to be applied on the scene. Must be chosen in the range
10109 [0,2] and default value is 1.
10112 The Minkowski parameter to be used for calculating the Minkowski distance. Must
10113 be chosen in the range [0,20] and default value is 1. Set to 0 for getting
10114 max value instead of calculating Minkowski distance.
10117 The standard deviation of Gaussian blur to be applied on the scene. Must be
10118 chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) )
10119 can't be euqal to 0 if @var{difford} is greater than 0.
10122 @subsection Examples
10128 greyedge=difford=1:minknorm=5:sigma=2
10134 greyedge=difford=1:minknorm=0:sigma=2
10142 Apply a Hald CLUT to a video stream.
10144 First input is the video stream to process, and second one is the Hald CLUT.
10145 The Hald CLUT input can be a simple picture or a complete video stream.
10147 The filter accepts the following options:
10151 Force termination when the shortest input terminates. Default is @code{0}.
10153 Continue applying the last CLUT after the end of the stream. A value of
10154 @code{0} disable the filter after the last frame of the CLUT is reached.
10155 Default is @code{1}.
10158 @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
10159 filters share the same internals).
10161 More information about the Hald CLUT can be found on Eskil Steenberg's website
10162 (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
10164 @subsection Workflow examples
10166 @subsubsection Hald CLUT video stream
10168 Generate an identity Hald CLUT stream altered with various effects:
10170 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
10173 Note: make sure you use a lossless codec.
10175 Then use it with @code{haldclut} to apply it on some random stream:
10177 ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
10180 The Hald CLUT will be applied to the 10 first seconds (duration of
10181 @file{clut.nut}), then the latest picture of that CLUT stream will be applied
10182 to the remaining frames of the @code{mandelbrot} stream.
10184 @subsubsection Hald CLUT with preview
10186 A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
10187 @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
10188 biggest possible square starting at the top left of the picture. The remaining
10189 padding pixels (bottom or right) will be ignored. This area can be used to add
10190 a preview of the Hald CLUT.
10192 Typically, the following generated Hald CLUT will be supported by the
10193 @code{haldclut} filter:
10196 ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
10197 pad=iw+320 [padded_clut];
10198 smptebars=s=320x256, split [a][b];
10199 [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
10200 [main][b] overlay=W-320" -frames:v 1 clut.png
10203 It contains the original and a preview of the effect of the CLUT: SMPTE color
10204 bars are displayed on the right-top, and below the same color bars processed by
10207 Then, the effect of this Hald CLUT can be visualized with:
10209 ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
10214 Flip the input video horizontally.
10216 For example, to horizontally flip the input video with @command{ffmpeg}:
10218 ffmpeg -i in.avi -vf "hflip" out.avi
10222 This filter applies a global color histogram equalization on a
10225 It can be used to correct video that has a compressed range of pixel
10226 intensities. The filter redistributes the pixel intensities to
10227 equalize their distribution across the intensity range. It may be
10228 viewed as an "automatically adjusting contrast filter". This filter is
10229 useful only for correcting degraded or poorly captured source
10232 The filter accepts the following options:
10236 Determine the amount of equalization to be applied. As the strength
10237 is reduced, the distribution of pixel intensities more-and-more
10238 approaches that of the input frame. The value must be a float number
10239 in the range [0,1] and defaults to 0.200.
10242 Set the maximum intensity that can generated and scale the output
10243 values appropriately. The strength should be set as desired and then
10244 the intensity can be limited if needed to avoid washing-out. The value
10245 must be a float number in the range [0,1] and defaults to 0.210.
10248 Set the antibanding level. If enabled the filter will randomly vary
10249 the luminance of output pixels by a small amount to avoid banding of
10250 the histogram. Possible values are @code{none}, @code{weak} or
10251 @code{strong}. It defaults to @code{none}.
10256 Compute and draw a color distribution histogram for the input video.
10258 The computed histogram is a representation of the color component
10259 distribution in an image.
10261 Standard histogram displays the color components distribution in an image.
10262 Displays color graph for each color component. Shows distribution of
10263 the Y, U, V, A or R, G, B components, depending on input format, in the
10264 current frame. Below each graph a color component scale meter is shown.
10266 The filter accepts the following options:
10270 Set height of level. Default value is @code{200}.
10271 Allowed range is [50, 2048].
10274 Set height of color scale. Default value is @code{12}.
10275 Allowed range is [0, 40].
10279 It accepts the following values:
10282 Per color component graphs are placed below each other.
10285 Per color component graphs are placed side by side.
10288 Presents information identical to that in the @code{parade}, except
10289 that the graphs representing color components are superimposed directly
10292 Default is @code{stack}.
10295 Set mode. Can be either @code{linear}, or @code{logarithmic}.
10296 Default is @code{linear}.
10299 Set what color components to display.
10300 Default is @code{7}.
10303 Set foreground opacity. Default is @code{0.7}.
10306 Set background opacity. Default is @code{0.5}.
10309 @subsection Examples
10314 Calculate and draw histogram:
10316 ffplay -i input -vf histogram
10324 This is a high precision/quality 3d denoise filter. It aims to reduce
10325 image noise, producing smooth images and making still images really
10326 still. It should enhance compressibility.
10328 It accepts the following optional parameters:
10332 A non-negative floating point number which specifies spatial luma strength.
10333 It defaults to 4.0.
10335 @item chroma_spatial
10336 A non-negative floating point number which specifies spatial chroma strength.
10337 It defaults to 3.0*@var{luma_spatial}/4.0.
10340 A floating point number which specifies luma temporal strength. It defaults to
10341 6.0*@var{luma_spatial}/4.0.
10344 A floating point number which specifies chroma temporal strength. It defaults to
10345 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
10348 @section hwdownload
10350 Download hardware frames to system memory.
10352 The input must be in hardware frames, and the output a non-hardware format.
10353 Not all formats will be supported on the output - it may be necessary to insert
10354 an additional @option{format} filter immediately following in the graph to get
10355 the output in a supported format.
10359 Map hardware frames to system memory or to another device.
10361 This filter has several different modes of operation; which one is used depends
10362 on the input and output formats:
10365 Hardware frame input, normal frame output
10367 Map the input frames to system memory and pass them to the output. If the
10368 original hardware frame is later required (for example, after overlaying
10369 something else on part of it), the @option{hwmap} filter can be used again
10370 in the next mode to retrieve it.
10372 Normal frame input, hardware frame output
10374 If the input is actually a software-mapped hardware frame, then unmap it -
10375 that is, return the original hardware frame.
10377 Otherwise, a device must be provided. Create new hardware surfaces on that
10378 device for the output, then map them back to the software format at the input
10379 and give those frames to the preceding filter. This will then act like the
10380 @option{hwupload} filter, but may be able to avoid an additional copy when
10381 the input is already in a compatible format.
10383 Hardware frame input and output
10385 A device must be supplied for the output, either directly or with the
10386 @option{derive_device} option. The input and output devices must be of
10387 different types and compatible - the exact meaning of this is
10388 system-dependent, but typically it means that they must refer to the same
10389 underlying hardware context (for example, refer to the same graphics card).
10391 If the input frames were originally created on the output device, then unmap
10392 to retrieve the original frames.
10394 Otherwise, map the frames to the output device - create new hardware frames
10395 on the output corresponding to the frames on the input.
10398 The following additional parameters are accepted:
10402 Set the frame mapping mode. Some combination of:
10405 The mapped frame should be readable.
10407 The mapped frame should be writeable.
10409 The mapping will always overwrite the entire frame.
10411 This may improve performance in some cases, as the original contents of the
10412 frame need not be loaded.
10414 The mapping must not involve any copying.
10416 Indirect mappings to copies of frames are created in some cases where either
10417 direct mapping is not possible or it would have unexpected properties.
10418 Setting this flag ensures that the mapping is direct and will fail if that is
10421 Defaults to @var{read+write} if not specified.
10423 @item derive_device @var{type}
10424 Rather than using the device supplied at initialisation, instead derive a new
10425 device of type @var{type} from the device the input frames exist on.
10428 In a hardware to hardware mapping, map in reverse - create frames in the sink
10429 and map them back to the source. This may be necessary in some cases where
10430 a mapping in one direction is required but only the opposite direction is
10431 supported by the devices being used.
10433 This option is dangerous - it may break the preceding filter in undefined
10434 ways if there are any additional constraints on that filter's output.
10435 Do not use it without fully understanding the implications of its use.
10440 Upload system memory frames to hardware surfaces.
10442 The device to upload to must be supplied when the filter is initialised. If
10443 using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
10446 @anchor{hwupload_cuda}
10447 @section hwupload_cuda
10449 Upload system memory frames to a CUDA device.
10451 It accepts the following optional parameters:
10455 The number of the CUDA device to use
10460 Apply a high-quality magnification filter designed for pixel art. This filter
10461 was originally created by Maxim Stepin.
10463 It accepts the following option:
10467 Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
10468 @code{hq3x} and @code{4} for @code{hq4x}.
10469 Default is @code{3}.
10473 Stack input videos horizontally.
10475 All streams must be of same pixel format and of same height.
10477 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
10478 to create same output.
10480 The filter accept the following option:
10484 Set number of input streams. Default is 2.
10487 If set to 1, force the output to terminate when the shortest input
10488 terminates. Default value is 0.
10493 Modify the hue and/or the saturation of the input.
10495 It accepts the following parameters:
10499 Specify the hue angle as a number of degrees. It accepts an expression,
10500 and defaults to "0".
10503 Specify the saturation in the [-10,10] range. It accepts an expression and
10507 Specify the hue angle as a number of radians. It accepts an
10508 expression, and defaults to "0".
10511 Specify the brightness in the [-10,10] range. It accepts an expression and
10515 @option{h} and @option{H} are mutually exclusive, and can't be
10516 specified at the same time.
10518 The @option{b}, @option{h}, @option{H} and @option{s} option values are
10519 expressions containing the following constants:
10523 frame count of the input frame starting from 0
10526 presentation timestamp of the input frame expressed in time base units
10529 frame rate of the input video, NAN if the input frame rate is unknown
10532 timestamp expressed in seconds, NAN if the input timestamp is unknown
10535 time base of the input video
10538 @subsection Examples
10542 Set the hue to 90 degrees and the saturation to 1.0:
10548 Same command but expressing the hue in radians:
10554 Rotate hue and make the saturation swing between 0
10555 and 2 over a period of 1 second:
10557 hue="H=2*PI*t: s=sin(2*PI*t)+1"
10561 Apply a 3 seconds saturation fade-in effect starting at 0:
10563 hue="s=min(t/3\,1)"
10566 The general fade-in expression can be written as:
10568 hue="s=min(0\, max((t-START)/DURATION\, 1))"
10572 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
10574 hue="s=max(0\, min(1\, (8-t)/3))"
10577 The general fade-out expression can be written as:
10579 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
10584 @subsection Commands
10586 This filter supports the following commands:
10592 Modify the hue and/or the saturation and/or brightness of the input video.
10593 The command accepts the same syntax of the corresponding option.
10595 If the specified expression is not valid, it is kept at its current
10599 @section hysteresis
10601 Grow first stream into second stream by connecting components.
10602 This makes it possible to build more robust edge masks.
10604 This filter accepts the following options:
10608 Set which planes will be processed as bitmap, unprocessed planes will be
10609 copied from first stream.
10610 By default value 0xf, all planes will be processed.
10613 Set threshold which is used in filtering. If pixel component value is higher than
10614 this value filter algorithm for connecting components is activated.
10615 By default value is 0.
10620 Detect video interlacing type.
10622 This filter tries to detect if the input frames are interlaced, progressive,
10623 top or bottom field first. It will also try to detect fields that are
10624 repeated between adjacent frames (a sign of telecine).
10626 Single frame detection considers only immediately adjacent frames when classifying each frame.
10627 Multiple frame detection incorporates the classification history of previous frames.
10629 The filter will log these metadata values:
10632 @item single.current_frame
10633 Detected type of current frame using single-frame detection. One of:
10634 ``tff'' (top field first), ``bff'' (bottom field first),
10635 ``progressive'', or ``undetermined''
10638 Cumulative number of frames detected as top field first using single-frame detection.
10641 Cumulative number of frames detected as top field first using multiple-frame detection.
10644 Cumulative number of frames detected as bottom field first using single-frame detection.
10646 @item multiple.current_frame
10647 Detected type of current frame using multiple-frame detection. One of:
10648 ``tff'' (top field first), ``bff'' (bottom field first),
10649 ``progressive'', or ``undetermined''
10652 Cumulative number of frames detected as bottom field first using multiple-frame detection.
10654 @item single.progressive
10655 Cumulative number of frames detected as progressive using single-frame detection.
10657 @item multiple.progressive
10658 Cumulative number of frames detected as progressive using multiple-frame detection.
10660 @item single.undetermined
10661 Cumulative number of frames that could not be classified using single-frame detection.
10663 @item multiple.undetermined
10664 Cumulative number of frames that could not be classified using multiple-frame detection.
10666 @item repeated.current_frame
10667 Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
10669 @item repeated.neither
10670 Cumulative number of frames with no repeated field.
10673 Cumulative number of frames with the top field repeated from the previous frame's top field.
10675 @item repeated.bottom
10676 Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
10679 The filter accepts the following options:
10683 Set interlacing threshold.
10685 Set progressive threshold.
10687 Threshold for repeated field detection.
10689 Number of frames after which a given frame's contribution to the
10690 statistics is halved (i.e., it contributes only 0.5 to its
10691 classification). The default of 0 means that all frames seen are given
10692 full weight of 1.0 forever.
10693 @item analyze_interlaced_flag
10694 When this is not 0 then idet will use the specified number of frames to determine
10695 if the interlaced flag is accurate, it will not count undetermined frames.
10696 If the flag is found to be accurate it will be used without any further
10697 computations, if it is found to be inaccurate it will be cleared without any
10698 further computations. This allows inserting the idet filter as a low computational
10699 method to clean up the interlaced flag
10704 Deinterleave or interleave fields.
10706 This filter allows one to process interlaced images fields without
10707 deinterlacing them. Deinterleaving splits the input frame into 2
10708 fields (so called half pictures). Odd lines are moved to the top
10709 half of the output image, even lines to the bottom half.
10710 You can process (filter) them independently and then re-interleave them.
10712 The filter accepts the following options:
10716 @item chroma_mode, c
10717 @item alpha_mode, a
10718 Available values for @var{luma_mode}, @var{chroma_mode} and
10719 @var{alpha_mode} are:
10725 @item deinterleave, d
10726 Deinterleave fields, placing one above the other.
10728 @item interleave, i
10729 Interleave fields. Reverse the effect of deinterleaving.
10731 Default value is @code{none}.
10733 @item luma_swap, ls
10734 @item chroma_swap, cs
10735 @item alpha_swap, as
10736 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
10741 Apply inflate effect to the video.
10743 This filter replaces the pixel by the local(3x3) average by taking into account
10744 only values higher than the pixel.
10746 It accepts the following options:
10753 Limit the maximum change for each plane, default is 65535.
10754 If 0, plane will remain unchanged.
10759 Simple interlacing filter from progressive contents. This interleaves upper (or
10760 lower) lines from odd frames with lower (or upper) lines from even frames,
10761 halving the frame rate and preserving image height.
10764 Original Original New Frame
10765 Frame 'j' Frame 'j+1' (tff)
10766 ========== =========== ==================
10767 Line 0 --------------------> Frame 'j' Line 0
10768 Line 1 Line 1 ----> Frame 'j+1' Line 1
10769 Line 2 ---------------------> Frame 'j' Line 2
10770 Line 3 Line 3 ----> Frame 'j+1' Line 3
10772 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
10775 It accepts the following optional parameters:
10779 This determines whether the interlaced frame is taken from the even
10780 (tff - default) or odd (bff) lines of the progressive frame.
10783 Vertical lowpass filter to avoid twitter interlacing and
10784 reduce moire patterns.
10788 Disable vertical lowpass filter
10791 Enable linear filter (default)
10794 Enable complex filter. This will slightly less reduce twitter and moire
10795 but better retain detail and subjective sharpness impression.
10802 Deinterlace input video by applying Donald Graft's adaptive kernel
10803 deinterling. Work on interlaced parts of a video to produce
10804 progressive frames.
10806 The description of the accepted parameters follows.
10810 Set the threshold which affects the filter's tolerance when
10811 determining if a pixel line must be processed. It must be an integer
10812 in the range [0,255] and defaults to 10. A value of 0 will result in
10813 applying the process on every pixels.
10816 Paint pixels exceeding the threshold value to white if set to 1.
10820 Set the fields order. Swap fields if set to 1, leave fields alone if
10824 Enable additional sharpening if set to 1. Default is 0.
10827 Enable twoway sharpening if set to 1. Default is 0.
10830 @subsection Examples
10834 Apply default values:
10836 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
10840 Enable additional sharpening:
10846 Paint processed pixels in white:
10852 @section lenscorrection
10854 Correct radial lens distortion
10856 This filter can be used to correct for radial distortion as can result from the use
10857 of wide angle lenses, and thereby re-rectify the image. To find the right parameters
10858 one can use tools available for example as part of opencv or simply trial-and-error.
10859 To use opencv use the calibration sample (under samples/cpp) from the opencv sources
10860 and extract the k1 and k2 coefficients from the resulting matrix.
10862 Note that effectively the same filter is available in the open-source tools Krita and
10863 Digikam from the KDE project.
10865 In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
10866 this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
10867 brightness distribution, so you may want to use both filters together in certain
10868 cases, though you will have to take care of ordering, i.e. whether vignetting should
10869 be applied before or after lens correction.
10871 @subsection Options
10873 The filter accepts the following options:
10877 Relative x-coordinate of the focal point of the image, and thereby the center of the
10878 distortion. This value has a range [0,1] and is expressed as fractions of the image
10879 width. Default is 0.5.
10881 Relative y-coordinate of the focal point of the image, and thereby the center of the
10882 distortion. This value has a range [0,1] and is expressed as fractions of the image
10883 height. Default is 0.5.
10885 Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means
10886 no correction. Default is 0.
10888 Coefficient of the double quadratic correction term. This value has a range [-1,1].
10889 0 means no correction. Default is 0.
10892 The formula that generates the correction is:
10894 @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)
10896 where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
10897 distances from the focal point in the source and target images, respectively.
10901 Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}).
10903 The @code{lensfun} filter requires the camera make, camera model, and lens model
10904 to apply the lens correction. The filter will load the lensfun database and
10905 query it to find the corresponding camera and lens entries in the database. As
10906 long as these entries can be found with the given options, the filter can
10907 perform corrections on frames. Note that incomplete strings will result in the
10908 filter choosing the best match with the given options, and the filter will
10909 output the chosen camera and lens models (logged with level "info"). You must
10910 provide the make, camera model, and lens model as they are required.
10912 The filter accepts the following options:
10916 The make of the camera (for example, "Canon"). This option is required.
10919 The model of the camera (for example, "Canon EOS 100D"). This option is
10923 The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This
10924 option is required.
10927 The type of correction to apply. The following values are valid options:
10931 Enables fixing lens vignetting.
10934 Enables fixing lens geometry. This is the default.
10937 Enables fixing chromatic aberrations.
10940 Enables fixing lens vignetting and lens geometry.
10943 Enables fixing lens vignetting and chromatic aberrations.
10946 Enables fixing both lens geometry and chromatic aberrations.
10949 Enables all possible corrections.
10953 The focal length of the image/video (zoom; expected constant for video). For
10954 example, a 18--55mm lens has focal length range of [18--55], so a value in that
10955 range should be chosen when using that lens. Default 18.
10958 The aperture of the image/video (expected constant for video). Note that
10959 aperture is only used for vignetting correction. Default 3.5.
10961 @item focus_distance
10962 The focus distance of the image/video (expected constant for video). Note that
10963 focus distance is only used for vignetting and only slightly affects the
10964 vignetting correction process. If unknown, leave it at the default value (which
10967 @item target_geometry
10968 The target geometry of the output image/video. The following values are valid
10972 @item rectilinear (default)
10975 @item equirectangular
10976 @item fisheye_orthographic
10977 @item fisheye_stereographic
10978 @item fisheye_equisolid
10979 @item fisheye_thoby
10982 Apply the reverse of image correction (instead of correcting distortion, apply
10985 @item interpolation
10986 The type of interpolation used when correcting distortion. The following values
10991 @item linear (default)
10996 @subsection Examples
11000 Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens
11001 model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and
11005 ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8 -c:v h264 -b:v 8000k output.mov
11009 Apply the same as before, but only for the first 5 seconds of video.
11012 ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8:enable='lte(t\,5)' -c:v h264 -b:v 8000k output.mov
11019 Obtain the VMAF (Video Multi-Method Assessment Fusion)
11020 score between two input videos.
11022 The obtained VMAF score is printed through the logging system.
11024 It requires Netflix's vmaf library (libvmaf) as a pre-requisite.
11025 After installing the library it can be enabled using:
11026 @code{./configure --enable-libvmaf --enable-version3}.
11027 If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}.
11029 The filter has following options:
11033 Set the model path which is to be used for SVM.
11034 Default value: @code{"vmaf_v0.6.1.pkl"}
11037 Set the file path to be used to store logs.
11040 Set the format of the log file (xml or json).
11042 @item enable_transform
11043 Enables transform for computing vmaf.
11046 Invokes the phone model which will generate VMAF scores higher than in the
11047 regular model, which is more suitable for laptop, TV, etc. viewing conditions.
11050 Enables computing psnr along with vmaf.
11053 Enables computing ssim along with vmaf.
11056 Enables computing ms_ssim along with vmaf.
11059 Set the pool method (mean, min or harmonic mean) to be used for computing vmaf.
11062 Set number of threads to be used when computing vmaf.
11065 Set interval for frame subsampling used when computing vmaf.
11067 @item enable_conf_interval
11068 Enables confidence interval.
11071 This filter also supports the @ref{framesync} options.
11073 On the below examples the input file @file{main.mpg} being processed is
11074 compared with the reference file @file{ref.mpg}.
11077 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
11080 Example with options:
11082 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:enable-transform=1" -f null -
11087 Limits the pixel components values to the specified range [min, max].
11089 The filter accepts the following options:
11093 Lower bound. Defaults to the lowest allowed value for the input.
11096 Upper bound. Defaults to the highest allowed value for the input.
11099 Specify which planes will be processed. Defaults to all available.
11106 The filter accepts the following options:
11110 Set the number of loops. Setting this value to -1 will result in infinite loops.
11114 Set maximal size in number of frames. Default is 0.
11117 Set first frame of loop. Default is 0.
11122 Apply a 1D LUT to an input video.
11124 The filter accepts the following options:
11128 Set the 1D LUT file name.
11130 Currently supported formats:
11137 Select interpolation mode.
11139 Available values are:
11143 Use values from the nearest defined point.
11145 Interpolate values using the linear interpolation.
11147 Interpolate values using the cubic interpolation.
11154 Apply a 3D LUT to an input video.
11156 The filter accepts the following options:
11160 Set the 3D LUT file name.
11162 Currently supported formats:
11174 Select interpolation mode.
11176 Available values are:
11180 Use values from the nearest defined point.
11182 Interpolate values using the 8 points defining a cube.
11184 Interpolate values using a tetrahedron.
11188 This filter also supports the @ref{framesync} options.
11192 Turn certain luma values into transparency.
11194 The filter accepts the following options:
11198 Set the luma which will be used as base for transparency.
11199 Default value is @code{0}.
11202 Set the range of luma values to be keyed out.
11203 Default value is @code{0}.
11206 Set the range of softness. Default value is @code{0}.
11207 Use this to control gradual transition from zero to full transparency.
11210 @section lut, lutrgb, lutyuv
11212 Compute a look-up table for binding each pixel component input value
11213 to an output value, and apply it to the input video.
11215 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
11216 to an RGB input video.
11218 These filters accept the following parameters:
11221 set first pixel component expression
11223 set second pixel component expression
11225 set third pixel component expression
11227 set fourth pixel component expression, corresponds to the alpha component
11230 set red component expression
11232 set green component expression
11234 set blue component expression
11236 alpha component expression
11239 set Y/luminance component expression
11241 set U/Cb component expression
11243 set V/Cr component expression
11246 Each of them specifies the expression to use for computing the lookup table for
11247 the corresponding pixel component values.
11249 The exact component associated to each of the @var{c*} options depends on the
11252 The @var{lut} filter requires either YUV or RGB pixel formats in input,
11253 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
11255 The expressions can contain the following constants and functions:
11260 The input width and height.
11263 The input value for the pixel component.
11266 The input value, clipped to the @var{minval}-@var{maxval} range.
11269 The maximum value for the pixel component.
11272 The minimum value for the pixel component.
11275 The negated value for the pixel component value, clipped to the
11276 @var{minval}-@var{maxval} range; it corresponds to the expression
11277 "maxval-clipval+minval".
11280 The computed value in @var{val}, clipped to the
11281 @var{minval}-@var{maxval} range.
11283 @item gammaval(gamma)
11284 The computed gamma correction value of the pixel component value,
11285 clipped to the @var{minval}-@var{maxval} range. It corresponds to the
11287 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
11291 All expressions default to "val".
11293 @subsection Examples
11297 Negate input video:
11299 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
11300 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
11303 The above is the same as:
11305 lutrgb="r=negval:g=negval:b=negval"
11306 lutyuv="y=negval:u=negval:v=negval"
11316 Remove chroma components, turning the video into a graytone image:
11318 lutyuv="u=128:v=128"
11322 Apply a luma burning effect:
11328 Remove green and blue components:
11334 Set a constant alpha channel value on input:
11336 format=rgba,lutrgb=a="maxval-minval/2"
11340 Correct luminance gamma by a factor of 0.5:
11342 lutyuv=y=gammaval(0.5)
11346 Discard least significant bits of luma:
11348 lutyuv=y='bitand(val, 128+64+32)'
11352 Technicolor like effect:
11354 lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
11358 @section lut2, tlut2
11360 The @code{lut2} filter takes two input streams and outputs one
11363 The @code{tlut2} (time lut2) filter takes two consecutive frames
11364 from one single stream.
11366 This filter accepts the following parameters:
11369 set first pixel component expression
11371 set second pixel component expression
11373 set third pixel component expression
11375 set fourth pixel component expression, corresponds to the alpha component
11378 Each of them specifies the expression to use for computing the lookup table for
11379 the corresponding pixel component values.
11381 The exact component associated to each of the @var{c*} options depends on the
11384 The expressions can contain the following constants:
11389 The input width and height.
11392 The first input value for the pixel component.
11395 The second input value for the pixel component.
11398 The first input video bit depth.
11401 The second input video bit depth.
11404 All expressions default to "x".
11406 @subsection Examples
11410 Highlight differences between two RGB video streams:
11412 lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1)'
11416 Highlight differences between two YUV video streams:
11418 lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1)'
11422 Show max difference between two video streams:
11424 lut2='if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1)))'
11428 @section maskedclamp
11430 Clamp the first input stream with the second input and third input stream.
11432 Returns the value of first stream to be between second input
11433 stream - @code{undershoot} and third input stream + @code{overshoot}.
11435 This filter accepts the following options:
11438 Default value is @code{0}.
11441 Default value is @code{0}.
11444 Set which planes will be processed as bitmap, unprocessed planes will be
11445 copied from first stream.
11446 By default value 0xf, all planes will be processed.
11449 @section maskedmerge
11451 Merge the first input stream with the second input stream using per pixel
11452 weights in the third input stream.
11454 A value of 0 in the third stream pixel component means that pixel component
11455 from first stream is returned unchanged, while maximum value (eg. 255 for
11456 8-bit videos) means that pixel component from second stream is returned
11457 unchanged. Intermediate values define the amount of merging between both
11458 input stream's pixel components.
11460 This filter accepts the following options:
11463 Set which planes will be processed as bitmap, unprocessed planes will be
11464 copied from first stream.
11465 By default value 0xf, all planes will be processed.
11470 Apply motion-compensation deinterlacing.
11472 It needs one field per frame as input and must thus be used together
11473 with yadif=1/3 or equivalent.
11475 This filter accepts the following options:
11478 Set the deinterlacing mode.
11480 It accepts one of the following values:
11485 use iterative motion estimation
11487 like @samp{slow}, but use multiple reference frames.
11489 Default value is @samp{fast}.
11492 Set the picture field parity assumed for the input video. It must be
11493 one of the following values:
11497 assume top field first
11499 assume bottom field first
11502 Default value is @samp{bff}.
11505 Set per-block quantization parameter (QP) used by the internal
11508 Higher values should result in a smoother motion vector field but less
11509 optimal individual vectors. Default value is 1.
11512 @section mergeplanes
11514 Merge color channel components from several video streams.
11516 The filter accepts up to 4 input streams, and merge selected input
11517 planes to the output video.
11519 This filter accepts the following options:
11522 Set input to output plane mapping. Default is @code{0}.
11524 The mappings is specified as a bitmap. It should be specified as a
11525 hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
11526 mapping for the first plane of the output stream. 'A' sets the number of
11527 the input stream to use (from 0 to 3), and 'a' the plane number of the
11528 corresponding input to use (from 0 to 3). The rest of the mappings is
11529 similar, 'Bb' describes the mapping for the output stream second
11530 plane, 'Cc' describes the mapping for the output stream third plane and
11531 'Dd' describes the mapping for the output stream fourth plane.
11534 Set output pixel format. Default is @code{yuva444p}.
11537 @subsection Examples
11541 Merge three gray video streams of same width and height into single video stream:
11543 [a0][a1][a2]mergeplanes=0x001020:yuv444p
11547 Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
11549 [a0][a1]mergeplanes=0x00010210:yuva444p
11553 Swap Y and A plane in yuva444p stream:
11555 format=yuva444p,mergeplanes=0x03010200:yuva444p
11559 Swap U and V plane in yuv420p stream:
11561 format=yuv420p,mergeplanes=0x000201:yuv420p
11565 Cast a rgb24 clip to yuv444p:
11567 format=rgb24,mergeplanes=0x000102:yuv444p
11573 Estimate and export motion vectors using block matching algorithms.
11574 Motion vectors are stored in frame side data to be used by other filters.
11576 This filter accepts the following options:
11579 Specify the motion estimation method. Accepts one of the following values:
11583 Exhaustive search algorithm.
11585 Three step search algorithm.
11587 Two dimensional logarithmic search algorithm.
11589 New three step search algorithm.
11591 Four step search algorithm.
11593 Diamond search algorithm.
11595 Hexagon-based search algorithm.
11597 Enhanced predictive zonal search algorithm.
11599 Uneven multi-hexagon search algorithm.
11601 Default value is @samp{esa}.
11604 Macroblock size. Default @code{16}.
11607 Search parameter. Default @code{7}.
11610 @section midequalizer
11612 Apply Midway Image Equalization effect using two video streams.
11614 Midway Image Equalization adjusts a pair of images to have the same
11615 histogram, while maintaining their dynamics as much as possible. It's
11616 useful for e.g. matching exposures from a pair of stereo cameras.
11618 This filter has two inputs and one output, which must be of same pixel format, but
11619 may be of different sizes. The output of filter is first input adjusted with
11620 midway histogram of both inputs.
11622 This filter accepts the following option:
11626 Set which planes to process. Default is @code{15}, which is all available planes.
11629 @section minterpolate
11631 Convert the video to specified frame rate using motion interpolation.
11633 This filter accepts the following options:
11636 Specify the output frame rate. This can be rational e.g. @code{60000/1001}. Frames are dropped if @var{fps} is lower than source fps. Default @code{60}.
11639 Motion interpolation mode. Following values are accepted:
11642 Duplicate previous or next frame for interpolating new ones.
11644 Blend source frames. Interpolated frame is mean of previous and next frames.
11646 Motion compensated interpolation. Following options are effective when this mode is selected:
11650 Motion compensation mode. Following values are accepted:
11653 Overlapped block motion compensation.
11655 Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
11657 Default mode is @samp{obmc}.
11660 Motion estimation mode. Following values are accepted:
11663 Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
11665 Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
11667 Default mode is @samp{bilat}.
11670 The algorithm to be used for motion estimation. Following values are accepted:
11673 Exhaustive search algorithm.
11675 Three step search algorithm.
11677 Two dimensional logarithmic search algorithm.
11679 New three step search algorithm.
11681 Four step search algorithm.
11683 Diamond search algorithm.
11685 Hexagon-based search algorithm.
11687 Enhanced predictive zonal search algorithm.
11689 Uneven multi-hexagon search algorithm.
11691 Default algorithm is @samp{epzs}.
11694 Macroblock size. Default @code{16}.
11697 Motion estimation search parameter. Default @code{32}.
11700 Enable variable-size block motion compensation. Motion estimation is applied with smaller block sizes at object boundaries in order to make the them less blur. Default is @code{0} (disabled).
11705 Scene change detection method. Scene change leads motion vectors to be in random direction. Scene change detection replace interpolated frames by duplicate ones. May not be needed for other modes. Following values are accepted:
11708 Disable scene change detection.
11710 Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected.
11712 Default method is @samp{fdiff}.
11714 @item scd_threshold
11715 Scene change detection threshold. Default is @code{5.0}.
11720 Mix several video input streams into one video stream.
11722 A description of the accepted options follows.
11726 The number of inputs. If unspecified, it defaults to 2.
11729 Specify weight of each input video stream as sequence.
11730 Each weight is separated by space. If number of weights
11731 is smaller than number of @var{frames} last specified
11732 weight will be used for all remaining unset weights.
11735 Specify scale, if it is set it will be multiplied with sum
11736 of each weight multiplied with pixel values to give final destination
11737 pixel value. By default @var{scale} is auto scaled to sum of weights.
11740 Specify how end of stream is determined.
11743 The duration of the longest input. (default)
11746 The duration of the shortest input.
11749 The duration of the first input.
11753 @section mpdecimate
11755 Drop frames that do not differ greatly from the previous frame in
11756 order to reduce frame rate.
11758 The main use of this filter is for very-low-bitrate encoding
11759 (e.g. streaming over dialup modem), but it could in theory be used for
11760 fixing movies that were inverse-telecined incorrectly.
11762 A description of the accepted options follows.
11766 Set the maximum number of consecutive frames which can be dropped (if
11767 positive), or the minimum interval between dropped frames (if
11768 negative). If the value is 0, the frame is dropped disregarding the
11769 number of previous sequentially dropped frames.
11771 Default value is 0.
11776 Set the dropping threshold values.
11778 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
11779 represent actual pixel value differences, so a threshold of 64
11780 corresponds to 1 unit of difference for each pixel, or the same spread
11781 out differently over the block.
11783 A frame is a candidate for dropping if no 8x8 blocks differ by more
11784 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
11785 meaning the whole image) differ by more than a threshold of @option{lo}.
11787 Default value for @option{hi} is 64*12, default value for @option{lo} is
11788 64*5, and default value for @option{frac} is 0.33.
11794 Negate (invert) the input video.
11796 It accepts the following option:
11801 With value 1, it negates the alpha component, if present. Default value is 0.
11807 Denoise frames using Non-Local Means algorithm.
11809 Each pixel is adjusted by looking for other pixels with similar contexts. This
11810 context similarity is defined by comparing their surrounding patches of size
11811 @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
11814 Note that the research area defines centers for patches, which means some
11815 patches will be made of pixels outside that research area.
11817 The filter accepts the following options.
11821 Set denoising strength.
11827 Same as @option{p} but for chroma planes.
11829 The default value is @var{0} and means automatic.
11835 Same as @option{r} but for chroma planes.
11837 The default value is @var{0} and means automatic.
11842 Deinterlace video using neural network edge directed interpolation.
11844 This filter accepts the following options:
11848 Mandatory option, without binary file filter can not work.
11849 Currently file can be found here:
11850 https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
11853 Set which frames to deinterlace, by default it is @code{all}.
11854 Can be @code{all} or @code{interlaced}.
11857 Set mode of operation.
11859 Can be one of the following:
11863 Use frame flags, both fields.
11865 Use frame flags, single field.
11867 Use top field only.
11869 Use bottom field only.
11871 Use both fields, top first.
11873 Use both fields, bottom first.
11877 Set which planes to process, by default filter process all frames.
11880 Set size of local neighborhood around each pixel, used by the predictor neural
11883 Can be one of the following:
11896 Set the number of neurons in predictor neural network.
11897 Can be one of the following:
11908 Controls the number of different neural network predictions that are blended
11909 together to compute the final output value. Can be @code{fast}, default or
11913 Set which set of weights to use in the predictor.
11914 Can be one of the following:
11918 weights trained to minimize absolute error
11920 weights trained to minimize squared error
11924 Controls whether or not the prescreener neural network is used to decide
11925 which pixels should be processed by the predictor neural network and which
11926 can be handled by simple cubic interpolation.
11927 The prescreener is trained to know whether cubic interpolation will be
11928 sufficient for a pixel or whether it should be predicted by the predictor nn.
11929 The computational complexity of the prescreener nn is much less than that of
11930 the predictor nn. Since most pixels can be handled by cubic interpolation,
11931 using the prescreener generally results in much faster processing.
11932 The prescreener is pretty accurate, so the difference between using it and not
11933 using it is almost always unnoticeable.
11935 Can be one of the following:
11943 Default is @code{new}.
11946 Set various debugging flags.
11951 Force libavfilter not to use any of the specified pixel formats for the
11952 input to the next filter.
11954 It accepts the following parameters:
11958 A '|'-separated list of pixel format names, such as
11959 pix_fmts=yuv420p|monow|rgb24".
11963 @subsection Examples
11967 Force libavfilter to use a format different from @var{yuv420p} for the
11968 input to the vflip filter:
11970 noformat=pix_fmts=yuv420p,vflip
11974 Convert the input video to any of the formats not contained in the list:
11976 noformat=yuv420p|yuv444p|yuv410p
11982 Add noise on video input frame.
11984 The filter accepts the following options:
11992 Set noise seed for specific pixel component or all pixel components in case
11993 of @var{all_seed}. Default value is @code{123457}.
11995 @item all_strength, alls
11996 @item c0_strength, c0s
11997 @item c1_strength, c1s
11998 @item c2_strength, c2s
11999 @item c3_strength, c3s
12000 Set noise strength for specific pixel component or all pixel components in case
12001 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
12003 @item all_flags, allf
12004 @item c0_flags, c0f
12005 @item c1_flags, c1f
12006 @item c2_flags, c2f
12007 @item c3_flags, c3f
12008 Set pixel component flags or set flags for all components if @var{all_flags}.
12009 Available values for component flags are:
12012 averaged temporal noise (smoother)
12014 mix random noise with a (semi)regular pattern
12016 temporal noise (noise pattern changes between frames)
12018 uniform noise (gaussian otherwise)
12022 @subsection Examples
12024 Add temporal and uniform noise to input video:
12026 noise=alls=20:allf=t+u
12031 Normalize RGB video (aka histogram stretching, contrast stretching).
12032 See: https://en.wikipedia.org/wiki/Normalization_(image_processing)
12034 For each channel of each frame, the filter computes the input range and maps
12035 it linearly to the user-specified output range. The output range defaults
12036 to the full dynamic range from pure black to pure white.
12038 Temporal smoothing can be used on the input range to reduce flickering (rapid
12039 changes in brightness) caused when small dark or bright objects enter or leave
12040 the scene. This is similar to the auto-exposure (automatic gain control) on a
12041 video camera, and, like a video camera, it may cause a period of over- or
12042 under-exposure of the video.
12044 The R,G,B channels can be normalized independently, which may cause some
12045 color shifting, or linked together as a single channel, which prevents
12046 color shifting. Linked normalization preserves hue. Independent normalization
12047 does not, so it can be used to remove some color casts. Independent and linked
12048 normalization can be combined in any ratio.
12050 The normalize filter accepts the following options:
12055 Colors which define the output range. The minimum input value is mapped to
12056 the @var{blackpt}. The maximum input value is mapped to the @var{whitept}.
12057 The defaults are black and white respectively. Specifying white for
12058 @var{blackpt} and black for @var{whitept} will give color-inverted,
12059 normalized video. Shades of grey can be used to reduce the dynamic range
12060 (contrast). Specifying saturated colors here can create some interesting
12064 The number of previous frames to use for temporal smoothing. The input range
12065 of each channel is smoothed using a rolling average over the current frame
12066 and the @var{smoothing} previous frames. The default is 0 (no temporal
12070 Controls the ratio of independent (color shifting) channel normalization to
12071 linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully
12072 independent. Defaults to 1.0 (fully independent).
12075 Overall strength of the filter. 1.0 is full strength. 0.0 is a rather
12076 expensive no-op. Defaults to 1.0 (full strength).
12080 @subsection Examples
12082 Stretch video contrast to use the full dynamic range, with no temporal
12083 smoothing; may flicker depending on the source content:
12085 normalize=blackpt=black:whitept=white:smoothing=0
12088 As above, but with 50 frames of temporal smoothing; flicker should be
12089 reduced, depending on the source content:
12091 normalize=blackpt=black:whitept=white:smoothing=50
12094 As above, but with hue-preserving linked channel normalization:
12096 normalize=blackpt=black:whitept=white:smoothing=50:independence=0
12099 As above, but with half strength:
12101 normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
12104 Map the darkest input color to red, the brightest input color to cyan:
12106 normalize=blackpt=red:whitept=cyan
12111 Pass the video source unchanged to the output.
12114 Optical Character Recognition
12116 This filter uses Tesseract for optical character recognition. To enable
12117 compilation of this filter, you need to configure FFmpeg with
12118 @code{--enable-libtesseract}.
12120 It accepts the following options:
12124 Set datapath to tesseract data. Default is to use whatever was
12125 set at installation.
12128 Set language, default is "eng".
12131 Set character whitelist.
12134 Set character blacklist.
12137 The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
12141 Apply a video transform using libopencv.
12143 To enable this filter, install the libopencv library and headers and
12144 configure FFmpeg with @code{--enable-libopencv}.
12146 It accepts the following parameters:
12151 The name of the libopencv filter to apply.
12153 @item filter_params
12154 The parameters to pass to the libopencv filter. If not specified, the default
12155 values are assumed.
12159 Refer to the official libopencv documentation for more precise
12161 @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
12163 Several libopencv filters are supported; see the following subsections.
12168 Dilate an image by using a specific structuring element.
12169 It corresponds to the libopencv function @code{cvDilate}.
12171 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
12173 @var{struct_el} represents a structuring element, and has the syntax:
12174 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
12176 @var{cols} and @var{rows} represent the number of columns and rows of
12177 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
12178 point, and @var{shape} the shape for the structuring element. @var{shape}
12179 must be "rect", "cross", "ellipse", or "custom".
12181 If the value for @var{shape} is "custom", it must be followed by a
12182 string of the form "=@var{filename}". The file with name
12183 @var{filename} is assumed to represent a binary image, with each
12184 printable character corresponding to a bright pixel. When a custom
12185 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
12186 or columns and rows of the read file are assumed instead.
12188 The default value for @var{struct_el} is "3x3+0x0/rect".
12190 @var{nb_iterations} specifies the number of times the transform is
12191 applied to the image, and defaults to 1.
12195 # Use the default values
12198 # Dilate using a structuring element with a 5x5 cross, iterating two times
12199 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
12201 # Read the shape from the file diamond.shape, iterating two times.
12202 # The file diamond.shape may contain a pattern of characters like this
12208 # The specified columns and rows are ignored
12209 # but the anchor point coordinates are not
12210 ocv=dilate:0x0+2x2/custom=diamond.shape|2
12215 Erode an image by using a specific structuring element.
12216 It corresponds to the libopencv function @code{cvErode}.
12218 It accepts the parameters: @var{struct_el}:@var{nb_iterations},
12219 with the same syntax and semantics as the @ref{dilate} filter.
12223 Smooth the input video.
12225 The filter takes the following parameters:
12226 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
12228 @var{type} is the type of smooth filter to apply, and must be one of
12229 the following values: "blur", "blur_no_scale", "median", "gaussian",
12230 or "bilateral". The default value is "gaussian".
12232 The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
12233 depend on the smooth type. @var{param1} and
12234 @var{param2} accept integer positive values or 0. @var{param3} and
12235 @var{param4} accept floating point values.
12237 The default value for @var{param1} is 3. The default value for the
12238 other parameters is 0.
12240 These parameters correspond to the parameters assigned to the
12241 libopencv function @code{cvSmooth}.
12243 @section oscilloscope
12245 2D Video Oscilloscope.
12247 Useful to measure spatial impulse, step responses, chroma delays, etc.
12249 It accepts the following parameters:
12253 Set scope center x position.
12256 Set scope center y position.
12259 Set scope size, relative to frame diagonal.
12262 Set scope tilt/rotation.
12268 Set trace center x position.
12271 Set trace center y position.
12274 Set trace width, relative to width of frame.
12277 Set trace height, relative to height of frame.
12280 Set which components to trace. By default it traces first three components.
12283 Draw trace grid. By default is enabled.
12286 Draw some statistics. By default is enabled.
12289 Draw scope. By default is enabled.
12292 @subsection Examples
12296 Inspect full first row of video frame.
12298 oscilloscope=x=0.5:y=0:s=1
12302 Inspect full last row of video frame.
12304 oscilloscope=x=0.5:y=1:s=1
12308 Inspect full 5th line of video frame of height 1080.
12310 oscilloscope=x=0.5:y=5/1080:s=1
12314 Inspect full last column of video frame.
12316 oscilloscope=x=1:y=0.5:s=1:t=1
12324 Overlay one video on top of another.
12326 It takes two inputs and has one output. The first input is the "main"
12327 video on which the second input is overlaid.
12329 It accepts the following parameters:
12331 A description of the accepted options follows.
12336 Set the expression for the x and y coordinates of the overlaid video
12337 on the main video. Default value is "0" for both expressions. In case
12338 the expression is invalid, it is set to a huge value (meaning that the
12339 overlay will not be displayed within the output visible area).
12342 See @ref{framesync}.
12345 Set when the expressions for @option{x}, and @option{y} are evaluated.
12347 It accepts the following values:
12350 only evaluate expressions once during the filter initialization or
12351 when a command is processed
12354 evaluate expressions for each incoming frame
12357 Default value is @samp{frame}.
12360 See @ref{framesync}.
12363 Set the format for the output video.
12365 It accepts the following values:
12368 force YUV420 output
12371 force YUV422 output
12374 force YUV444 output
12377 force packed RGB output
12380 force planar RGB output
12383 automatically pick format
12386 Default value is @samp{yuv420}.
12389 See @ref{framesync}.
12392 Set format of alpha of the overlaid video, it can be @var{straight} or
12393 @var{premultiplied}. Default is @var{straight}.
12396 The @option{x}, and @option{y} expressions can contain the following
12402 The main input width and height.
12406 The overlay input width and height.
12410 The computed values for @var{x} and @var{y}. They are evaluated for
12415 horizontal and vertical chroma subsample values of the output
12416 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
12420 the number of input frame, starting from 0
12423 the position in the file of the input frame, NAN if unknown
12426 The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
12430 This filter also supports the @ref{framesync} options.
12432 Note that the @var{n}, @var{pos}, @var{t} variables are available only
12433 when evaluation is done @emph{per frame}, and will evaluate to NAN
12434 when @option{eval} is set to @samp{init}.
12436 Be aware that frames are taken from each input video in timestamp
12437 order, hence, if their initial timestamps differ, it is a good idea
12438 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
12439 have them begin in the same zero timestamp, as the example for
12440 the @var{movie} filter does.
12442 You can chain together more overlays but you should test the
12443 efficiency of such approach.
12445 @subsection Commands
12447 This filter supports the following commands:
12451 Modify the x and y of the overlay input.
12452 The command accepts the same syntax of the corresponding option.
12454 If the specified expression is not valid, it is kept at its current
12458 @subsection Examples
12462 Draw the overlay at 10 pixels from the bottom right corner of the main
12465 overlay=main_w-overlay_w-10:main_h-overlay_h-10
12468 Using named options the example above becomes:
12470 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
12474 Insert a transparent PNG logo in the bottom left corner of the input,
12475 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
12477 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
12481 Insert 2 different transparent PNG logos (second logo on bottom
12482 right corner) using the @command{ffmpeg} tool:
12484 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
12488 Add a transparent color layer on top of the main video; @code{WxH}
12489 must specify the size of the main input to the overlay filter:
12491 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
12495 Play an original video and a filtered version (here with the deshake
12496 filter) side by side using the @command{ffplay} tool:
12498 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
12501 The above command is the same as:
12503 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
12507 Make a sliding overlay appearing from the left to the right top part of the
12508 screen starting since time 2:
12510 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
12514 Compose output by putting two input videos side to side:
12516 ffmpeg -i left.avi -i right.avi -filter_complex "
12517 nullsrc=size=200x100 [background];
12518 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
12519 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
12520 [background][left] overlay=shortest=1 [background+left];
12521 [background+left][right] overlay=shortest=1:x=100 [left+right]
12526 Mask 10-20 seconds of a video by applying the delogo filter to a section
12528 ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
12529 -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]'
12534 Chain several overlays in cascade:
12536 nullsrc=s=200x200 [bg];
12537 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
12538 [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
12539 [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
12540 [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
12541 [in3] null, [mid2] overlay=100:100 [out0]
12548 Apply Overcomplete Wavelet denoiser.
12550 The filter accepts the following options:
12556 Larger depth values will denoise lower frequency components more, but
12557 slow down filtering.
12559 Must be an int in the range 8-16, default is @code{8}.
12561 @item luma_strength, ls
12564 Must be a double value in the range 0-1000, default is @code{1.0}.
12566 @item chroma_strength, cs
12567 Set chroma strength.
12569 Must be a double value in the range 0-1000, default is @code{1.0}.
12575 Add paddings to the input image, and place the original input at the
12576 provided @var{x}, @var{y} coordinates.
12578 It accepts the following parameters:
12583 Specify an expression for the size of the output image with the
12584 paddings added. If the value for @var{width} or @var{height} is 0, the
12585 corresponding input size is used for the output.
12587 The @var{width} expression can reference the value set by the
12588 @var{height} expression, and vice versa.
12590 The default value of @var{width} and @var{height} is 0.
12594 Specify the offsets to place the input image at within the padded area,
12595 with respect to the top/left border of the output image.
12597 The @var{x} expression can reference the value set by the @var{y}
12598 expression, and vice versa.
12600 The default value of @var{x} and @var{y} is 0.
12602 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
12603 so the input image is centered on the padded area.
12606 Specify the color of the padded area. For the syntax of this option,
12607 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
12608 manual,ffmpeg-utils}.
12610 The default value of @var{color} is "black".
12613 Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression.
12615 It accepts the following values:
12619 Only evaluate expressions once during the filter initialization or when
12620 a command is processed.
12623 Evaluate expressions for each incoming frame.
12627 Default value is @samp{init}.
12630 Pad to aspect instead to a resolution.
12634 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
12635 options are expressions containing the following constants:
12640 The input video width and height.
12644 These are the same as @var{in_w} and @var{in_h}.
12648 The output width and height (the size of the padded area), as
12649 specified by the @var{width} and @var{height} expressions.
12653 These are the same as @var{out_w} and @var{out_h}.
12657 The x and y offsets as specified by the @var{x} and @var{y}
12658 expressions, or NAN if not yet specified.
12661 same as @var{iw} / @var{ih}
12664 input sample aspect ratio
12667 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
12671 The horizontal and vertical chroma subsample values. For example for the
12672 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
12675 @subsection Examples
12679 Add paddings with the color "violet" to the input video. The output video
12680 size is 640x480, and the top-left corner of the input video is placed at
12683 pad=640:480:0:40:violet
12686 The example above is equivalent to the following command:
12688 pad=width=640:height=480:x=0:y=40:color=violet
12692 Pad the input to get an output with dimensions increased by 3/2,
12693 and put the input video at the center of the padded area:
12695 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
12699 Pad the input to get a squared output with size equal to the maximum
12700 value between the input width and height, and put the input video at
12701 the center of the padded area:
12703 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
12707 Pad the input to get a final w/h ratio of 16:9:
12709 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
12713 In case of anamorphic video, in order to set the output display aspect
12714 correctly, it is necessary to use @var{sar} in the expression,
12715 according to the relation:
12717 (ih * X / ih) * sar = output_dar
12718 X = output_dar / sar
12721 Thus the previous example needs to be modified to:
12723 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
12727 Double the output size and put the input video in the bottom-right
12728 corner of the output padded area:
12730 pad="2*iw:2*ih:ow-iw:oh-ih"
12734 @anchor{palettegen}
12735 @section palettegen
12737 Generate one palette for a whole video stream.
12739 It accepts the following options:
12743 Set the maximum number of colors to quantize in the palette.
12744 Note: the palette will still contain 256 colors; the unused palette entries
12747 @item reserve_transparent
12748 Create a palette of 255 colors maximum and reserve the last one for
12749 transparency. Reserving the transparency color is useful for GIF optimization.
12750 If not set, the maximum of colors in the palette will be 256. You probably want
12751 to disable this option for a standalone image.
12754 @item transparency_color
12755 Set the color that will be used as background for transparency.
12758 Set statistics mode.
12760 It accepts the following values:
12763 Compute full frame histograms.
12765 Compute histograms only for the part that differs from previous frame. This
12766 might be relevant to give more importance to the moving part of your input if
12767 the background is static.
12769 Compute new histogram for each frame.
12772 Default value is @var{full}.
12775 The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
12776 (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
12777 color quantization of the palette. This information is also visible at
12778 @var{info} logging level.
12780 @subsection Examples
12784 Generate a representative palette of a given video using @command{ffmpeg}:
12786 ffmpeg -i input.mkv -vf palettegen palette.png
12790 @section paletteuse
12792 Use a palette to downsample an input video stream.
12794 The filter takes two inputs: one video stream and a palette. The palette must
12795 be a 256 pixels image.
12797 It accepts the following options:
12801 Select dithering mode. Available algorithms are:
12804 Ordered 8x8 bayer dithering (deterministic)
12806 Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
12807 Note: this dithering is sometimes considered "wrong" and is included as a
12809 @item floyd_steinberg
12810 Floyd and Steingberg dithering (error diffusion)
12812 Frankie Sierra dithering v2 (error diffusion)
12814 Frankie Sierra dithering v2 "Lite" (error diffusion)
12817 Default is @var{sierra2_4a}.
12820 When @var{bayer} dithering is selected, this option defines the scale of the
12821 pattern (how much the crosshatch pattern is visible). A low value means more
12822 visible pattern for less banding, and higher value means less visible pattern
12823 at the cost of more banding.
12825 The option must be an integer value in the range [0,5]. Default is @var{2}.
12828 If set, define the zone to process
12832 Only the changing rectangle will be reprocessed. This is similar to GIF
12833 cropping/offsetting compression mechanism. This option can be useful for speed
12834 if only a part of the image is changing, and has use cases such as limiting the
12835 scope of the error diffusal @option{dither} to the rectangle that bounds the
12836 moving scene (it leads to more deterministic output if the scene doesn't change
12837 much, and as a result less moving noise and better GIF compression).
12840 Default is @var{none}.
12843 Take new palette for each output frame.
12845 @item alpha_threshold
12846 Sets the alpha threshold for transparency. Alpha values above this threshold
12847 will be treated as completely opaque, and values below this threshold will be
12848 treated as completely transparent.
12850 The option must be an integer value in the range [0,255]. Default is @var{128}.
12853 @subsection Examples
12857 Use a palette (generated for example with @ref{palettegen}) to encode a GIF
12858 using @command{ffmpeg}:
12860 ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
12864 @section perspective
12866 Correct perspective of video not recorded perpendicular to the screen.
12868 A description of the accepted parameters follows.
12879 Set coordinates expression for top left, top right, bottom left and bottom right corners.
12880 Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
12881 If the @code{sense} option is set to @code{source}, then the specified points will be sent
12882 to the corners of the destination. If the @code{sense} option is set to @code{destination},
12883 then the corners of the source will be sent to the specified coordinates.
12885 The expressions can use the following variables:
12890 the width and height of video frame.
12894 Output frame count.
12897 @item interpolation
12898 Set interpolation for perspective correction.
12900 It accepts the following values:
12906 Default value is @samp{linear}.
12909 Set interpretation of coordinate options.
12911 It accepts the following values:
12915 Send point in the source specified by the given coordinates to
12916 the corners of the destination.
12918 @item 1, destination
12920 Send the corners of the source to the point in the destination specified
12921 by the given coordinates.
12923 Default value is @samp{source}.
12927 Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
12929 It accepts the following values:
12932 only evaluate expressions once during the filter initialization or
12933 when a command is processed
12936 evaluate expressions for each incoming frame
12939 Default value is @samp{init}.
12944 Delay interlaced video by one field time so that the field order changes.
12946 The intended use is to fix PAL movies that have been captured with the
12947 opposite field order to the film-to-video transfer.
12949 A description of the accepted parameters follows.
12955 It accepts the following values:
12958 Capture field order top-first, transfer bottom-first.
12959 Filter will delay the bottom field.
12962 Capture field order bottom-first, transfer top-first.
12963 Filter will delay the top field.
12966 Capture and transfer with the same field order. This mode only exists
12967 for the documentation of the other options to refer to, but if you
12968 actually select it, the filter will faithfully do nothing.
12971 Capture field order determined automatically by field flags, transfer
12973 Filter selects among @samp{t} and @samp{b} modes on a frame by frame
12974 basis using field flags. If no field information is available,
12975 then this works just like @samp{u}.
12978 Capture unknown or varying, transfer opposite.
12979 Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
12980 analyzing the images and selecting the alternative that produces best
12981 match between the fields.
12984 Capture top-first, transfer unknown or varying.
12985 Filter selects among @samp{t} and @samp{p} using image analysis.
12988 Capture bottom-first, transfer unknown or varying.
12989 Filter selects among @samp{b} and @samp{p} using image analysis.
12992 Capture determined by field flags, transfer unknown or varying.
12993 Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
12994 image analysis. If no field information is available, then this works just
12995 like @samp{U}. This is the default mode.
12998 Both capture and transfer unknown or varying.
12999 Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
13003 @section pixdesctest
13005 Pixel format descriptor test filter, mainly useful for internal
13006 testing. The output video should be equal to the input video.
13010 format=monow, pixdesctest
13013 can be used to test the monowhite pixel format descriptor definition.
13017 Display sample values of color channels. Mainly useful for checking color
13018 and levels. Minimum supported resolution is 640x480.
13020 The filters accept the following options:
13024 Set scope X position, relative offset on X axis.
13027 Set scope Y position, relative offset on Y axis.
13036 Set window opacity. This window also holds statistics about pixel area.
13039 Set window X position, relative offset on X axis.
13042 Set window Y position, relative offset on Y axis.
13047 Enable the specified chain of postprocessing subfilters using libpostproc. This
13048 library should be automatically selected with a GPL build (@code{--enable-gpl}).
13049 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
13050 Each subfilter and some options have a short and a long name that can be used
13051 interchangeably, i.e. dr/dering are the same.
13053 The filters accept the following options:
13057 Set postprocessing subfilters string.
13060 All subfilters share common options to determine their scope:
13064 Honor the quality commands for this subfilter.
13067 Do chrominance filtering, too (default).
13070 Do luminance filtering only (no chrominance).
13073 Do chrominance filtering only (no luminance).
13076 These options can be appended after the subfilter name, separated by a '|'.
13078 Available subfilters are:
13081 @item hb/hdeblock[|difference[|flatness]]
13082 Horizontal deblocking filter
13085 Difference factor where higher values mean more deblocking (default: @code{32}).
13087 Flatness threshold where lower values mean more deblocking (default: @code{39}).
13090 @item vb/vdeblock[|difference[|flatness]]
13091 Vertical deblocking filter
13094 Difference factor where higher values mean more deblocking (default: @code{32}).
13096 Flatness threshold where lower values mean more deblocking (default: @code{39}).
13099 @item ha/hadeblock[|difference[|flatness]]
13100 Accurate horizontal deblocking filter
13103 Difference factor where higher values mean more deblocking (default: @code{32}).
13105 Flatness threshold where lower values mean more deblocking (default: @code{39}).
13108 @item va/vadeblock[|difference[|flatness]]
13109 Accurate vertical deblocking filter
13112 Difference factor where higher values mean more deblocking (default: @code{32}).
13114 Flatness threshold where lower values mean more deblocking (default: @code{39}).
13118 The horizontal and vertical deblocking filters share the difference and
13119 flatness values so you cannot set different horizontal and vertical
13123 @item h1/x1hdeblock
13124 Experimental horizontal deblocking filter
13126 @item v1/x1vdeblock
13127 Experimental vertical deblocking filter
13132 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
13135 larger -> stronger filtering
13137 larger -> stronger filtering
13139 larger -> stronger filtering
13142 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
13145 Stretch luminance to @code{0-255}.
13148 @item lb/linblenddeint
13149 Linear blend deinterlacing filter that deinterlaces the given block by
13150 filtering all lines with a @code{(1 2 1)} filter.
13152 @item li/linipoldeint
13153 Linear interpolating deinterlacing filter that deinterlaces the given block by
13154 linearly interpolating every second line.
13156 @item ci/cubicipoldeint
13157 Cubic interpolating deinterlacing filter deinterlaces the given block by
13158 cubically interpolating every second line.
13160 @item md/mediandeint
13161 Median deinterlacing filter that deinterlaces the given block by applying a
13162 median filter to every second line.
13164 @item fd/ffmpegdeint
13165 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
13166 second line with a @code{(-1 4 2 4 -1)} filter.
13169 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
13170 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
13172 @item fq/forceQuant[|quantizer]
13173 Overrides the quantizer table from the input with the constant quantizer you
13181 Default pp filter combination (@code{hb|a,vb|a,dr|a})
13184 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
13187 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
13190 @subsection Examples
13194 Apply horizontal and vertical deblocking, deringing and automatic
13195 brightness/contrast:
13201 Apply default filters without brightness/contrast correction:
13207 Apply default filters and temporal denoiser:
13209 pp=default/tmpnoise|1|2|3
13213 Apply deblocking on luminance only, and switch vertical deblocking on or off
13214 automatically depending on available CPU time:
13221 Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
13222 similar to spp = 6 with 7 point DCT, where only the center sample is
13225 The filter accepts the following options:
13229 Force a constant quantization parameter. It accepts an integer in range
13230 0 to 63. If not set, the filter will use the QP from the video stream
13234 Set thresholding mode. Available modes are:
13238 Set hard thresholding.
13240 Set soft thresholding (better de-ringing effect, but likely blurrier).
13242 Set medium thresholding (good results, default).
13246 @section premultiply
13247 Apply alpha premultiply effect to input video stream using first plane
13248 of second stream as alpha.
13250 Both streams must have same dimensions and same pixel format.
13252 The filter accepts the following option:
13256 Set which planes will be processed, unprocessed planes will be copied.
13257 By default value 0xf, all planes will be processed.
13260 Do not require 2nd input for processing, instead use alpha plane from input stream.
13264 Apply prewitt operator to input video stream.
13266 The filter accepts the following option:
13270 Set which planes will be processed, unprocessed planes will be copied.
13271 By default value 0xf, all planes will be processed.
13274 Set value which will be multiplied with filtered result.
13277 Set value which will be added to filtered result.
13280 @anchor{program_opencl}
13281 @section program_opencl
13283 Filter video using an OpenCL program.
13288 OpenCL program source file.
13291 Kernel name in program.
13294 Number of inputs to the filter. Defaults to 1.
13297 Size of output frames. Defaults to the same as the first input.
13301 The program source file must contain a kernel function with the given name,
13302 which will be run once for each plane of the output. Each run on a plane
13303 gets enqueued as a separate 2D global NDRange with one work-item for each
13304 pixel to be generated. The global ID offset for each work-item is therefore
13305 the coordinates of a pixel in the destination image.
13307 The kernel function needs to take the following arguments:
13310 Destination image, @var{__write_only image2d_t}.
13312 This image will become the output; the kernel should write all of it.
13314 Frame index, @var{unsigned int}.
13316 This is a counter starting from zero and increasing by one for each frame.
13318 Source images, @var{__read_only image2d_t}.
13320 These are the most recent images on each input. The kernel may read from
13321 them to generate the output, but they can't be written to.
13328 Copy the input to the output (output must be the same size as the input).
13330 __kernel void copy(__write_only image2d_t destination,
13331 unsigned int index,
13332 __read_only image2d_t source)
13334 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
13336 int2 location = (int2)(get_global_id(0), get_global_id(1));
13338 float4 value = read_imagef(source, sampler, location);
13340 write_imagef(destination, location, value);
13345 Apply a simple transformation, rotating the input by an amount increasing
13346 with the index counter. Pixel values are linearly interpolated by the
13347 sampler, and the output need not have the same dimensions as the input.
13349 __kernel void rotate_image(__write_only image2d_t dst,
13350 unsigned int index,
13351 __read_only image2d_t src)
13353 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
13354 CLK_FILTER_LINEAR);
13356 float angle = (float)index / 100.0f;
13358 float2 dst_dim = convert_float2(get_image_dim(dst));
13359 float2 src_dim = convert_float2(get_image_dim(src));
13361 float2 dst_cen = dst_dim / 2.0f;
13362 float2 src_cen = src_dim / 2.0f;
13364 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
13366 float2 dst_pos = convert_float2(dst_loc) - dst_cen;
13368 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
13369 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
13371 src_pos = src_pos * src_dim / dst_dim;
13373 float2 src_loc = src_pos + src_cen;
13375 if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
13376 src_loc.x > src_dim.x || src_loc.y > src_dim.y)
13377 write_imagef(dst, dst_loc, 0.5f);
13379 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
13384 Blend two inputs together, with the amount of each input used varying
13385 with the index counter.
13387 __kernel void blend_images(__write_only image2d_t dst,
13388 unsigned int index,
13389 __read_only image2d_t src1,
13390 __read_only image2d_t src2)
13392 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
13393 CLK_FILTER_LINEAR);
13395 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
13397 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
13398 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
13399 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
13401 float4 val1 = read_imagef(src1, sampler, src1_loc);
13402 float4 val2 = read_imagef(src2, sampler, src2_loc);
13404 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
13410 @section pseudocolor
13412 Alter frame colors in video with pseudocolors.
13414 This filter accept the following options:
13418 set pixel first component expression
13421 set pixel second component expression
13424 set pixel third component expression
13427 set pixel fourth component expression, corresponds to the alpha component
13430 set component to use as base for altering colors
13433 Each of them specifies the expression to use for computing the lookup table for
13434 the corresponding pixel component values.
13436 The expressions can contain the following constants and functions:
13441 The input width and height.
13444 The input value for the pixel component.
13446 @item ymin, umin, vmin, amin
13447 The minimum allowed component value.
13449 @item ymax, umax, vmax, amax
13450 The maximum allowed component value.
13453 All expressions default to "val".
13455 @subsection Examples
13459 Change too high luma values to gradient:
13461 pseudocolor="'if(between(val,ymax,amax),lerp(ymin,ymax,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(umax,umin,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(vmin,vmax,(val-ymax)/(amax-ymax)),-1):-1'"
13467 Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
13468 Ratio) between two input videos.
13470 This filter takes in input two input videos, the first input is
13471 considered the "main" source and is passed unchanged to the
13472 output. The second input is used as a "reference" video for computing
13475 Both video inputs must have the same resolution and pixel format for
13476 this filter to work correctly. Also it assumes that both inputs
13477 have the same number of frames, which are compared one by one.
13479 The obtained average PSNR is printed through the logging system.
13481 The filter stores the accumulated MSE (mean squared error) of each
13482 frame, and at the end of the processing it is averaged across all frames
13483 equally, and the following formula is applied to obtain the PSNR:
13486 PSNR = 10*log10(MAX^2/MSE)
13489 Where MAX is the average of the maximum values of each component of the
13492 The description of the accepted parameters follows.
13495 @item stats_file, f
13496 If specified the filter will use the named file to save the PSNR of
13497 each individual frame. When filename equals "-" the data is sent to
13500 @item stats_version
13501 Specifies which version of the stats file format to use. Details of
13502 each format are written below.
13503 Default value is 1.
13505 @item stats_add_max
13506 Determines whether the max value is output to the stats log.
13507 Default value is 0.
13508 Requires stats_version >= 2. If this is set and stats_version < 2,
13509 the filter will return an error.
13512 This filter also supports the @ref{framesync} options.
13514 The file printed if @var{stats_file} is selected, contains a sequence of
13515 key/value pairs of the form @var{key}:@var{value} for each compared
13518 If a @var{stats_version} greater than 1 is specified, a header line precedes
13519 the list of per-frame-pair stats, with key value pairs following the frame
13520 format with the following parameters:
13523 @item psnr_log_version
13524 The version of the log file format. Will match @var{stats_version}.
13527 A comma separated list of the per-frame-pair parameters included in
13531 A description of each shown per-frame-pair parameter follows:
13535 sequential number of the input frame, starting from 1
13538 Mean Square Error pixel-by-pixel average difference of the compared
13539 frames, averaged over all the image components.
13541 @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
13542 Mean Square Error pixel-by-pixel average difference of the compared
13543 frames for the component specified by the suffix.
13545 @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
13546 Peak Signal to Noise ratio of the compared frames for the component
13547 specified by the suffix.
13549 @item max_avg, max_y, max_u, max_v
13550 Maximum allowed value for each channel, and average over all
13556 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
13557 [main][ref] psnr="stats_file=stats.log" [out]
13560 On this example the input file being processed is compared with the
13561 reference file @file{ref_movie.mpg}. The PSNR of each individual frame
13562 is stored in @file{stats.log}.
13567 Pulldown reversal (inverse telecine) filter, capable of handling mixed
13568 hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
13571 The pullup filter is designed to take advantage of future context in making
13572 its decisions. This filter is stateless in the sense that it does not lock
13573 onto a pattern to follow, but it instead looks forward to the following
13574 fields in order to identify matches and rebuild progressive frames.
13576 To produce content with an even framerate, insert the fps filter after
13577 pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
13578 @code{fps=24} for 30fps and the (rare) telecined 25fps input.
13580 The filter accepts the following options:
13587 These options set the amount of "junk" to ignore at the left, right, top, and
13588 bottom of the image, respectively. Left and right are in units of 8 pixels,
13589 while top and bottom are in units of 2 lines.
13590 The default is 8 pixels on each side.
13593 Set the strict breaks. Setting this option to 1 will reduce the chances of
13594 filter generating an occasional mismatched frame, but it may also cause an
13595 excessive number of frames to be dropped during high motion sequences.
13596 Conversely, setting it to -1 will make filter match fields more easily.
13597 This may help processing of video where there is slight blurring between
13598 the fields, but may also cause there to be interlaced frames in the output.
13599 Default value is @code{0}.
13602 Set the metric plane to use. It accepts the following values:
13608 Use chroma blue plane.
13611 Use chroma red plane.
13614 This option may be set to use chroma plane instead of the default luma plane
13615 for doing filter's computations. This may improve accuracy on very clean
13616 source material, but more likely will decrease accuracy, especially if there
13617 is chroma noise (rainbow effect) or any grayscale video.
13618 The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
13619 load and make pullup usable in realtime on slow machines.
13622 For best results (without duplicated frames in the output file) it is
13623 necessary to change the output frame rate. For example, to inverse
13624 telecine NTSC input:
13626 ffmpeg -i input -vf pullup -r 24000/1001 ...
13631 Change video quantization parameters (QP).
13633 The filter accepts the following option:
13637 Set expression for quantization parameter.
13640 The expression is evaluated through the eval API and can contain, among others,
13641 the following constants:
13645 1 if index is not 129, 0 otherwise.
13648 Sequential index starting from -129 to 128.
13651 @subsection Examples
13655 Some equation like:
13663 Flush video frames from internal cache of frames into a random order.
13664 No frame is discarded.
13665 Inspired by @ref{frei0r} nervous filter.
13669 Set size in number of frames of internal cache, in range from @code{2} to
13670 @code{512}. Default is @code{30}.
13673 Set seed for random number generator, must be an integer included between
13674 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
13675 less than @code{0}, the filter will try to use a good random seed on a
13679 @section readeia608
13681 Read closed captioning (EIA-608) information from the top lines of a video frame.
13683 This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and
13684 @code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line
13685 with EIA-608 data (starting from 0). A description of each metadata value follows:
13688 @item lavfi.readeia608.X.cc
13689 The two bytes stored as EIA-608 data (printed in hexadecimal).
13691 @item lavfi.readeia608.X.line
13692 The number of the line on which the EIA-608 data was identified and read.
13695 This filter accepts the following options:
13699 Set the line to start scanning for EIA-608 data. Default is @code{0}.
13702 Set the line to end scanning for EIA-608 data. Default is @code{29}.
13705 Set minimal acceptable amplitude change for sync codes detection.
13706 Default is @code{0.2}. Allowed range is @code{[0.001 - 1]}.
13709 Set the ratio of width reserved for sync code detection.
13710 Default is @code{0.27}. Allowed range is @code{[0.01 - 0.7]}.
13713 Set the max peaks height difference for sync code detection.
13714 Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
13717 Set max peaks period difference for sync code detection.
13718 Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
13721 Set the first two max start code bits differences.
13722 Default is @code{0.02}. Allowed range is @code{[0.0 - 0.5]}.
13725 Set the minimum ratio of bits height compared to 3rd start code bit.
13726 Default is @code{0.75}. Allowed range is @code{[0.01 - 1]}.
13729 Set the white color threshold. Default is @code{0.35}. Allowed range is @code{[0.1 - 1]}.
13732 Set the black color threshold. Default is @code{0.15}. Allowed range is @code{[0.0 - 0.5]}.
13735 Enable checking the parity bit. In the event of a parity error, the filter will output
13736 @code{0x00} for that character. Default is false.
13739 @subsection Examples
13743 Output a csv with presentation time and the first two lines of identified EIA-608 captioning data.
13745 ffprobe -f lavfi -i movie=captioned_video.mov,readeia608 -show_entries frame=pkt_pts_time:frame_tags=lavfi.readeia608.0.cc,lavfi.readeia608.1.cc -of csv
13751 Read vertical interval timecode (VITC) information from the top lines of a
13754 The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
13755 timecode value, if a valid timecode has been detected. Further metadata key
13756 @code{lavfi.readvitc.found} is set to 0/1 depending on whether
13757 timecode data has been found or not.
13759 This filter accepts the following options:
13763 Set the maximum number of lines to scan for VITC data. If the value is set to
13764 @code{-1} the full video frame is scanned. Default is @code{45}.
13767 Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
13768 default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
13771 Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
13772 default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
13775 @subsection Examples
13779 Detect and draw VITC data onto the video frame; if no valid VITC is detected,
13780 draw @code{--:--:--:--} as a placeholder:
13782 ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
13788 Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
13790 Destination pixel at position (X, Y) will be picked from source (x, y) position
13791 where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
13792 value for pixel will be used for destination pixel.
13794 Xmap and Ymap input video streams must be of same dimensions. Output video stream
13795 will have Xmap/Ymap video stream dimensions.
13796 Xmap and Ymap input video streams are 16bit depth, single channel.
13798 @section removegrain
13800 The removegrain filter is a spatial denoiser for progressive video.
13804 Set mode for the first plane.
13807 Set mode for the second plane.
13810 Set mode for the third plane.
13813 Set mode for the fourth plane.
13816 Range of mode is from 0 to 24. Description of each mode follows:
13820 Leave input plane unchanged. Default.
13823 Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
13826 Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
13829 Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
13832 Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
13833 This is equivalent to a median filter.
13836 Line-sensitive clipping giving the minimal change.
13839 Line-sensitive clipping, intermediate.
13842 Line-sensitive clipping, intermediate.
13845 Line-sensitive clipping, intermediate.
13848 Line-sensitive clipping on a line where the neighbours pixels are the closest.
13851 Replaces the target pixel with the closest neighbour.
13854 [1 2 1] horizontal and vertical kernel blur.
13860 Bob mode, interpolates top field from the line where the neighbours
13861 pixels are the closest.
13864 Bob mode, interpolates bottom field from the line where the neighbours
13865 pixels are the closest.
13868 Bob mode, interpolates top field. Same as 13 but with a more complicated
13869 interpolation formula.
13872 Bob mode, interpolates bottom field. Same as 14 but with a more complicated
13873 interpolation formula.
13876 Clips the pixel with the minimum and maximum of respectively the maximum and
13877 minimum of each pair of opposite neighbour pixels.
13880 Line-sensitive clipping using opposite neighbours whose greatest distance from
13881 the current pixel is minimal.
13884 Replaces the pixel with the average of its 8 neighbours.
13887 Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
13890 Clips pixels using the averages of opposite neighbour.
13893 Same as mode 21 but simpler and faster.
13896 Small edge and halo removal, but reputed useless.
13902 @section removelogo
13904 Suppress a TV station logo, using an image file to determine which
13905 pixels comprise the logo. It works by filling in the pixels that
13906 comprise the logo with neighboring pixels.
13908 The filter accepts the following options:
13912 Set the filter bitmap file, which can be any image format supported by
13913 libavformat. The width and height of the image file must match those of the
13914 video stream being processed.
13917 Pixels in the provided bitmap image with a value of zero are not
13918 considered part of the logo, non-zero pixels are considered part of
13919 the logo. If you use white (255) for the logo and black (0) for the
13920 rest, you will be safe. For making the filter bitmap, it is
13921 recommended to take a screen capture of a black frame with the logo
13922 visible, and then using a threshold filter followed by the erode
13923 filter once or twice.
13925 If needed, little splotches can be fixed manually. Remember that if
13926 logo pixels are not covered, the filter quality will be much
13927 reduced. Marking too many pixels as part of the logo does not hurt as
13928 much, but it will increase the amount of blurring needed to cover over
13929 the image and will destroy more information than necessary, and extra
13930 pixels will slow things down on a large logo.
13932 @section repeatfields
13934 This filter uses the repeat_field flag from the Video ES headers and hard repeats
13935 fields based on its value.
13939 Reverse a video clip.
13941 Warning: This filter requires memory to buffer the entire clip, so trimming
13944 @subsection Examples
13948 Take the first 5 seconds of a clip, and reverse it.
13955 Apply roberts cross operator to input video stream.
13957 The filter accepts the following option:
13961 Set which planes will be processed, unprocessed planes will be copied.
13962 By default value 0xf, all planes will be processed.
13965 Set value which will be multiplied with filtered result.
13968 Set value which will be added to filtered result.
13973 Rotate video by an arbitrary angle expressed in radians.
13975 The filter accepts the following options:
13977 A description of the optional parameters follows.
13980 Set an expression for the angle by which to rotate the input video
13981 clockwise, expressed as a number of radians. A negative value will
13982 result in a counter-clockwise rotation. By default it is set to "0".
13984 This expression is evaluated for each frame.
13987 Set the output width expression, default value is "iw".
13988 This expression is evaluated just once during configuration.
13991 Set the output height expression, default value is "ih".
13992 This expression is evaluated just once during configuration.
13995 Enable bilinear interpolation if set to 1, a value of 0 disables
13996 it. Default value is 1.
13999 Set the color used to fill the output area not covered by the rotated
14000 image. For the general syntax of this option, check the
14001 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
14002 If the special value "none" is selected then no
14003 background is printed (useful for example if the background is never shown).
14005 Default value is "black".
14008 The expressions for the angle and the output size can contain the
14009 following constants and functions:
14013 sequential number of the input frame, starting from 0. It is always NAN
14014 before the first frame is filtered.
14017 time in seconds of the input frame, it is set to 0 when the filter is
14018 configured. It is always NAN before the first frame is filtered.
14022 horizontal and vertical chroma subsample values. For example for the
14023 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14027 the input video width and height
14031 the output width and height, that is the size of the padded area as
14032 specified by the @var{width} and @var{height} expressions
14036 the minimal width/height required for completely containing the input
14037 video rotated by @var{a} radians.
14039 These are only available when computing the @option{out_w} and
14040 @option{out_h} expressions.
14043 @subsection Examples
14047 Rotate the input by PI/6 radians clockwise:
14053 Rotate the input by PI/6 radians counter-clockwise:
14059 Rotate the input by 45 degrees clockwise:
14065 Apply a constant rotation with period T, starting from an angle of PI/3:
14067 rotate=PI/3+2*PI*t/T
14071 Make the input video rotation oscillating with a period of T
14072 seconds and an amplitude of A radians:
14074 rotate=A*sin(2*PI/T*t)
14078 Rotate the video, output size is chosen so that the whole rotating
14079 input video is always completely contained in the output:
14081 rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
14085 Rotate the video, reduce the output size so that no background is ever
14088 rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
14092 @subsection Commands
14094 The filter supports the following commands:
14098 Set the angle expression.
14099 The command accepts the same syntax of the corresponding option.
14101 If the specified expression is not valid, it is kept at its current
14107 Apply Shape Adaptive Blur.
14109 The filter accepts the following options:
14112 @item luma_radius, lr
14113 Set luma blur filter strength, must be a value in range 0.1-4.0, default
14114 value is 1.0. A greater value will result in a more blurred image, and
14115 in slower processing.
14117 @item luma_pre_filter_radius, lpfr
14118 Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
14121 @item luma_strength, ls
14122 Set luma maximum difference between pixels to still be considered, must
14123 be a value in the 0.1-100.0 range, default value is 1.0.
14125 @item chroma_radius, cr
14126 Set chroma blur filter strength, must be a value in range -0.9-4.0. A
14127 greater value will result in a more blurred image, and in slower
14130 @item chroma_pre_filter_radius, cpfr
14131 Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
14133 @item chroma_strength, cs
14134 Set chroma maximum difference between pixels to still be considered,
14135 must be a value in the -0.9-100.0 range.
14138 Each chroma option value, if not explicitly specified, is set to the
14139 corresponding luma option value.
14144 Scale (resize) the input video, using the libswscale library.
14146 The scale filter forces the output display aspect ratio to be the same
14147 of the input, by changing the output sample aspect ratio.
14149 If the input image format is different from the format requested by
14150 the next filter, the scale filter will convert the input to the
14153 @subsection Options
14154 The filter accepts the following options, or any of the options
14155 supported by the libswscale scaler.
14157 See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
14158 the complete list of scaler options.
14163 Set the output video dimension expression. Default value is the input
14166 If the @var{width} or @var{w} value is 0, the input width is used for
14167 the output. If the @var{height} or @var{h} value is 0, the input height
14168 is used for the output.
14170 If one and only one of the values is -n with n >= 1, the scale filter
14171 will use a value that maintains the aspect ratio of the input image,
14172 calculated from the other specified dimension. After that it will,
14173 however, make sure that the calculated dimension is divisible by n and
14174 adjust the value if necessary.
14176 If both values are -n with n >= 1, the behavior will be identical to
14177 both values being set to 0 as previously detailed.
14179 See below for the list of accepted constants for use in the dimension
14183 Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
14187 Only evaluate expressions once during the filter initialization or when a command is processed.
14190 Evaluate expressions for each incoming frame.
14194 Default value is @samp{init}.
14198 Set the interlacing mode. It accepts the following values:
14202 Force interlaced aware scaling.
14205 Do not apply interlaced scaling.
14208 Select interlaced aware scaling depending on whether the source frames
14209 are flagged as interlaced or not.
14212 Default value is @samp{0}.
14215 Set libswscale scaling flags. See
14216 @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
14217 complete list of values. If not explicitly specified the filter applies
14221 @item param0, param1
14222 Set libswscale input parameters for scaling algorithms that need them. See
14223 @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
14224 complete documentation. If not explicitly specified the filter applies
14230 Set the video size. For the syntax of this option, check the
14231 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
14233 @item in_color_matrix
14234 @item out_color_matrix
14235 Set in/output YCbCr color space type.
14237 This allows the autodetected value to be overridden as well as allows forcing
14238 a specific value used for the output and encoder.
14240 If not specified, the color space type depends on the pixel format.
14246 Choose automatically.
14249 Format conforming to International Telecommunication Union (ITU)
14250 Recommendation BT.709.
14253 Set color space conforming to the United States Federal Communications
14254 Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
14257 Set color space conforming to:
14261 ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
14264 ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
14267 Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
14272 Set color space conforming to SMPTE ST 240:1999.
14277 Set in/output YCbCr sample range.
14279 This allows the autodetected value to be overridden as well as allows forcing
14280 a specific value used for the output and encoder. If not specified, the
14281 range depends on the pixel format. Possible values:
14285 Choose automatically.
14288 Set full range (0-255 in case of 8-bit luma).
14290 @item mpeg/limited/tv
14291 Set "MPEG" range (16-235 in case of 8-bit luma).
14294 @item force_original_aspect_ratio
14295 Enable decreasing or increasing output video width or height if necessary to
14296 keep the original aspect ratio. Possible values:
14300 Scale the video as specified and disable this feature.
14303 The output video dimensions will automatically be decreased if needed.
14306 The output video dimensions will automatically be increased if needed.
14310 One useful instance of this option is that when you know a specific device's
14311 maximum allowed resolution, you can use this to limit the output video to
14312 that, while retaining the aspect ratio. For example, device A allows
14313 1280x720 playback, and your video is 1920x800. Using this option (set it to
14314 decrease) and specifying 1280x720 to the command line makes the output
14317 Please note that this is a different thing than specifying -1 for @option{w}
14318 or @option{h}, you still need to specify the output resolution for this option
14323 The values of the @option{w} and @option{h} options are expressions
14324 containing the following constants:
14329 The input width and height
14333 These are the same as @var{in_w} and @var{in_h}.
14337 The output (scaled) width and height
14341 These are the same as @var{out_w} and @var{out_h}
14344 The same as @var{iw} / @var{ih}
14347 input sample aspect ratio
14350 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
14354 horizontal and vertical input chroma subsample values. For example for the
14355 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14359 horizontal and vertical output chroma subsample values. For example for the
14360 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14363 @subsection Examples
14367 Scale the input video to a size of 200x100
14372 This is equivalent to:
14383 Specify a size abbreviation for the output size:
14388 which can also be written as:
14394 Scale the input to 2x:
14396 scale=w=2*iw:h=2*ih
14400 The above is the same as:
14402 scale=2*in_w:2*in_h
14406 Scale the input to 2x with forced interlaced scaling:
14408 scale=2*iw:2*ih:interl=1
14412 Scale the input to half size:
14414 scale=w=iw/2:h=ih/2
14418 Increase the width, and set the height to the same size:
14424 Seek Greek harmony:
14431 Increase the height, and set the width to 3/2 of the height:
14433 scale=w=3/2*oh:h=3/5*ih
14437 Increase the size, making the size a multiple of the chroma
14440 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
14444 Increase the width to a maximum of 500 pixels,
14445 keeping the same aspect ratio as the input:
14447 scale=w='min(500\, iw*3/2):h=-1'
14451 Make pixels square by combining scale and setsar:
14453 scale='trunc(ih*dar):ih',setsar=1/1
14457 Make pixels square by combining scale and setsar,
14458 making sure the resulting resolution is even (required by some codecs):
14460 scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1
14464 @subsection Commands
14466 This filter supports the following commands:
14470 Set the output video dimension expression.
14471 The command accepts the same syntax of the corresponding option.
14473 If the specified expression is not valid, it is kept at its current
14479 Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
14480 format conversion on CUDA video frames. Setting the output width and height
14481 works in the same way as for the @var{scale} filter.
14483 The following additional options are accepted:
14486 The pixel format of the output CUDA frames. If set to the string "same" (the
14487 default), the input format will be kept. Note that automatic format negotiation
14488 and conversion is not yet supported for hardware frames
14491 The interpolation algorithm used for resizing. One of the following:
14498 @item cubic2p_bspline
14499 2-parameter cubic (B=1, C=0)
14501 @item cubic2p_catmullrom
14502 2-parameter cubic (B=0, C=1/2)
14504 @item cubic2p_b05c03
14505 2-parameter cubic (B=1/2, C=3/10)
14517 Scale (resize) the input video, based on a reference video.
14519 See the scale filter for available options, scale2ref supports the same but
14520 uses the reference video instead of the main input as basis. scale2ref also
14521 supports the following additional constants for the @option{w} and
14522 @option{h} options:
14527 The main input video's width and height
14530 The same as @var{main_w} / @var{main_h}
14533 The main input video's sample aspect ratio
14535 @item main_dar, mdar
14536 The main input video's display aspect ratio. Calculated from
14537 @code{(main_w / main_h) * main_sar}.
14541 The main input video's horizontal and vertical chroma subsample values.
14542 For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub}
14546 @subsection Examples
14550 Scale a subtitle stream (b) to match the main video (a) in size before overlaying
14552 'scale2ref[b][a];[a][b]overlay'
14556 @anchor{selectivecolor}
14557 @section selectivecolor
14559 Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
14560 as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
14561 by the "purity" of the color (that is, how saturated it already is).
14563 This filter is similar to the Adobe Photoshop Selective Color tool.
14565 The filter accepts the following options:
14568 @item correction_method
14569 Select color correction method.
14571 Available values are:
14574 Specified adjustments are applied "as-is" (added/subtracted to original pixel
14577 Specified adjustments are relative to the original component value.
14579 Default is @code{absolute}.
14581 Adjustments for red pixels (pixels where the red component is the maximum)
14583 Adjustments for yellow pixels (pixels where the blue component is the minimum)
14585 Adjustments for green pixels (pixels where the green component is the maximum)
14587 Adjustments for cyan pixels (pixels where the red component is the minimum)
14589 Adjustments for blue pixels (pixels where the blue component is the maximum)
14591 Adjustments for magenta pixels (pixels where the green component is the minimum)
14593 Adjustments for white pixels (pixels where all components are greater than 128)
14595 Adjustments for all pixels except pure black and pure white
14597 Adjustments for black pixels (pixels where all components are lesser than 128)
14599 Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
14602 All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
14603 4 space separated floating point adjustment values in the [-1,1] range,
14604 respectively to adjust the amount of cyan, magenta, yellow and black for the
14605 pixels of its range.
14607 @subsection Examples
14611 Increase cyan by 50% and reduce yellow by 33% in every green areas, and
14612 increase magenta by 27% in blue areas:
14614 selectivecolor=greens=.5 0 -.33 0:blues=0 .27
14618 Use a Photoshop selective color preset:
14620 selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
14624 @anchor{separatefields}
14625 @section separatefields
14627 The @code{separatefields} takes a frame-based video input and splits
14628 each frame into its components fields, producing a new half height clip
14629 with twice the frame rate and twice the frame count.
14631 This filter use field-dominance information in frame to decide which
14632 of each pair of fields to place first in the output.
14633 If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
14635 @section setdar, setsar
14637 The @code{setdar} filter sets the Display Aspect Ratio for the filter
14640 This is done by changing the specified Sample (aka Pixel) Aspect
14641 Ratio, according to the following equation:
14643 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
14646 Keep in mind that the @code{setdar} filter does not modify the pixel
14647 dimensions of the video frame. Also, the display aspect ratio set by
14648 this filter may be changed by later filters in the filterchain,
14649 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
14652 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
14653 the filter output video.
14655 Note that as a consequence of the application of this filter, the
14656 output display aspect ratio will change according to the equation
14659 Keep in mind that the sample aspect ratio set by the @code{setsar}
14660 filter may be changed by later filters in the filterchain, e.g. if
14661 another "setsar" or a "setdar" filter is applied.
14663 It accepts the following parameters:
14666 @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
14667 Set the aspect ratio used by the filter.
14669 The parameter can be a floating point number string, an expression, or
14670 a string of the form @var{num}:@var{den}, where @var{num} and
14671 @var{den} are the numerator and denominator of the aspect ratio. If
14672 the parameter is not specified, it is assumed the value "0".
14673 In case the form "@var{num}:@var{den}" is used, the @code{:} character
14677 Set the maximum integer value to use for expressing numerator and
14678 denominator when reducing the expressed aspect ratio to a rational.
14679 Default value is @code{100}.
14683 The parameter @var{sar} is an expression containing
14684 the following constants:
14688 These are approximated values for the mathematical constants e
14689 (Euler's number), pi (Greek pi), and phi (the golden ratio).
14692 The input width and height.
14695 These are the same as @var{w} / @var{h}.
14698 The input sample aspect ratio.
14701 The input display aspect ratio. It is the same as
14702 (@var{w} / @var{h}) * @var{sar}.
14705 Horizontal and vertical chroma subsample values. For example, for the
14706 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14709 @subsection Examples
14714 To change the display aspect ratio to 16:9, specify one of the following:
14721 To change the sample aspect ratio to 10:11, specify:
14727 To set a display aspect ratio of 16:9, and specify a maximum integer value of
14728 1000 in the aspect ratio reduction, use the command:
14730 setdar=ratio=16/9:max=1000
14738 Force field for the output video frame.
14740 The @code{setfield} filter marks the interlace type field for the
14741 output frames. It does not change the input frame, but only sets the
14742 corresponding property, which affects how the frame is treated by
14743 following filters (e.g. @code{fieldorder} or @code{yadif}).
14745 The filter accepts the following options:
14750 Available values are:
14754 Keep the same field property.
14757 Mark the frame as bottom-field-first.
14760 Mark the frame as top-field-first.
14763 Mark the frame as progressive.
14769 Show a line containing various information for each input video frame.
14770 The input video is not modified.
14772 The shown line contains a sequence of key/value pairs of the form
14773 @var{key}:@var{value}.
14775 The following values are shown in the output:
14779 The (sequential) number of the input frame, starting from 0.
14782 The Presentation TimeStamp of the input frame, expressed as a number of
14783 time base units. The time base unit depends on the filter input pad.
14786 The Presentation TimeStamp of the input frame, expressed as a number of
14790 The position of the frame in the input stream, or -1 if this information is
14791 unavailable and/or meaningless (for example in case of synthetic video).
14794 The pixel format name.
14797 The sample aspect ratio of the input frame, expressed in the form
14798 @var{num}/@var{den}.
14801 The size of the input frame. For the syntax of this option, check the
14802 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
14805 The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
14806 for bottom field first).
14809 This is 1 if the frame is a key frame, 0 otherwise.
14812 The picture type of the input frame ("I" for an I-frame, "P" for a
14813 P-frame, "B" for a B-frame, or "?" for an unknown type).
14814 Also refer to the documentation of the @code{AVPictureType} enum and of
14815 the @code{av_get_picture_type_char} function defined in
14816 @file{libavutil/avutil.h}.
14819 The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
14821 @item plane_checksum
14822 The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
14823 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
14826 @section showpalette
14828 Displays the 256 colors palette of each frame. This filter is only relevant for
14829 @var{pal8} pixel format frames.
14831 It accepts the following option:
14835 Set the size of the box used to represent one palette color entry. Default is
14836 @code{30} (for a @code{30x30} pixel box).
14839 @section shuffleframes
14841 Reorder and/or duplicate and/or drop video frames.
14843 It accepts the following parameters:
14847 Set the destination indexes of input frames.
14848 This is space or '|' separated list of indexes that maps input frames to output
14849 frames. Number of indexes also sets maximal value that each index may have.
14850 '-1' index have special meaning and that is to drop frame.
14853 The first frame has the index 0. The default is to keep the input unchanged.
14855 @subsection Examples
14859 Swap second and third frame of every three frames of the input:
14861 ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
14865 Swap 10th and 1st frame of every ten frames of the input:
14867 ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
14871 @section shuffleplanes
14873 Reorder and/or duplicate video planes.
14875 It accepts the following parameters:
14880 The index of the input plane to be used as the first output plane.
14883 The index of the input plane to be used as the second output plane.
14886 The index of the input plane to be used as the third output plane.
14889 The index of the input plane to be used as the fourth output plane.
14893 The first plane has the index 0. The default is to keep the input unchanged.
14895 @subsection Examples
14899 Swap the second and third planes of the input:
14901 ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
14905 @anchor{signalstats}
14906 @section signalstats
14907 Evaluate various visual metrics that assist in determining issues associated
14908 with the digitization of analog video media.
14910 By default the filter will log these metadata values:
14914 Display the minimal Y value contained within the input frame. Expressed in
14918 Display the Y value at the 10% percentile within the input frame. Expressed in
14922 Display the average Y value within the input frame. Expressed in range of
14926 Display the Y value at the 90% percentile within the input frame. Expressed in
14930 Display the maximum Y value contained within the input frame. Expressed in
14934 Display the minimal U value contained within the input frame. Expressed in
14938 Display the U value at the 10% percentile within the input frame. Expressed in
14942 Display the average U value within the input frame. Expressed in range of
14946 Display the U value at the 90% percentile within the input frame. Expressed in
14950 Display the maximum U value contained within the input frame. Expressed in
14954 Display the minimal V value contained within the input frame. Expressed in
14958 Display the V value at the 10% percentile within the input frame. Expressed in
14962 Display the average V value within the input frame. Expressed in range of
14966 Display the V value at the 90% percentile within the input frame. Expressed in
14970 Display the maximum V value contained within the input frame. Expressed in
14974 Display the minimal saturation value contained within the input frame.
14975 Expressed in range of [0-~181.02].
14978 Display the saturation value at the 10% percentile within the input frame.
14979 Expressed in range of [0-~181.02].
14982 Display the average saturation value within the input frame. Expressed in range
14986 Display the saturation value at the 90% percentile within the input frame.
14987 Expressed in range of [0-~181.02].
14990 Display the maximum saturation value contained within the input frame.
14991 Expressed in range of [0-~181.02].
14994 Display the median value for hue within the input frame. Expressed in range of
14998 Display the average value for hue within the input frame. Expressed in range of
15002 Display the average of sample value difference between all values of the Y
15003 plane in the current frame and corresponding values of the previous input frame.
15004 Expressed in range of [0-255].
15007 Display the average of sample value difference between all values of the U
15008 plane in the current frame and corresponding values of the previous input frame.
15009 Expressed in range of [0-255].
15012 Display the average of sample value difference between all values of the V
15013 plane in the current frame and corresponding values of the previous input frame.
15014 Expressed in range of [0-255].
15017 Display bit depth of Y plane in current frame.
15018 Expressed in range of [0-16].
15021 Display bit depth of U plane in current frame.
15022 Expressed in range of [0-16].
15025 Display bit depth of V plane in current frame.
15026 Expressed in range of [0-16].
15029 The filter accepts the following options:
15035 @option{stat} specify an additional form of image analysis.
15036 @option{out} output video with the specified type of pixel highlighted.
15038 Both options accept the following values:
15042 Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
15043 unlike the neighboring pixels of the same field. Examples of temporal outliers
15044 include the results of video dropouts, head clogs, or tape tracking issues.
15047 Identify @var{vertical line repetition}. Vertical line repetition includes
15048 similar rows of pixels within a frame. In born-digital video vertical line
15049 repetition is common, but this pattern is uncommon in video digitized from an
15050 analog source. When it occurs in video that results from the digitization of an
15051 analog source it can indicate concealment from a dropout compensator.
15054 Identify pixels that fall outside of legal broadcast range.
15058 Set the highlight color for the @option{out} option. The default color is
15062 @subsection Examples
15066 Output data of various video metrics:
15068 ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
15072 Output specific data about the minimum and maximum values of the Y plane per frame:
15074 ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
15078 Playback video while highlighting pixels that are outside of broadcast range in red.
15080 ffplay example.mov -vf signalstats="out=brng:color=red"
15084 Playback video with signalstats metadata drawn over the frame.
15086 ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
15089 The contents of signalstat_drawtext.txt used in the command are:
15092 Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
15093 U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
15094 V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
15095 saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
15103 Calculates the MPEG-7 Video Signature. The filter can handle more than one
15104 input. In this case the matching between the inputs can be calculated additionally.
15105 The filter always passes through the first input. The signature of each stream can
15106 be written into a file.
15108 It accepts the following options:
15112 Enable or disable the matching process.
15114 Available values are:
15118 Disable the calculation of a matching (default).
15120 Calculate the matching for the whole video and output whether the whole video
15121 matches or only parts.
15123 Calculate only until a matching is found or the video ends. Should be faster in
15128 Set the number of inputs. The option value must be a non negative integer.
15129 Default value is 1.
15132 Set the path to which the output is written. If there is more than one input,
15133 the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive
15134 integer), that will be replaced with the input number. If no filename is
15135 specified, no output will be written. This is the default.
15138 Choose the output format.
15140 Available values are:
15144 Use the specified binary representation (default).
15146 Use the specified xml representation.
15150 Set threshold to detect one word as similar. The option value must be an integer
15151 greater than zero. The default value is 9000.
15154 Set threshold to detect all words as similar. The option value must be an integer
15155 greater than zero. The default value is 60000.
15158 Set threshold to detect frames as similar. The option value must be an integer
15159 greater than zero. The default value is 116.
15162 Set the minimum length of a sequence in frames to recognize it as matching
15163 sequence. The option value must be a non negative integer value.
15164 The default value is 0.
15167 Set the minimum relation, that matching frames to all frames must have.
15168 The option value must be a double value between 0 and 1. The default value is 0.5.
15171 @subsection Examples
15175 To calculate the signature of an input video and store it in signature.bin:
15177 ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
15181 To detect whether two videos match and store the signatures in XML format in
15182 signature0.xml and signature1.xml:
15184 ffmpeg -i input1.mkv -i input2.mkv -filter_complex "[0:v][1:v] signature=nb_inputs=2:detectmode=full:format=xml:filename=signature%d.xml" -map :v -f null -
15192 Blur the input video without impacting the outlines.
15194 It accepts the following options:
15197 @item luma_radius, lr
15198 Set the luma radius. The option value must be a float number in
15199 the range [0.1,5.0] that specifies the variance of the gaussian filter
15200 used to blur the image (slower if larger). Default value is 1.0.
15202 @item luma_strength, ls
15203 Set the luma strength. The option value must be a float number
15204 in the range [-1.0,1.0] that configures the blurring. A value included
15205 in [0.0,1.0] will blur the image whereas a value included in
15206 [-1.0,0.0] will sharpen the image. Default value is 1.0.
15208 @item luma_threshold, lt
15209 Set the luma threshold used as a coefficient to determine
15210 whether a pixel should be blurred or not. The option value must be an
15211 integer in the range [-30,30]. A value of 0 will filter all the image,
15212 a value included in [0,30] will filter flat areas and a value included
15213 in [-30,0] will filter edges. Default value is 0.
15215 @item chroma_radius, cr
15216 Set the chroma radius. The option value must be a float number in
15217 the range [0.1,5.0] that specifies the variance of the gaussian filter
15218 used to blur the image (slower if larger). Default value is @option{luma_radius}.
15220 @item chroma_strength, cs
15221 Set the chroma strength. The option value must be a float number
15222 in the range [-1.0,1.0] that configures the blurring. A value included
15223 in [0.0,1.0] will blur the image whereas a value included in
15224 [-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}.
15226 @item chroma_threshold, ct
15227 Set the chroma threshold used as a coefficient to determine
15228 whether a pixel should be blurred or not. The option value must be an
15229 integer in the range [-30,30]. A value of 0 will filter all the image,
15230 a value included in [0,30] will filter flat areas and a value included
15231 in [-30,0] will filter edges. Default value is @option{luma_threshold}.
15234 If a chroma option is not explicitly set, the corresponding luma value
15239 Obtain the SSIM (Structural SImilarity Metric) between two input videos.
15241 This filter takes in input two input videos, the first input is
15242 considered the "main" source and is passed unchanged to the
15243 output. The second input is used as a "reference" video for computing
15246 Both video inputs must have the same resolution and pixel format for
15247 this filter to work correctly. Also it assumes that both inputs
15248 have the same number of frames, which are compared one by one.
15250 The filter stores the calculated SSIM of each frame.
15252 The description of the accepted parameters follows.
15255 @item stats_file, f
15256 If specified the filter will use the named file to save the SSIM of
15257 each individual frame. When filename equals "-" the data is sent to
15261 The file printed if @var{stats_file} is selected, contains a sequence of
15262 key/value pairs of the form @var{key}:@var{value} for each compared
15265 A description of each shown parameter follows:
15269 sequential number of the input frame, starting from 1
15271 @item Y, U, V, R, G, B
15272 SSIM of the compared frames for the component specified by the suffix.
15275 SSIM of the compared frames for the whole frame.
15278 Same as above but in dB representation.
15281 This filter also supports the @ref{framesync} options.
15285 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
15286 [main][ref] ssim="stats_file=stats.log" [out]
15289 On this example the input file being processed is compared with the
15290 reference file @file{ref_movie.mpg}. The SSIM of each individual frame
15291 is stored in @file{stats.log}.
15293 Another example with both psnr and ssim at same time:
15295 ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
15300 Convert between different stereoscopic image formats.
15302 The filters accept the following options:
15306 Set stereoscopic image format of input.
15308 Available values for input image formats are:
15311 side by side parallel (left eye left, right eye right)
15314 side by side crosseye (right eye left, left eye right)
15317 side by side parallel with half width resolution
15318 (left eye left, right eye right)
15321 side by side crosseye with half width resolution
15322 (right eye left, left eye right)
15325 above-below (left eye above, right eye below)
15328 above-below (right eye above, left eye below)
15331 above-below with half height resolution
15332 (left eye above, right eye below)
15335 above-below with half height resolution
15336 (right eye above, left eye below)
15339 alternating frames (left eye first, right eye second)
15342 alternating frames (right eye first, left eye second)
15345 interleaved rows (left eye has top row, right eye starts on next row)
15348 interleaved rows (right eye has top row, left eye starts on next row)
15351 interleaved columns, left eye first
15354 interleaved columns, right eye first
15356 Default value is @samp{sbsl}.
15360 Set stereoscopic image format of output.
15364 side by side parallel (left eye left, right eye right)
15367 side by side crosseye (right eye left, left eye right)
15370 side by side parallel with half width resolution
15371 (left eye left, right eye right)
15374 side by side crosseye with half width resolution
15375 (right eye left, left eye right)
15378 above-below (left eye above, right eye below)
15381 above-below (right eye above, left eye below)
15384 above-below with half height resolution
15385 (left eye above, right eye below)
15388 above-below with half height resolution
15389 (right eye above, left eye below)
15392 alternating frames (left eye first, right eye second)
15395 alternating frames (right eye first, left eye second)
15398 interleaved rows (left eye has top row, right eye starts on next row)
15401 interleaved rows (right eye has top row, left eye starts on next row)
15404 anaglyph red/blue gray
15405 (red filter on left eye, blue filter on right eye)
15408 anaglyph red/green gray
15409 (red filter on left eye, green filter on right eye)
15412 anaglyph red/cyan gray
15413 (red filter on left eye, cyan filter on right eye)
15416 anaglyph red/cyan half colored
15417 (red filter on left eye, cyan filter on right eye)
15420 anaglyph red/cyan color
15421 (red filter on left eye, cyan filter on right eye)
15424 anaglyph red/cyan color optimized with the least squares projection of dubois
15425 (red filter on left eye, cyan filter on right eye)
15428 anaglyph green/magenta gray
15429 (green filter on left eye, magenta filter on right eye)
15432 anaglyph green/magenta half colored
15433 (green filter on left eye, magenta filter on right eye)
15436 anaglyph green/magenta colored
15437 (green filter on left eye, magenta filter on right eye)
15440 anaglyph green/magenta color optimized with the least squares projection of dubois
15441 (green filter on left eye, magenta filter on right eye)
15444 anaglyph yellow/blue gray
15445 (yellow filter on left eye, blue filter on right eye)
15448 anaglyph yellow/blue half colored
15449 (yellow filter on left eye, blue filter on right eye)
15452 anaglyph yellow/blue colored
15453 (yellow filter on left eye, blue filter on right eye)
15456 anaglyph yellow/blue color optimized with the least squares projection of dubois
15457 (yellow filter on left eye, blue filter on right eye)
15460 mono output (left eye only)
15463 mono output (right eye only)
15466 checkerboard, left eye first
15469 checkerboard, right eye first
15472 interleaved columns, left eye first
15475 interleaved columns, right eye first
15481 Default value is @samp{arcd}.
15484 @subsection Examples
15488 Convert input video from side by side parallel to anaglyph yellow/blue dubois:
15494 Convert input video from above below (left eye above, right eye below) to side by side crosseye.
15500 @section streamselect, astreamselect
15501 Select video or audio streams.
15503 The filter accepts the following options:
15507 Set number of inputs. Default is 2.
15510 Set input indexes to remap to outputs.
15513 @subsection Commands
15515 The @code{streamselect} and @code{astreamselect} filter supports the following
15520 Set input indexes to remap to outputs.
15523 @subsection Examples
15527 Select first 5 seconds 1st stream and rest of time 2nd stream:
15529 sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
15533 Same as above, but for audio:
15535 asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
15540 Apply sobel operator to input video stream.
15542 The filter accepts the following option:
15546 Set which planes will be processed, unprocessed planes will be copied.
15547 By default value 0xf, all planes will be processed.
15550 Set value which will be multiplied with filtered result.
15553 Set value which will be added to filtered result.
15559 Apply a simple postprocessing filter that compresses and decompresses the image
15560 at several (or - in the case of @option{quality} level @code{6} - all) shifts
15561 and average the results.
15563 The filter accepts the following options:
15567 Set quality. This option defines the number of levels for averaging. It accepts
15568 an integer in the range 0-6. If set to @code{0}, the filter will have no
15569 effect. A value of @code{6} means the higher quality. For each increment of
15570 that value the speed drops by a factor of approximately 2. Default value is
15574 Force a constant quantization parameter. If not set, the filter will use the QP
15575 from the video stream (if available).
15578 Set thresholding mode. Available modes are:
15582 Set hard thresholding (default).
15584 Set soft thresholding (better de-ringing effect, but likely blurrier).
15587 @item use_bframe_qp
15588 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
15589 option may cause flicker since the B-Frames have often larger QP. Default is
15590 @code{0} (not enabled).
15595 Scale the input by applying one of the super-resolution methods based on
15596 convolutional neural networks.
15598 Training scripts as well as scripts for model generation are provided in
15599 the repository at @url{https://github.com/HighVoltageRocknRoll/sr.git}.
15601 The filter accepts the following options:
15605 Specify which super-resolution model to use. This option accepts the following values:
15609 Super-Resolution Convolutional Neural Network model.
15610 See @url{https://arxiv.org/abs/1501.00092}.
15613 Efficient Sub-Pixel Convolutional Neural Network model.
15614 See @url{https://arxiv.org/abs/1609.05158}.
15618 Default value is @samp{srcnn}.
15621 Specify which DNN backend to use for model loading and execution. This option accepts
15622 the following values:
15626 Native implementation of DNN loading and execution.
15629 TensorFlow backend. To enable this backend you
15630 need to install the TensorFlow for C library (see
15631 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
15632 @code{--enable-libtensorflow}
15636 Default value is @samp{native}.
15639 Set scale factor for SRCNN model, for which custom model file was provided.
15640 Allowed values are @code{2}, @code{3} and @code{4}. Default value is @code{2}.
15641 Scale factor is necessary for SRCNN model, because it accepts input upscaled
15642 using bicubic upscaling with proper scale factor.
15644 @item model_filename
15645 Set path to model file specifying network architecture and its parameters.
15646 Note that different backends use different file formats. TensorFlow backend
15647 can load files for both formats, while native backend can load files for only
15655 Draw subtitles on top of input video using the libass library.
15657 To enable compilation of this filter you need to configure FFmpeg with
15658 @code{--enable-libass}. This filter also requires a build with libavcodec and
15659 libavformat to convert the passed subtitles file to ASS (Advanced Substation
15660 Alpha) subtitles format.
15662 The filter accepts the following options:
15666 Set the filename of the subtitle file to read. It must be specified.
15668 @item original_size
15669 Specify the size of the original video, the video for which the ASS file
15670 was composed. For the syntax of this option, check the
15671 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15672 Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
15673 correctly scale the fonts if the aspect ratio has been changed.
15676 Set a directory path containing fonts that can be used by the filter.
15677 These fonts will be used in addition to whatever the font provider uses.
15680 Process alpha channel, by default alpha channel is untouched.
15683 Set subtitles input character encoding. @code{subtitles} filter only. Only
15684 useful if not UTF-8.
15686 @item stream_index, si
15687 Set subtitles stream index. @code{subtitles} filter only.
15690 Override default style or script info parameters of the subtitles. It accepts a
15691 string containing ASS style format @code{KEY=VALUE} couples separated by ",".
15694 If the first key is not specified, it is assumed that the first value
15695 specifies the @option{filename}.
15697 For example, to render the file @file{sub.srt} on top of the input
15698 video, use the command:
15703 which is equivalent to:
15705 subtitles=filename=sub.srt
15708 To render the default subtitles stream from file @file{video.mkv}, use:
15710 subtitles=video.mkv
15713 To render the second subtitles stream from that file, use:
15715 subtitles=video.mkv:si=1
15718 To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue
15719 @code{DejaVu Serif}, use:
15721 subtitles=sub.srt:force_style='FontName=DejaVu Serif,PrimaryColour=&HCCFF0000'
15724 @section super2xsai
15726 Scale the input by 2x and smooth using the Super2xSaI (Scale and
15727 Interpolate) pixel art scaling algorithm.
15729 Useful for enlarging pixel art images without reducing sharpness.
15733 Swap two rectangular objects in video.
15735 This filter accepts the following options:
15745 Set 1st rect x coordinate.
15748 Set 1st rect y coordinate.
15751 Set 2nd rect x coordinate.
15754 Set 2nd rect y coordinate.
15756 All expressions are evaluated once for each frame.
15759 The all options are expressions containing the following constants:
15764 The input width and height.
15767 same as @var{w} / @var{h}
15770 input sample aspect ratio
15773 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
15776 The number of the input frame, starting from 0.
15779 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
15782 the position in the file of the input frame, NAN if unknown
15790 Apply telecine process to the video.
15792 This filter accepts the following options:
15801 The default value is @code{top}.
15805 A string of numbers representing the pulldown pattern you wish to apply.
15806 The default value is @code{23}.
15810 Some typical patterns:
15815 24p: 2332 (preferred)
15822 24p: 222222222223 ("Euro pulldown")
15829 Apply threshold effect to video stream.
15831 This filter needs four video streams to perform thresholding.
15832 First stream is stream we are filtering.
15833 Second stream is holding threshold values, third stream is holding min values,
15834 and last, fourth stream is holding max values.
15836 The filter accepts the following option:
15840 Set which planes will be processed, unprocessed planes will be copied.
15841 By default value 0xf, all planes will be processed.
15844 For example if first stream pixel's component value is less then threshold value
15845 of pixel component from 2nd threshold stream, third stream value will picked,
15846 otherwise fourth stream pixel component value will be picked.
15848 Using color source filter one can perform various types of thresholding:
15850 @subsection Examples
15854 Binary threshold, using gray color as threshold:
15856 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
15860 Inverted binary threshold, using gray color as threshold:
15862 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
15866 Truncate binary threshold, using gray color as threshold:
15868 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
15872 Threshold to zero, using gray color as threshold:
15874 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
15878 Inverted threshold to zero, using gray color as threshold:
15880 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
15885 Select the most representative frame in a given sequence of consecutive frames.
15887 The filter accepts the following options:
15891 Set the frames batch size to analyze; in a set of @var{n} frames, the filter
15892 will pick one of them, and then handle the next batch of @var{n} frames until
15893 the end. Default is @code{100}.
15896 Since the filter keeps track of the whole frames sequence, a bigger @var{n}
15897 value will result in a higher memory usage, so a high value is not recommended.
15899 @subsection Examples
15903 Extract one picture each 50 frames:
15909 Complete example of a thumbnail creation with @command{ffmpeg}:
15911 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
15917 Tile several successive frames together.
15919 The filter accepts the following options:
15924 Set the grid size (i.e. the number of lines and columns). For the syntax of
15925 this option, check the
15926 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15929 Set the maximum number of frames to render in the given area. It must be less
15930 than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
15931 the area will be used.
15934 Set the outer border margin in pixels.
15937 Set the inner border thickness (i.e. the number of pixels between frames). For
15938 more advanced padding options (such as having different values for the edges),
15939 refer to the pad video filter.
15942 Specify the color of the unused area. For the syntax of this option, check the
15943 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
15944 The default value of @var{color} is "black".
15947 Set the number of frames to overlap when tiling several successive frames together.
15948 The value must be between @code{0} and @var{nb_frames - 1}.
15951 Set the number of frames to initially be empty before displaying first output frame.
15952 This controls how soon will one get first output frame.
15953 The value must be between @code{0} and @var{nb_frames - 1}.
15956 @subsection Examples
15960 Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
15962 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
15964 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
15965 duplicating each output frame to accommodate the originally detected frame
15969 Display @code{5} pictures in an area of @code{3x2} frames,
15970 with @code{7} pixels between them, and @code{2} pixels of initial margin, using
15971 mixed flat and named options:
15973 tile=3x2:nb_frames=5:padding=7:margin=2
15977 @section tinterlace
15979 Perform various types of temporal field interlacing.
15981 Frames are counted starting from 1, so the first input frame is
15984 The filter accepts the following options:
15989 Specify the mode of the interlacing. This option can also be specified
15990 as a value alone. See below for a list of values for this option.
15992 Available values are:
15996 Move odd frames into the upper field, even into the lower field,
15997 generating a double height frame at half frame rate.
16001 Frame 1 Frame 2 Frame 3 Frame 4
16003 11111 22222 33333 44444
16004 11111 22222 33333 44444
16005 11111 22222 33333 44444
16006 11111 22222 33333 44444
16020 Only output odd frames, even frames are dropped, generating a frame with
16021 unchanged height at half frame rate.
16026 Frame 1 Frame 2 Frame 3 Frame 4
16028 11111 22222 33333 44444
16029 11111 22222 33333 44444
16030 11111 22222 33333 44444
16031 11111 22222 33333 44444
16041 Only output even frames, odd frames are dropped, generating a frame with
16042 unchanged height at half frame rate.
16047 Frame 1 Frame 2 Frame 3 Frame 4
16049 11111 22222 33333 44444
16050 11111 22222 33333 44444
16051 11111 22222 33333 44444
16052 11111 22222 33333 44444
16062 Expand each frame to full height, but pad alternate lines with black,
16063 generating a frame with double height at the same input frame rate.
16068 Frame 1 Frame 2 Frame 3 Frame 4
16070 11111 22222 33333 44444
16071 11111 22222 33333 44444
16072 11111 22222 33333 44444
16073 11111 22222 33333 44444
16076 11111 ..... 33333 .....
16077 ..... 22222 ..... 44444
16078 11111 ..... 33333 .....
16079 ..... 22222 ..... 44444
16080 11111 ..... 33333 .....
16081 ..... 22222 ..... 44444
16082 11111 ..... 33333 .....
16083 ..... 22222 ..... 44444
16087 @item interleave_top, 4
16088 Interleave the upper field from odd frames with the lower field from
16089 even frames, generating a frame with unchanged height at half frame rate.
16094 Frame 1 Frame 2 Frame 3 Frame 4
16096 11111<- 22222 33333<- 44444
16097 11111 22222<- 33333 44444<-
16098 11111<- 22222 33333<- 44444
16099 11111 22222<- 33333 44444<-
16109 @item interleave_bottom, 5
16110 Interleave the lower field from odd frames with the upper field from
16111 even frames, generating a frame with unchanged height at half frame rate.
16116 Frame 1 Frame 2 Frame 3 Frame 4
16118 11111 22222<- 33333 44444<-
16119 11111<- 22222 33333<- 44444
16120 11111 22222<- 33333 44444<-
16121 11111<- 22222 33333<- 44444
16131 @item interlacex2, 6
16132 Double frame rate with unchanged height. Frames are inserted each
16133 containing the second temporal field from the previous input frame and
16134 the first temporal field from the next input frame. This mode relies on
16135 the top_field_first flag. Useful for interlaced video displays with no
16136 field synchronisation.
16141 Frame 1 Frame 2 Frame 3 Frame 4
16143 11111 22222 33333 44444
16144 11111 22222 33333 44444
16145 11111 22222 33333 44444
16146 11111 22222 33333 44444
16149 11111 22222 22222 33333 33333 44444 44444
16150 11111 11111 22222 22222 33333 33333 44444
16151 11111 22222 22222 33333 33333 44444 44444
16152 11111 11111 22222 22222 33333 33333 44444
16157 Move odd frames into the upper field, even into the lower field,
16158 generating a double height frame at same frame rate.
16163 Frame 1 Frame 2 Frame 3 Frame 4
16165 11111 22222 33333 44444
16166 11111 22222 33333 44444
16167 11111 22222 33333 44444
16168 11111 22222 33333 44444
16171 11111 33333 33333 55555
16172 22222 22222 44444 44444
16173 11111 33333 33333 55555
16174 22222 22222 44444 44444
16175 11111 33333 33333 55555
16176 22222 22222 44444 44444
16177 11111 33333 33333 55555
16178 22222 22222 44444 44444
16183 Numeric values are deprecated but are accepted for backward
16184 compatibility reasons.
16186 Default mode is @code{merge}.
16189 Specify flags influencing the filter process.
16191 Available value for @var{flags} is:
16194 @item low_pass_filter, vlfp
16195 Enable linear vertical low-pass filtering in the filter.
16196 Vertical low-pass filtering is required when creating an interlaced
16197 destination from a progressive source which contains high-frequency
16198 vertical detail. Filtering will reduce interlace 'twitter' and Moire
16201 @item complex_filter, cvlfp
16202 Enable complex vertical low-pass filtering.
16203 This will slightly less reduce interlace 'twitter' and Moire
16204 patterning but better retain detail and subjective sharpness impression.
16208 Vertical low-pass filtering can only be enabled for @option{mode}
16209 @var{interleave_top} and @var{interleave_bottom}.
16215 Mix successive video frames.
16217 A description of the accepted options follows.
16221 The number of successive frames to mix. If unspecified, it defaults to 3.
16224 Specify weight of each input video frame.
16225 Each weight is separated by space. If number of weights is smaller than
16226 number of @var{frames} last specified weight will be used for all remaining
16230 Specify scale, if it is set it will be multiplied with sum
16231 of each weight multiplied with pixel values to give final destination
16232 pixel value. By default @var{scale} is auto scaled to sum of weights.
16235 @subsection Examples
16239 Average 7 successive frames:
16241 tmix=frames=7:weights="1 1 1 1 1 1 1"
16245 Apply simple temporal convolution:
16247 tmix=frames=3:weights="-1 3 -1"
16251 Similar as above but only showing temporal differences:
16253 tmix=frames=3:weights="-1 2 -1":scale=1
16258 Tone map colors from different dynamic ranges.
16260 This filter expects data in single precision floating point, as it needs to
16261 operate on (and can output) out-of-range values. Another filter, such as
16262 @ref{zscale}, is needed to convert the resulting frame to a usable format.
16264 The tonemapping algorithms implemented only work on linear light, so input
16265 data should be linearized beforehand (and possibly correctly tagged).
16268 ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
16271 @subsection Options
16272 The filter accepts the following options.
16276 Set the tone map algorithm to use.
16278 Possible values are:
16281 Do not apply any tone map, only desaturate overbright pixels.
16284 Hard-clip any out-of-range values. Use it for perfect color accuracy for
16285 in-range values, while distorting out-of-range values.
16288 Stretch the entire reference gamut to a linear multiple of the display.
16291 Fit a logarithmic transfer between the tone curves.
16294 Preserve overall image brightness with a simple curve, using nonlinear
16295 contrast, which results in flattening details and degrading color accuracy.
16298 Preserve both dark and bright details better than @var{reinhard}, at the cost
16299 of slightly darkening everything. Use it when detail preservation is more
16300 important than color and brightness accuracy.
16303 Smoothly map out-of-range values, while retaining contrast and colors for
16304 in-range material as much as possible. Use it when color accuracy is more
16305 important than detail preservation.
16311 Tune the tone mapping algorithm.
16313 This affects the following algorithms:
16319 Specifies the scale factor to use while stretching.
16323 Specifies the exponent of the function.
16327 Specify an extra linear coefficient to multiply into the signal before clipping.
16331 Specify the local contrast coefficient at the display peak.
16332 Default to 0.5, which means that in-gamut values will be about half as bright
16339 Specify the transition point from linear to mobius transform. Every value
16340 below this point is guaranteed to be mapped 1:1. The higher the value, the
16341 more accurate the result will be, at the cost of losing bright details.
16342 Default to 0.3, which due to the steep initial slope still preserves in-range
16343 colors fairly accurately.
16347 Apply desaturation for highlights that exceed this level of brightness. The
16348 higher the parameter, the more color information will be preserved. This
16349 setting helps prevent unnaturally blown-out colors for super-highlights, by
16350 (smoothly) turning into white instead. This makes images feel more natural,
16351 at the cost of reducing information about out-of-range colors.
16353 The default of 2.0 is somewhat conservative and will mostly just apply to
16354 skies or directly sunlit surfaces. A setting of 0.0 disables this option.
16356 This option works only if the input frame has a supported color tag.
16359 Override signal/nominal/reference peak with this value. Useful when the
16360 embedded peak information in display metadata is not reliable or when tone
16361 mapping from a lower range to a higher range.
16367 Transpose rows with columns in the input video and optionally flip it.
16369 It accepts the following parameters:
16374 Specify the transposition direction.
16376 Can assume the following values:
16378 @item 0, 4, cclock_flip
16379 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
16387 Rotate by 90 degrees clockwise, that is:
16395 Rotate by 90 degrees counterclockwise, that is:
16402 @item 3, 7, clock_flip
16403 Rotate by 90 degrees clockwise and vertically flip, that is:
16411 For values between 4-7, the transposition is only done if the input
16412 video geometry is portrait and not landscape. These values are
16413 deprecated, the @code{passthrough} option should be used instead.
16415 Numerical values are deprecated, and should be dropped in favor of
16416 symbolic constants.
16419 Do not apply the transposition if the input geometry matches the one
16420 specified by the specified value. It accepts the following values:
16423 Always apply transposition.
16425 Preserve portrait geometry (when @var{height} >= @var{width}).
16427 Preserve landscape geometry (when @var{width} >= @var{height}).
16430 Default value is @code{none}.
16433 For example to rotate by 90 degrees clockwise and preserve portrait
16436 transpose=dir=1:passthrough=portrait
16439 The command above can also be specified as:
16441 transpose=1:portrait
16444 @section transpose_npp
16446 Transpose rows with columns in the input video and optionally flip it.
16447 For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options.
16449 It accepts the following parameters:
16454 Specify the transposition direction.
16456 Can assume the following values:
16459 Rotate by 90 degrees counterclockwise and vertically flip. (default)
16462 Rotate by 90 degrees clockwise.
16465 Rotate by 90 degrees counterclockwise.
16468 Rotate by 90 degrees clockwise and vertically flip.
16472 Do not apply the transposition if the input geometry matches the one
16473 specified by the specified value. It accepts the following values:
16476 Always apply transposition. (default)
16478 Preserve portrait geometry (when @var{height} >= @var{width}).
16480 Preserve landscape geometry (when @var{width} >= @var{height}).
16486 Trim the input so that the output contains one continuous subpart of the input.
16488 It accepts the following parameters:
16491 Specify the time of the start of the kept section, i.e. the frame with the
16492 timestamp @var{start} will be the first frame in the output.
16495 Specify the time of the first frame that will be dropped, i.e. the frame
16496 immediately preceding the one with the timestamp @var{end} will be the last
16497 frame in the output.
16500 This is the same as @var{start}, except this option sets the start timestamp
16501 in timebase units instead of seconds.
16504 This is the same as @var{end}, except this option sets the end timestamp
16505 in timebase units instead of seconds.
16508 The maximum duration of the output in seconds.
16511 The number of the first frame that should be passed to the output.
16514 The number of the first frame that should be dropped.
16517 @option{start}, @option{end}, and @option{duration} are expressed as time
16518 duration specifications; see
16519 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
16520 for the accepted syntax.
16522 Note that the first two sets of the start/end options and the @option{duration}
16523 option look at the frame timestamp, while the _frame variants simply count the
16524 frames that pass through the filter. Also note that this filter does not modify
16525 the timestamps. If you wish for the output timestamps to start at zero, insert a
16526 setpts filter after the trim filter.
16528 If multiple start or end options are set, this filter tries to be greedy and
16529 keep all the frames that match at least one of the specified constraints. To keep
16530 only the part that matches all the constraints at once, chain multiple trim
16533 The defaults are such that all the input is kept. So it is possible to set e.g.
16534 just the end values to keep everything before the specified time.
16539 Drop everything except the second minute of input:
16541 ffmpeg -i INPUT -vf trim=60:120
16545 Keep only the first second:
16547 ffmpeg -i INPUT -vf trim=duration=1
16552 @section unpremultiply
16553 Apply alpha unpremultiply effect to input video stream using first plane
16554 of second stream as alpha.
16556 Both streams must have same dimensions and same pixel format.
16558 The filter accepts the following option:
16562 Set which planes will be processed, unprocessed planes will be copied.
16563 By default value 0xf, all planes will be processed.
16565 If the format has 1 or 2 components, then luma is bit 0.
16566 If the format has 3 or 4 components:
16567 for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red;
16568 for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V.
16569 If present, the alpha channel is always the last bit.
16572 Do not require 2nd input for processing, instead use alpha plane from input stream.
16578 Sharpen or blur the input video.
16580 It accepts the following parameters:
16583 @item luma_msize_x, lx
16584 Set the luma matrix horizontal size. It must be an odd integer between
16585 3 and 23. The default value is 5.
16587 @item luma_msize_y, ly
16588 Set the luma matrix vertical size. It must be an odd integer between 3
16589 and 23. The default value is 5.
16591 @item luma_amount, la
16592 Set the luma effect strength. It must be a floating point number, reasonable
16593 values lay between -1.5 and 1.5.
16595 Negative values will blur the input video, while positive values will
16596 sharpen it, a value of zero will disable the effect.
16598 Default value is 1.0.
16600 @item chroma_msize_x, cx
16601 Set the chroma matrix horizontal size. It must be an odd integer
16602 between 3 and 23. The default value is 5.
16604 @item chroma_msize_y, cy
16605 Set the chroma matrix vertical size. It must be an odd integer
16606 between 3 and 23. The default value is 5.
16608 @item chroma_amount, ca
16609 Set the chroma effect strength. It must be a floating point number, reasonable
16610 values lay between -1.5 and 1.5.
16612 Negative values will blur the input video, while positive values will
16613 sharpen it, a value of zero will disable the effect.
16615 Default value is 0.0.
16619 All parameters are optional and default to the equivalent of the
16620 string '5:5:1.0:5:5:0.0'.
16622 @subsection Examples
16626 Apply strong luma sharpen effect:
16628 unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
16632 Apply a strong blur of both luma and chroma parameters:
16634 unsharp=7:7:-2:7:7:-2
16640 Apply ultra slow/simple postprocessing filter that compresses and decompresses
16641 the image at several (or - in the case of @option{quality} level @code{8} - all)
16642 shifts and average the results.
16644 The way this differs from the behavior of spp is that uspp actually encodes &
16645 decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
16646 DCT similar to MJPEG.
16648 The filter accepts the following options:
16652 Set quality. This option defines the number of levels for averaging. It accepts
16653 an integer in the range 0-8. If set to @code{0}, the filter will have no
16654 effect. A value of @code{8} means the higher quality. For each increment of
16655 that value the speed drops by a factor of approximately 2. Default value is
16659 Force a constant quantization parameter. If not set, the filter will use the QP
16660 from the video stream (if available).
16663 @section vaguedenoiser
16665 Apply a wavelet based denoiser.
16667 It transforms each frame from the video input into the wavelet domain,
16668 using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
16669 the obtained coefficients. It does an inverse wavelet transform after.
16670 Due to wavelet properties, it should give a nice smoothed result, and
16671 reduced noise, without blurring picture features.
16673 This filter accepts the following options:
16677 The filtering strength. The higher, the more filtered the video will be.
16678 Hard thresholding can use a higher threshold than soft thresholding
16679 before the video looks overfiltered. Default value is 2.
16682 The filtering method the filter will use.
16684 It accepts the following values:
16687 All values under the threshold will be zeroed.
16690 All values under the threshold will be zeroed. All values above will be
16691 reduced by the threshold.
16694 Scales or nullifies coefficients - intermediary between (more) soft and
16695 (less) hard thresholding.
16698 Default is garrote.
16701 Number of times, the wavelet will decompose the picture. Picture can't
16702 be decomposed beyond a particular point (typically, 8 for a 640x480
16703 frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6.
16706 Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85.
16709 A list of the planes to process. By default all planes are processed.
16712 @section vectorscope
16714 Display 2 color component values in the two dimensional graph (which is called
16717 This filter accepts the following options:
16721 Set vectorscope mode.
16723 It accepts the following values:
16726 Gray values are displayed on graph, higher brightness means more pixels have
16727 same component color value on location in graph. This is the default mode.
16730 Gray values are displayed on graph. Surrounding pixels values which are not
16731 present in video frame are drawn in gradient of 2 color components which are
16732 set by option @code{x} and @code{y}. The 3rd color component is static.
16735 Actual color components values present in video frame are displayed on graph.
16738 Similar as color2 but higher frequency of same values @code{x} and @code{y}
16739 on graph increases value of another color component, which is luminance by
16740 default values of @code{x} and @code{y}.
16743 Actual colors present in video frame are displayed on graph. If two different
16744 colors map to same position on graph then color with higher value of component
16745 not present in graph is picked.
16748 Gray values are displayed on graph. Similar to @code{color} but with 3rd color
16749 component picked from radial gradient.
16753 Set which color component will be represented on X-axis. Default is @code{1}.
16756 Set which color component will be represented on Y-axis. Default is @code{2}.
16759 Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
16760 of color component which represents frequency of (X, Y) location in graph.
16765 No envelope, this is default.
16768 Instant envelope, even darkest single pixel will be clearly highlighted.
16771 Hold maximum and minimum values presented in graph over time. This way you
16772 can still spot out of range values without constantly looking at vectorscope.
16775 Peak and instant envelope combined together.
16779 Set what kind of graticule to draw.
16787 Set graticule opacity.
16790 Set graticule flags.
16794 Draw graticule for white point.
16797 Draw graticule for black point.
16800 Draw color points short names.
16804 Set background opacity.
16806 @item lthreshold, l
16807 Set low threshold for color component not represented on X or Y axis.
16808 Values lower than this value will be ignored. Default is 0.
16809 Note this value is multiplied with actual max possible value one pixel component
16810 can have. So for 8-bit input and low threshold value of 0.1 actual threshold
16813 @item hthreshold, h
16814 Set high threshold for color component not represented on X or Y axis.
16815 Values higher than this value will be ignored. Default is 1.
16816 Note this value is multiplied with actual max possible value one pixel component
16817 can have. So for 8-bit input and high threshold value of 0.9 actual threshold
16818 is 0.9 * 255 = 230.
16820 @item colorspace, c
16821 Set what kind of colorspace to use when drawing graticule.
16830 @anchor{vidstabdetect}
16831 @section vidstabdetect
16833 Analyze video stabilization/deshaking. Perform pass 1 of 2, see
16834 @ref{vidstabtransform} for pass 2.
16836 This filter generates a file with relative translation and rotation
16837 transform information about subsequent frames, which is then used by
16838 the @ref{vidstabtransform} filter.
16840 To enable compilation of this filter you need to configure FFmpeg with
16841 @code{--enable-libvidstab}.
16843 This filter accepts the following options:
16847 Set the path to the file used to write the transforms information.
16848 Default value is @file{transforms.trf}.
16851 Set how shaky the video is and how quick the camera is. It accepts an
16852 integer in the range 1-10, a value of 1 means little shakiness, a
16853 value of 10 means strong shakiness. Default value is 5.
16856 Set the accuracy of the detection process. It must be a value in the
16857 range 1-15. A value of 1 means low accuracy, a value of 15 means high
16858 accuracy. Default value is 15.
16861 Set stepsize of the search process. The region around minimum is
16862 scanned with 1 pixel resolution. Default value is 6.
16865 Set minimum contrast. Below this value a local measurement field is
16866 discarded. Must be a floating point value in the range 0-1. Default
16870 Set reference frame number for tripod mode.
16872 If enabled, the motion of the frames is compared to a reference frame
16873 in the filtered stream, identified by the specified number. The idea
16874 is to compensate all movements in a more-or-less static scene and keep
16875 the camera view absolutely still.
16877 If set to 0, it is disabled. The frames are counted starting from 1.
16880 Show fields and transforms in the resulting frames. It accepts an
16881 integer in the range 0-2. Default value is 0, which disables any
16885 @subsection Examples
16889 Use default values:
16895 Analyze strongly shaky movie and put the results in file
16896 @file{mytransforms.trf}:
16898 vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
16902 Visualize the result of internal transformations in the resulting
16905 vidstabdetect=show=1
16909 Analyze a video with medium shakiness using @command{ffmpeg}:
16911 ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
16915 @anchor{vidstabtransform}
16916 @section vidstabtransform
16918 Video stabilization/deshaking: pass 2 of 2,
16919 see @ref{vidstabdetect} for pass 1.
16921 Read a file with transform information for each frame and
16922 apply/compensate them. Together with the @ref{vidstabdetect}
16923 filter this can be used to deshake videos. See also
16924 @url{http://public.hronopik.de/vid.stab}. It is important to also use
16925 the @ref{unsharp} filter, see below.
16927 To enable compilation of this filter you need to configure FFmpeg with
16928 @code{--enable-libvidstab}.
16930 @subsection Options
16934 Set path to the file used to read the transforms. Default value is
16935 @file{transforms.trf}.
16938 Set the number of frames (value*2 + 1) used for lowpass filtering the
16939 camera movements. Default value is 10.
16941 For example a number of 10 means that 21 frames are used (10 in the
16942 past and 10 in the future) to smoothen the motion in the video. A
16943 larger value leads to a smoother video, but limits the acceleration of
16944 the camera (pan/tilt movements). 0 is a special case where a static
16945 camera is simulated.
16948 Set the camera path optimization algorithm.
16950 Accepted values are:
16953 gaussian kernel low-pass filter on camera motion (default)
16955 averaging on transformations
16959 Set maximal number of pixels to translate frames. Default value is -1,
16963 Set maximal angle in radians (degree*PI/180) to rotate frames. Default
16964 value is -1, meaning no limit.
16967 Specify how to deal with borders that may be visible due to movement
16970 Available values are:
16973 keep image information from previous frame (default)
16975 fill the border black
16979 Invert transforms if set to 1. Default value is 0.
16982 Consider transforms as relative to previous frame if set to 1,
16983 absolute if set to 0. Default value is 0.
16986 Set percentage to zoom. A positive value will result in a zoom-in
16987 effect, a negative value in a zoom-out effect. Default value is 0 (no
16991 Set optimal zooming to avoid borders.
16993 Accepted values are:
16998 optimal static zoom value is determined (only very strong movements
16999 will lead to visible borders) (default)
17001 optimal adaptive zoom value is determined (no borders will be
17002 visible), see @option{zoomspeed}
17005 Note that the value given at zoom is added to the one calculated here.
17008 Set percent to zoom maximally each frame (enabled when
17009 @option{optzoom} is set to 2). Range is from 0 to 5, default value is
17013 Specify type of interpolation.
17015 Available values are:
17020 linear only horizontal
17022 linear in both directions (default)
17024 cubic in both directions (slow)
17028 Enable virtual tripod mode if set to 1, which is equivalent to
17029 @code{relative=0:smoothing=0}. Default value is 0.
17031 Use also @code{tripod} option of @ref{vidstabdetect}.
17034 Increase log verbosity if set to 1. Also the detected global motions
17035 are written to the temporary file @file{global_motions.trf}. Default
17039 @subsection Examples
17043 Use @command{ffmpeg} for a typical stabilization with default values:
17045 ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
17048 Note the use of the @ref{unsharp} filter which is always recommended.
17051 Zoom in a bit more and load transform data from a given file:
17053 vidstabtransform=zoom=5:input="mytransforms.trf"
17057 Smoothen the video even more:
17059 vidstabtransform=smoothing=30
17065 Flip the input video vertically.
17067 For example, to vertically flip a video with @command{ffmpeg}:
17069 ffmpeg -i in.avi -vf "vflip" out.avi
17074 Detect variable frame rate video.
17076 This filter tries to detect if the input is variable or constant frame rate.
17078 At end it will output number of frames detected as having variable delta pts,
17079 and ones with constant delta pts.
17080 If there was frames with variable delta, than it will also show min and max delta
17086 Make or reverse a natural vignetting effect.
17088 The filter accepts the following options:
17092 Set lens angle expression as a number of radians.
17094 The value is clipped in the @code{[0,PI/2]} range.
17096 Default value: @code{"PI/5"}
17100 Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
17104 Set forward/backward mode.
17106 Available modes are:
17109 The larger the distance from the central point, the darker the image becomes.
17112 The larger the distance from the central point, the brighter the image becomes.
17113 This can be used to reverse a vignette effect, though there is no automatic
17114 detection to extract the lens @option{angle} and other settings (yet). It can
17115 also be used to create a burning effect.
17118 Default value is @samp{forward}.
17121 Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
17123 It accepts the following values:
17126 Evaluate expressions only once during the filter initialization.
17129 Evaluate expressions for each incoming frame. This is way slower than the
17130 @samp{init} mode since it requires all the scalers to be re-computed, but it
17131 allows advanced dynamic expressions.
17134 Default value is @samp{init}.
17137 Set dithering to reduce the circular banding effects. Default is @code{1}
17141 Set vignette aspect. This setting allows one to adjust the shape of the vignette.
17142 Setting this value to the SAR of the input will make a rectangular vignetting
17143 following the dimensions of the video.
17145 Default is @code{1/1}.
17148 @subsection Expressions
17150 The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
17151 following parameters.
17156 input width and height
17159 the number of input frame, starting from 0
17162 the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
17163 @var{TB} units, NAN if undefined
17166 frame rate of the input video, NAN if the input frame rate is unknown
17169 the PTS (Presentation TimeStamp) of the filtered video frame,
17170 expressed in seconds, NAN if undefined
17173 time base of the input video
17177 @subsection Examples
17181 Apply simple strong vignetting effect:
17187 Make a flickering vignetting:
17189 vignette='PI/4+random(1)*PI/50':eval=frame
17194 @section vmafmotion
17196 Obtain the average vmaf motion score of a video.
17197 It is one of the component filters of VMAF.
17199 The obtained average motion score is printed through the logging system.
17201 In the below example the input file @file{ref.mpg} is being processed and score
17205 ffmpeg -i ref.mpg -lavfi vmafmotion -f null -
17209 Stack input videos vertically.
17211 All streams must be of same pixel format and of same width.
17213 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
17214 to create same output.
17216 The filter accept the following option:
17220 Set number of input streams. Default is 2.
17223 If set to 1, force the output to terminate when the shortest input
17224 terminates. Default value is 0.
17229 Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
17230 Deinterlacing Filter").
17232 Based on the process described by Martin Weston for BBC R&D, and
17233 implemented based on the de-interlace algorithm written by Jim
17234 Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
17235 uses filter coefficients calculated by BBC R&D.
17237 There are two sets of filter coefficients, so called "simple":
17238 and "complex". Which set of filter coefficients is used can
17239 be set by passing an optional parameter:
17243 Set the interlacing filter coefficients. Accepts one of the following values:
17247 Simple filter coefficient set.
17249 More-complex filter coefficient set.
17251 Default value is @samp{complex}.
17254 Specify which frames to deinterlace. Accept one of the following values:
17258 Deinterlace all frames,
17260 Only deinterlace frames marked as interlaced.
17263 Default value is @samp{all}.
17267 Video waveform monitor.
17269 The waveform monitor plots color component intensity. By default luminance
17270 only. Each column of the waveform corresponds to a column of pixels in the
17273 It accepts the following options:
17277 Can be either @code{row}, or @code{column}. Default is @code{column}.
17278 In row mode, the graph on the left side represents color component value 0 and
17279 the right side represents value = 255. In column mode, the top side represents
17280 color component value = 0 and bottom side represents value = 255.
17283 Set intensity. Smaller values are useful to find out how many values of the same
17284 luminance are distributed across input rows/columns.
17285 Default value is @code{0.04}. Allowed range is [0, 1].
17288 Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
17289 In mirrored mode, higher values will be represented on the left
17290 side for @code{row} mode and at the top for @code{column} mode. Default is
17291 @code{1} (mirrored).
17295 It accepts the following values:
17298 Presents information identical to that in the @code{parade}, except
17299 that the graphs representing color components are superimposed directly
17302 This display mode makes it easier to spot relative differences or similarities
17303 in overlapping areas of the color components that are supposed to be identical,
17304 such as neutral whites, grays, or blacks.
17307 Display separate graph for the color components side by side in
17308 @code{row} mode or one below the other in @code{column} mode.
17311 Display separate graph for the color components side by side in
17312 @code{column} mode or one below the other in @code{row} mode.
17314 Using this display mode makes it easy to spot color casts in the highlights
17315 and shadows of an image, by comparing the contours of the top and the bottom
17316 graphs of each waveform. Since whites, grays, and blacks are characterized
17317 by exactly equal amounts of red, green, and blue, neutral areas of the picture
17318 should display three waveforms of roughly equal width/height. If not, the
17319 correction is easy to perform by making level adjustments the three waveforms.
17321 Default is @code{stack}.
17323 @item components, c
17324 Set which color components to display. Default is 1, which means only luminance
17325 or red color component if input is in RGB colorspace. If is set for example to
17326 7 it will display all 3 (if) available color components.
17331 No envelope, this is default.
17334 Instant envelope, minimum and maximum values presented in graph will be easily
17335 visible even with small @code{step} value.
17338 Hold minimum and maximum values presented in graph across time. This way you
17339 can still spot out of range values without constantly looking at waveforms.
17342 Peak and instant envelope combined together.
17348 No filtering, this is default.
17351 Luma and chroma combined together.
17354 Similar as above, but shows difference between blue and red chroma.
17357 Similar as above, but use different colors.
17360 Displays only chroma.
17363 Displays actual color value on waveform.
17366 Similar as above, but with luma showing frequency of chroma values.
17370 Set which graticule to display.
17374 Do not display graticule.
17377 Display green graticule showing legal broadcast ranges.
17380 Display orange graticule showing legal broadcast ranges.
17384 Set graticule opacity.
17387 Set graticule flags.
17391 Draw numbers above lines. By default enabled.
17394 Draw dots instead of lines.
17398 Set scale used for displaying graticule.
17405 Default is digital.
17408 Set background opacity.
17411 @section weave, doubleweave
17413 The @code{weave} takes a field-based video input and join
17414 each two sequential fields into single frame, producing a new double
17415 height clip with half the frame rate and half the frame count.
17417 The @code{doubleweave} works same as @code{weave} but without
17418 halving frame rate and frame count.
17420 It accepts the following option:
17424 Set first field. Available values are:
17428 Set the frame as top-field-first.
17431 Set the frame as bottom-field-first.
17435 @subsection Examples
17439 Interlace video using @ref{select} and @ref{separatefields} filter:
17441 separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
17446 Apply the xBR high-quality magnification filter which is designed for pixel
17447 art. It follows a set of edge-detection rules, see
17448 @url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}.
17450 It accepts the following option:
17454 Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
17455 @code{3xBR} and @code{4} for @code{4xBR}.
17456 Default is @code{3}.
17462 Deinterlace the input video ("yadif" means "yet another deinterlacing
17465 It accepts the following parameters:
17471 The interlacing mode to adopt. It accepts one of the following values:
17474 @item 0, send_frame
17475 Output one frame for each frame.
17476 @item 1, send_field
17477 Output one frame for each field.
17478 @item 2, send_frame_nospatial
17479 Like @code{send_frame}, but it skips the spatial interlacing check.
17480 @item 3, send_field_nospatial
17481 Like @code{send_field}, but it skips the spatial interlacing check.
17484 The default value is @code{send_frame}.
17487 The picture field parity assumed for the input interlaced video. It accepts one
17488 of the following values:
17492 Assume the top field is first.
17494 Assume the bottom field is first.
17496 Enable automatic detection of field parity.
17499 The default value is @code{auto}.
17500 If the interlacing is unknown or the decoder does not export this information,
17501 top field first will be assumed.
17504 Specify which frames to deinterlace. Accept one of the following
17509 Deinterlace all frames.
17510 @item 1, interlaced
17511 Only deinterlace frames marked as interlaced.
17514 The default value is @code{all}.
17519 Apply Zoom & Pan effect.
17521 This filter accepts the following options:
17525 Set the zoom expression. Default is 1.
17529 Set the x and y expression. Default is 0.
17532 Set the duration expression in number of frames.
17533 This sets for how many number of frames effect will last for
17534 single input image.
17537 Set the output image size, default is 'hd720'.
17540 Set the output frame rate, default is '25'.
17543 Each expression can contain the following constants:
17562 Output frame count.
17566 Last calculated 'x' and 'y' position from 'x' and 'y' expression
17567 for current input frame.
17571 'x' and 'y' of last output frame of previous input frame or 0 when there was
17572 not yet such frame (first input frame).
17575 Last calculated zoom from 'z' expression for current input frame.
17578 Last calculated zoom of last output frame of previous input frame.
17581 Number of output frames for current input frame. Calculated from 'd' expression
17582 for each input frame.
17585 number of output frames created for previous input frame
17588 Rational number: input width / input height
17591 sample aspect ratio
17594 display aspect ratio
17598 @subsection Examples
17602 Zoom-in up to 1.5 and pan at same time to some spot near center of picture:
17604 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
17608 Zoom-in up to 1.5 and pan always at center of picture:
17610 zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
17614 Same as above but without pausing:
17616 zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
17622 Scale (resize) the input video, using the z.lib library:
17623 @url{https://github.com/sekrit-twc/zimg}. To enable compilation of this
17624 filter, you need to configure FFmpeg with @code{--enable-libzimg}.
17626 The zscale filter forces the output display aspect ratio to be the same
17627 as the input, by changing the output sample aspect ratio.
17629 If the input image format is different from the format requested by
17630 the next filter, the zscale filter will convert the input to the
17633 @subsection Options
17634 The filter accepts the following options.
17639 Set the output video dimension expression. Default value is the input
17642 If the @var{width} or @var{w} value is 0, the input width is used for
17643 the output. If the @var{height} or @var{h} value is 0, the input height
17644 is used for the output.
17646 If one and only one of the values is -n with n >= 1, the zscale filter
17647 will use a value that maintains the aspect ratio of the input image,
17648 calculated from the other specified dimension. After that it will,
17649 however, make sure that the calculated dimension is divisible by n and
17650 adjust the value if necessary.
17652 If both values are -n with n >= 1, the behavior will be identical to
17653 both values being set to 0 as previously detailed.
17655 See below for the list of accepted constants for use in the dimension
17659 Set the video size. For the syntax of this option, check the
17660 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17663 Set the dither type.
17665 Possible values are:
17670 @item error_diffusion
17676 Set the resize filter type.
17678 Possible values are:
17688 Default is bilinear.
17691 Set the color range.
17693 Possible values are:
17700 Default is same as input.
17703 Set the color primaries.
17705 Possible values are:
17715 Default is same as input.
17718 Set the transfer characteristics.
17720 Possible values are:
17734 Default is same as input.
17737 Set the colorspace matrix.
17739 Possible value are:
17750 Default is same as input.
17753 Set the input color range.
17755 Possible values are:
17762 Default is same as input.
17764 @item primariesin, pin
17765 Set the input color primaries.
17767 Possible values are:
17777 Default is same as input.
17779 @item transferin, tin
17780 Set the input transfer characteristics.
17782 Possible values are:
17793 Default is same as input.
17795 @item matrixin, min
17796 Set the input colorspace matrix.
17798 Possible value are:
17810 Set the output chroma location.
17812 Possible values are:
17823 @item chromalin, cin
17824 Set the input chroma location.
17826 Possible values are:
17838 Set the nominal peak luminance.
17841 The values of the @option{w} and @option{h} options are expressions
17842 containing the following constants:
17847 The input width and height
17851 These are the same as @var{in_w} and @var{in_h}.
17855 The output (scaled) width and height
17859 These are the same as @var{out_w} and @var{out_h}
17862 The same as @var{iw} / @var{ih}
17865 input sample aspect ratio
17868 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
17872 horizontal and vertical input chroma subsample values. For example for the
17873 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
17877 horizontal and vertical output chroma subsample values. For example for the
17878 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
17884 @c man end VIDEO FILTERS
17886 @chapter Video Sources
17887 @c man begin VIDEO SOURCES
17889 Below is a description of the currently available video sources.
17893 Buffer video frames, and make them available to the filter chain.
17895 This source is mainly intended for a programmatic use, in particular
17896 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
17898 It accepts the following parameters:
17903 Specify the size (width and height) of the buffered video frames. For the
17904 syntax of this option, check the
17905 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17908 The input video width.
17911 The input video height.
17914 A string representing the pixel format of the buffered video frames.
17915 It may be a number corresponding to a pixel format, or a pixel format
17919 Specify the timebase assumed by the timestamps of the buffered frames.
17922 Specify the frame rate expected for the video stream.
17924 @item pixel_aspect, sar
17925 The sample (pixel) aspect ratio of the input video.
17928 Specify the optional parameters to be used for the scale filter which
17929 is automatically inserted when an input change is detected in the
17930 input size or format.
17932 @item hw_frames_ctx
17933 When using a hardware pixel format, this should be a reference to an
17934 AVHWFramesContext describing input frames.
17939 buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
17942 will instruct the source to accept video frames with size 320x240 and
17943 with format "yuv410p", assuming 1/24 as the timestamps timebase and
17944 square pixels (1:1 sample aspect ratio).
17945 Since the pixel format with name "yuv410p" corresponds to the number 6
17946 (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
17947 this example corresponds to:
17949 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
17952 Alternatively, the options can be specified as a flat string, but this
17953 syntax is deprecated:
17955 @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}]
17959 Create a pattern generated by an elementary cellular automaton.
17961 The initial state of the cellular automaton can be defined through the
17962 @option{filename} and @option{pattern} options. If such options are
17963 not specified an initial state is created randomly.
17965 At each new frame a new row in the video is filled with the result of
17966 the cellular automaton next generation. The behavior when the whole
17967 frame is filled is defined by the @option{scroll} option.
17969 This source accepts the following options:
17973 Read the initial cellular automaton state, i.e. the starting row, from
17974 the specified file.
17975 In the file, each non-whitespace character is considered an alive
17976 cell, a newline will terminate the row, and further characters in the
17977 file will be ignored.
17980 Read the initial cellular automaton state, i.e. the starting row, from
17981 the specified string.
17983 Each non-whitespace character in the string is considered an alive
17984 cell, a newline will terminate the row, and further characters in the
17985 string will be ignored.
17988 Set the video rate, that is the number of frames generated per second.
17991 @item random_fill_ratio, ratio
17992 Set the random fill ratio for the initial cellular automaton row. It
17993 is a floating point number value ranging from 0 to 1, defaults to
17996 This option is ignored when a file or a pattern is specified.
17998 @item random_seed, seed
17999 Set the seed for filling randomly the initial row, must be an integer
18000 included between 0 and UINT32_MAX. If not specified, or if explicitly
18001 set to -1, the filter will try to use a good random seed on a best
18005 Set the cellular automaton rule, it is a number ranging from 0 to 255.
18006 Default value is 110.
18009 Set the size of the output video. For the syntax of this option, check the
18010 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18012 If @option{filename} or @option{pattern} is specified, the size is set
18013 by default to the width of the specified initial state row, and the
18014 height is set to @var{width} * PHI.
18016 If @option{size} is set, it must contain the width of the specified
18017 pattern string, and the specified pattern will be centered in the
18020 If a filename or a pattern string is not specified, the size value
18021 defaults to "320x518" (used for a randomly generated initial state).
18024 If set to 1, scroll the output upward when all the rows in the output
18025 have been already filled. If set to 0, the new generated row will be
18026 written over the top row just after the bottom row is filled.
18029 @item start_full, full
18030 If set to 1, completely fill the output with generated rows before
18031 outputting the first frame.
18032 This is the default behavior, for disabling set the value to 0.
18035 If set to 1, stitch the left and right row edges together.
18036 This is the default behavior, for disabling set the value to 0.
18039 @subsection Examples
18043 Read the initial state from @file{pattern}, and specify an output of
18046 cellauto=f=pattern:s=200x400
18050 Generate a random initial row with a width of 200 cells, with a fill
18053 cellauto=ratio=2/3:s=200x200
18057 Create a pattern generated by rule 18 starting by a single alive cell
18058 centered on an initial row with width 100:
18060 cellauto=p=@@:s=100x400:full=0:rule=18
18064 Specify a more elaborated initial pattern:
18066 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
18071 @anchor{coreimagesrc}
18072 @section coreimagesrc
18073 Video source generated on GPU using Apple's CoreImage API on OSX.
18075 This video source is a specialized version of the @ref{coreimage} video filter.
18076 Use a core image generator at the beginning of the applied filterchain to
18077 generate the content.
18079 The coreimagesrc video source accepts the following options:
18081 @item list_generators
18082 List all available generators along with all their respective options as well as
18083 possible minimum and maximum values along with the default values.
18085 list_generators=true
18089 Specify the size of the sourced video. For the syntax of this option, check the
18090 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18091 The default value is @code{320x240}.
18094 Specify the frame rate of the sourced video, as the number of frames
18095 generated per second. It has to be a string in the format
18096 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
18097 number or a valid video frame rate abbreviation. The default value is
18101 Set the sample aspect ratio of the sourced video.
18104 Set the duration of the sourced video. See
18105 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
18106 for the accepted syntax.
18108 If not specified, or the expressed duration is negative, the video is
18109 supposed to be generated forever.
18112 Additionally, all options of the @ref{coreimage} video filter are accepted.
18113 A complete filterchain can be used for further processing of the
18114 generated input without CPU-HOST transfer. See @ref{coreimage} documentation
18115 and examples for details.
18117 @subsection Examples
18122 Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
18123 given as complete and escaped command-line for Apple's standard bash shell:
18125 ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
18127 This example is equivalent to the QRCode example of @ref{coreimage} without the
18128 need for a nullsrc video source.
18132 @section mandelbrot
18134 Generate a Mandelbrot set fractal, and progressively zoom towards the
18135 point specified with @var{start_x} and @var{start_y}.
18137 This source accepts the following options:
18142 Set the terminal pts value. Default value is 400.
18145 Set the terminal scale value.
18146 Must be a floating point value. Default value is 0.3.
18149 Set the inner coloring mode, that is the algorithm used to draw the
18150 Mandelbrot fractal internal region.
18152 It shall assume one of the following values:
18157 Show time until convergence.
18159 Set color based on point closest to the origin of the iterations.
18164 Default value is @var{mincol}.
18167 Set the bailout value. Default value is 10.0.
18170 Set the maximum of iterations performed by the rendering
18171 algorithm. Default value is 7189.
18174 Set outer coloring mode.
18175 It shall assume one of following values:
18177 @item iteration_count
18178 Set iteration cound mode.
18179 @item normalized_iteration_count
18180 set normalized iteration count mode.
18182 Default value is @var{normalized_iteration_count}.
18185 Set frame rate, expressed as number of frames per second. Default
18189 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
18190 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
18193 Set the initial scale value. Default value is 3.0.
18196 Set the initial x position. Must be a floating point value between
18197 -100 and 100. Default value is -0.743643887037158704752191506114774.
18200 Set the initial y position. Must be a floating point value between
18201 -100 and 100. Default value is -0.131825904205311970493132056385139.
18206 Generate various test patterns, as generated by the MPlayer test filter.
18208 The size of the generated video is fixed, and is 256x256.
18209 This source is useful in particular for testing encoding features.
18211 This source accepts the following options:
18216 Specify the frame rate of the sourced video, as the number of frames
18217 generated per second. It has to be a string in the format
18218 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
18219 number or a valid video frame rate abbreviation. The default value is
18223 Set the duration of the sourced video. See
18224 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
18225 for the accepted syntax.
18227 If not specified, or the expressed duration is negative, the video is
18228 supposed to be generated forever.
18232 Set the number or the name of the test to perform. Supported tests are:
18248 Default value is "all", which will cycle through the list of all tests.
18253 mptestsrc=t=dc_luma
18256 will generate a "dc_luma" test pattern.
18258 @section frei0r_src
18260 Provide a frei0r source.
18262 To enable compilation of this filter you need to install the frei0r
18263 header and configure FFmpeg with @code{--enable-frei0r}.
18265 This source accepts the following parameters:
18270 The size of the video to generate. For the syntax of this option, check the
18271 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18274 The framerate of the generated video. It may be a string of the form
18275 @var{num}/@var{den} or a frame rate abbreviation.
18278 The name to the frei0r source to load. For more information regarding frei0r and
18279 how to set the parameters, read the @ref{frei0r} section in the video filters
18282 @item filter_params
18283 A '|'-separated list of parameters to pass to the frei0r source.
18287 For example, to generate a frei0r partik0l source with size 200x200
18288 and frame rate 10 which is overlaid on the overlay filter main input:
18290 frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
18295 Generate a life pattern.
18297 This source is based on a generalization of John Conway's life game.
18299 The sourced input represents a life grid, each pixel represents a cell
18300 which can be in one of two possible states, alive or dead. Every cell
18301 interacts with its eight neighbours, which are the cells that are
18302 horizontally, vertically, or diagonally adjacent.
18304 At each interaction the grid evolves according to the adopted rule,
18305 which specifies the number of neighbor alive cells which will make a
18306 cell stay alive or born. The @option{rule} option allows one to specify
18309 This source accepts the following options:
18313 Set the file from which to read the initial grid state. In the file,
18314 each non-whitespace character is considered an alive cell, and newline
18315 is used to delimit the end of each row.
18317 If this option is not specified, the initial grid is generated
18321 Set the video rate, that is the number of frames generated per second.
18324 @item random_fill_ratio, ratio
18325 Set the random fill ratio for the initial random grid. It is a
18326 floating point number value ranging from 0 to 1, defaults to 1/PHI.
18327 It is ignored when a file is specified.
18329 @item random_seed, seed
18330 Set the seed for filling the initial random grid, must be an integer
18331 included between 0 and UINT32_MAX. If not specified, or if explicitly
18332 set to -1, the filter will try to use a good random seed on a best
18338 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
18339 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
18340 @var{NS} specifies the number of alive neighbor cells which make a
18341 live cell stay alive, and @var{NB} the number of alive neighbor cells
18342 which make a dead cell to become alive (i.e. to "born").
18343 "s" and "b" can be used in place of "S" and "B", respectively.
18345 Alternatively a rule can be specified by an 18-bits integer. The 9
18346 high order bits are used to encode the next cell state if it is alive
18347 for each number of neighbor alive cells, the low order bits specify
18348 the rule for "borning" new cells. Higher order bits encode for an
18349 higher number of neighbor cells.
18350 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
18351 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
18353 Default value is "S23/B3", which is the original Conway's game of life
18354 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
18355 cells, and will born a new cell if there are three alive cells around
18359 Set the size of the output video. For the syntax of this option, check the
18360 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18362 If @option{filename} is specified, the size is set by default to the
18363 same size of the input file. If @option{size} is set, it must contain
18364 the size specified in the input file, and the initial grid defined in
18365 that file is centered in the larger resulting area.
18367 If a filename is not specified, the size value defaults to "320x240"
18368 (used for a randomly generated initial grid).
18371 If set to 1, stitch the left and right grid edges together, and the
18372 top and bottom edges also. Defaults to 1.
18375 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
18376 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
18377 value from 0 to 255.
18380 Set the color of living (or new born) cells.
18383 Set the color of dead cells. If @option{mold} is set, this is the first color
18384 used to represent a dead cell.
18387 Set mold color, for definitely dead and moldy cells.
18389 For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the
18390 ffmpeg-utils manual,ffmpeg-utils}.
18393 @subsection Examples
18397 Read a grid from @file{pattern}, and center it on a grid of size
18400 life=f=pattern:s=300x300
18404 Generate a random grid of size 200x200, with a fill ratio of 2/3:
18406 life=ratio=2/3:s=200x200
18410 Specify a custom rule for evolving a randomly generated grid:
18416 Full example with slow death effect (mold) using @command{ffplay}:
18418 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
18425 @anchor{haldclutsrc}
18428 @anchor{pal100bars}
18429 @anchor{rgbtestsrc}
18431 @anchor{smptehdbars}
18434 @anchor{yuvtestsrc}
18435 @section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
18437 The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
18439 The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
18441 The @code{color} source provides an uniformly colored input.
18443 The @code{haldclutsrc} source provides an identity Hald CLUT. See also
18444 @ref{haldclut} filter.
18446 The @code{nullsrc} source returns unprocessed video frames. It is
18447 mainly useful to be employed in analysis / debugging tools, or as the
18448 source for filters which ignore the input data.
18450 The @code{pal75bars} source generates a color bars pattern, based on
18451 EBU PAL recommendations with 75% color levels.
18453 The @code{pal100bars} source generates a color bars pattern, based on
18454 EBU PAL recommendations with 100% color levels.
18456 The @code{rgbtestsrc} source generates an RGB test pattern useful for
18457 detecting RGB vs BGR issues. You should see a red, green and blue
18458 stripe from top to bottom.
18460 The @code{smptebars} source generates a color bars pattern, based on
18461 the SMPTE Engineering Guideline EG 1-1990.
18463 The @code{smptehdbars} source generates a color bars pattern, based on
18464 the SMPTE RP 219-2002.
18466 The @code{testsrc} source generates a test video pattern, showing a
18467 color pattern, a scrolling gradient and a timestamp. This is mainly
18468 intended for testing purposes.
18470 The @code{testsrc2} source is similar to testsrc, but supports more
18471 pixel formats instead of just @code{rgb24}. This allows using it as an
18472 input for other tests without requiring a format conversion.
18474 The @code{yuvtestsrc} source generates an YUV test pattern. You should
18475 see a y, cb and cr stripe from top to bottom.
18477 The sources accept the following parameters:
18482 Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
18483 source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
18484 pixels to be used as identity matrix for 3D lookup tables. Each component is
18485 coded on a @code{1/(N*N)} scale.
18488 Specify the color of the source, only available in the @code{color}
18489 source. For the syntax of this option, check the
18490 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
18493 Specify the size of the sourced video. For the syntax of this option, check the
18494 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18495 The default value is @code{320x240}.
18497 This option is not available with the @code{allrgb}, @code{allyuv}, and
18498 @code{haldclutsrc} filters.
18501 Specify the frame rate of the sourced video, as the number of frames
18502 generated per second. It has to be a string in the format
18503 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
18504 number or a valid video frame rate abbreviation. The default value is
18508 Set the duration of the sourced video. See
18509 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
18510 for the accepted syntax.
18512 If not specified, or the expressed duration is negative, the video is
18513 supposed to be generated forever.
18516 Set the sample aspect ratio of the sourced video.
18519 Specify the alpha (opacity) of the background, only available in the
18520 @code{testsrc2} source. The value must be between 0 (fully transparent) and
18521 255 (fully opaque, the default).
18524 Set the number of decimals to show in the timestamp, only available in the
18525 @code{testsrc} source.
18527 The displayed timestamp value will correspond to the original
18528 timestamp value multiplied by the power of 10 of the specified
18529 value. Default value is 0.
18532 @subsection Examples
18536 Generate a video with a duration of 5.3 seconds, with size
18537 176x144 and a frame rate of 10 frames per second:
18539 testsrc=duration=5.3:size=qcif:rate=10
18543 The following graph description will generate a red source
18544 with an opacity of 0.2, with size "qcif" and a frame rate of 10
18547 color=c=red@@0.2:s=qcif:r=10
18551 If the input content is to be ignored, @code{nullsrc} can be used. The
18552 following command generates noise in the luminance plane by employing
18553 the @code{geq} filter:
18555 nullsrc=s=256x256, geq=random(1)*255:128:128
18559 @subsection Commands
18561 The @code{color} source supports the following commands:
18565 Set the color of the created image. Accepts the same syntax of the
18566 corresponding @option{color} option.
18571 Generate video using an OpenCL program.
18576 OpenCL program source file.
18579 Kernel name in program.
18582 Size of frames to generate. This must be set.
18585 Pixel format to use for the generated frames. This must be set.
18588 Number of frames generated every second. Default value is '25'.
18592 For details of how the program loading works, see the @ref{program_opencl}
18599 Generate a colour ramp by setting pixel values from the position of the pixel
18600 in the output image. (Note that this will work with all pixel formats, but
18601 the generated output will not be the same.)
18603 __kernel void ramp(__write_only image2d_t dst,
18604 unsigned int index)
18606 int2 loc = (int2)(get_global_id(0), get_global_id(1));
18609 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
18611 write_imagef(dst, loc, val);
18616 Generate a Sierpinski carpet pattern, panning by a single pixel each frame.
18618 __kernel void sierpinski_carpet(__write_only image2d_t dst,
18619 unsigned int index)
18621 int2 loc = (int2)(get_global_id(0), get_global_id(1));
18623 float4 value = 0.0f;
18624 int x = loc.x + index;
18625 int y = loc.y + index;
18626 while (x > 0 || y > 0) {
18627 if (x % 3 == 1 && y % 3 == 1) {
18635 write_imagef(dst, loc, value);
18641 @c man end VIDEO SOURCES
18643 @chapter Video Sinks
18644 @c man begin VIDEO SINKS
18646 Below is a description of the currently available video sinks.
18648 @section buffersink
18650 Buffer video frames, and make them available to the end of the filter
18653 This sink is mainly intended for programmatic use, in particular
18654 through the interface defined in @file{libavfilter/buffersink.h}
18655 or the options system.
18657 It accepts a pointer to an AVBufferSinkContext structure, which
18658 defines the incoming buffers' formats, to be passed as the opaque
18659 parameter to @code{avfilter_init_filter} for initialization.
18663 Null video sink: do absolutely nothing with the input video. It is
18664 mainly useful as a template and for use in analysis / debugging
18667 @c man end VIDEO SINKS
18669 @chapter Multimedia Filters
18670 @c man begin MULTIMEDIA FILTERS
18672 Below is a description of the currently available multimedia filters.
18676 Convert input audio to a video output, displaying the audio bit scope.
18678 The filter accepts the following options:
18682 Set frame rate, expressed as number of frames per second. Default
18686 Specify the video size for the output. For the syntax of this option, check the
18687 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18688 Default value is @code{1024x256}.
18691 Specify list of colors separated by space or by '|' which will be used to
18692 draw channels. Unrecognized or missing colors will be replaced
18696 @section ahistogram
18698 Convert input audio to a video output, displaying the volume histogram.
18700 The filter accepts the following options:
18704 Specify how histogram is calculated.
18706 It accepts the following values:
18709 Use single histogram for all channels.
18711 Use separate histogram for each channel.
18713 Default is @code{single}.
18716 Set frame rate, expressed as number of frames per second. Default
18720 Specify the video size for the output. For the syntax of this option, check the
18721 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18722 Default value is @code{hd720}.
18727 It accepts the following values:
18738 reverse logarithmic
18740 Default is @code{log}.
18743 Set amplitude scale.
18745 It accepts the following values:
18752 Default is @code{log}.
18755 Set how much frames to accumulate in histogram.
18756 Defauls is 1. Setting this to -1 accumulates all frames.
18759 Set histogram ratio of window height.
18762 Set sonogram sliding.
18764 It accepts the following values:
18767 replace old rows with new ones.
18769 scroll from top to bottom.
18771 Default is @code{replace}.
18774 @section aphasemeter
18776 Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase},
18777 representing mean phase of current audio frame. A video output can also be produced and is
18778 enabled by default. The audio is passed through as first output.
18780 Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in
18781 range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase
18782 and @code{1} means channels are in phase.
18784 The filter accepts the following options, all related to its video output:
18788 Set the output frame rate. Default value is @code{25}.
18791 Set the video size for the output. For the syntax of this option, check the
18792 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18793 Default value is @code{800x400}.
18798 Specify the red, green, blue contrast. Default values are @code{2},
18799 @code{7} and @code{1}.
18800 Allowed range is @code{[0, 255]}.
18803 Set color which will be used for drawing median phase. If color is
18804 @code{none} which is default, no median phase value will be drawn.
18807 Enable video output. Default is enabled.
18810 @section avectorscope
18812 Convert input audio to a video output, representing the audio vector
18815 The filter is used to measure the difference between channels of stereo
18816 audio stream. A monoaural signal, consisting of identical left and right
18817 signal, results in straight vertical line. Any stereo separation is visible
18818 as a deviation from this line, creating a Lissajous figure.
18819 If the straight (or deviation from it) but horizontal line appears this
18820 indicates that the left and right channels are out of phase.
18822 The filter accepts the following options:
18826 Set the vectorscope mode.
18828 Available values are:
18831 Lissajous rotated by 45 degrees.
18834 Same as above but not rotated.
18837 Shape resembling half of circle.
18840 Default value is @samp{lissajous}.
18843 Set the video size for the output. For the syntax of this option, check the
18844 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18845 Default value is @code{400x400}.
18848 Set the output frame rate. Default value is @code{25}.
18854 Specify the red, green, blue and alpha contrast. Default values are @code{40},
18855 @code{160}, @code{80} and @code{255}.
18856 Allowed range is @code{[0, 255]}.
18862 Specify the red, green, blue and alpha fade. Default values are @code{15},
18863 @code{10}, @code{5} and @code{5}.
18864 Allowed range is @code{[0, 255]}.
18867 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}.
18868 Values lower than @var{1} will auto adjust zoom factor to maximal possible value.
18871 Set the vectorscope drawing mode.
18873 Available values are:
18876 Draw dot for each sample.
18879 Draw line between previous and current sample.
18882 Default value is @samp{dot}.
18885 Specify amplitude scale of audio samples.
18887 Available values are:
18903 Swap left channel axis with right channel axis.
18913 Mirror only x axis.
18916 Mirror only y axis.
18924 @subsection Examples
18928 Complete example using @command{ffplay}:
18930 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
18931 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
18935 @section bench, abench
18937 Benchmark part of a filtergraph.
18939 The filter accepts the following options:
18943 Start or stop a timer.
18945 Available values are:
18948 Get the current time, set it as frame metadata (using the key
18949 @code{lavfi.bench.start_time}), and forward the frame to the next filter.
18952 Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
18953 the input frame metadata to get the time difference. Time difference, average,
18954 maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
18955 @code{min}) are then printed. The timestamps are expressed in seconds.
18959 @subsection Examples
18963 Benchmark @ref{selectivecolor} filter:
18965 bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
18971 Concatenate audio and video streams, joining them together one after the
18974 The filter works on segments of synchronized video and audio streams. All
18975 segments must have the same number of streams of each type, and that will
18976 also be the number of streams at output.
18978 The filter accepts the following options:
18983 Set the number of segments. Default is 2.
18986 Set the number of output video streams, that is also the number of video
18987 streams in each segment. Default is 1.
18990 Set the number of output audio streams, that is also the number of audio
18991 streams in each segment. Default is 0.
18994 Activate unsafe mode: do not fail if segments have a different format.
18998 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
18999 @var{a} audio outputs.
19001 There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
19002 segment, in the same order as the outputs, then the inputs for the second
19005 Related streams do not always have exactly the same duration, for various
19006 reasons including codec frame size or sloppy authoring. For that reason,
19007 related synchronized streams (e.g. a video and its audio track) should be
19008 concatenated at once. The concat filter will use the duration of the longest
19009 stream in each segment (except the last one), and if necessary pad shorter
19010 audio streams with silence.
19012 For this filter to work correctly, all segments must start at timestamp 0.
19014 All corresponding streams must have the same parameters in all segments; the
19015 filtering system will automatically select a common pixel format for video
19016 streams, and a common sample format, sample rate and channel layout for
19017 audio streams, but other settings, such as resolution, must be converted
19018 explicitly by the user.
19020 Different frame rates are acceptable but will result in variable frame rate
19021 at output; be sure to configure the output file to handle it.
19023 @subsection Examples
19027 Concatenate an opening, an episode and an ending, all in bilingual version
19028 (video in stream 0, audio in streams 1 and 2):
19030 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
19031 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
19032 concat=n=3:v=1:a=2 [v] [a1] [a2]' \
19033 -map '[v]' -map '[a1]' -map '[a2]' output.mkv
19037 Concatenate two parts, handling audio and video separately, using the
19038 (a)movie sources, and adjusting the resolution:
19040 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
19041 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
19042 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
19044 Note that a desync will happen at the stitch if the audio and video streams
19045 do not have exactly the same duration in the first file.
19049 @subsection Commands
19051 This filter supports the following commands:
19054 Close the current segment and step to the next one
19057 @section drawgraph, adrawgraph
19059 Draw a graph using input video or audio metadata.
19061 It accepts the following parameters:
19065 Set 1st frame metadata key from which metadata values will be used to draw a graph.
19068 Set 1st foreground color expression.
19071 Set 2nd frame metadata key from which metadata values will be used to draw a graph.
19074 Set 2nd foreground color expression.
19077 Set 3rd frame metadata key from which metadata values will be used to draw a graph.
19080 Set 3rd foreground color expression.
19083 Set 4th frame metadata key from which metadata values will be used to draw a graph.
19086 Set 4th foreground color expression.
19089 Set minimal value of metadata value.
19092 Set maximal value of metadata value.
19095 Set graph background color. Default is white.
19100 Available values for mode is:
19107 Default is @code{line}.
19112 Available values for slide is:
19115 Draw new frame when right border is reached.
19118 Replace old columns with new ones.
19121 Scroll from right to left.
19124 Scroll from left to right.
19127 Draw single picture.
19130 Default is @code{frame}.
19133 Set size of graph video. For the syntax of this option, check the
19134 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19135 The default value is @code{900x256}.
19137 The foreground color expressions can use the following variables:
19140 Minimal value of metadata value.
19143 Maximal value of metadata value.
19146 Current metadata key value.
19149 The color is defined as 0xAABBGGRR.
19152 Example using metadata from @ref{signalstats} filter:
19154 signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
19157 Example using metadata from @ref{ebur128} filter:
19159 ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
19165 EBU R128 scanner filter. This filter takes an audio stream as input and outputs
19166 it unchanged. By default, it logs a message at a frequency of 10Hz with the
19167 Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
19168 Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
19170 The filter also has a video output (see the @var{video} option) with a real
19171 time graph to observe the loudness evolution. The graphic contains the logged
19172 message mentioned above, so it is not printed anymore when this option is set,
19173 unless the verbose logging is set. The main graphing area contains the
19174 short-term loudness (3 seconds of analysis), and the gauge on the right is for
19175 the momentary loudness (400 milliseconds).
19177 More information about the Loudness Recommendation EBU R128 on
19178 @url{http://tech.ebu.ch/loudness}.
19180 The filter accepts the following options:
19185 Activate the video output. The audio stream is passed unchanged whether this
19186 option is set or no. The video stream will be the first output stream if
19187 activated. Default is @code{0}.
19190 Set the video size. This option is for video only. For the syntax of this
19192 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19193 Default and minimum resolution is @code{640x480}.
19196 Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
19197 @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
19198 other integer value between this range is allowed.
19201 Set metadata injection. If set to @code{1}, the audio input will be segmented
19202 into 100ms output frames, each of them containing various loudness information
19203 in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
19205 Default is @code{0}.
19208 Force the frame logging level.
19210 Available values are:
19213 information logging level
19215 verbose logging level
19218 By default, the logging level is set to @var{info}. If the @option{video} or
19219 the @option{metadata} options are set, it switches to @var{verbose}.
19224 Available modes can be cumulated (the option is a @code{flag} type). Possible
19228 Disable any peak mode (default).
19230 Enable sample-peak mode.
19232 Simple peak mode looking for the higher sample value. It logs a message
19233 for sample-peak (identified by @code{SPK}).
19235 Enable true-peak mode.
19237 If enabled, the peak lookup is done on an over-sampled version of the input
19238 stream for better peak accuracy. It logs a message for true-peak.
19239 (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
19240 This mode requires a build with @code{libswresample}.
19244 Treat mono input files as "dual mono". If a mono file is intended for playback
19245 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
19246 If set to @code{true}, this option will compensate for this effect.
19247 Multi-channel input files are not affected by this option.
19250 Set a specific pan law to be used for the measurement of dual mono files.
19251 This parameter is optional, and has a default value of -3.01dB.
19254 @subsection Examples
19258 Real-time graph using @command{ffplay}, with a EBU scale meter +18:
19260 ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
19264 Run an analysis with @command{ffmpeg}:
19266 ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
19270 @section interleave, ainterleave
19272 Temporally interleave frames from several inputs.
19274 @code{interleave} works with video inputs, @code{ainterleave} with audio.
19276 These filters read frames from several inputs and send the oldest
19277 queued frame to the output.
19279 Input streams must have well defined, monotonically increasing frame
19282 In order to submit one frame to output, these filters need to enqueue
19283 at least one frame for each input, so they cannot work in case one
19284 input is not yet terminated and will not receive incoming frames.
19286 For example consider the case when one input is a @code{select} filter
19287 which always drops input frames. The @code{interleave} filter will keep
19288 reading from that input, but it will never be able to send new frames
19289 to output until the input sends an end-of-stream signal.
19291 Also, depending on inputs synchronization, the filters will drop
19292 frames in case one input receives more frames than the other ones, and
19293 the queue is already filled.
19295 These filters accept the following options:
19299 Set the number of different inputs, it is 2 by default.
19302 @subsection Examples
19306 Interleave frames belonging to different streams using @command{ffmpeg}:
19308 ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
19312 Add flickering blur effect:
19314 select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
19318 @section metadata, ametadata
19320 Manipulate frame metadata.
19322 This filter accepts the following options:
19326 Set mode of operation of the filter.
19328 Can be one of the following:
19332 If both @code{value} and @code{key} is set, select frames
19333 which have such metadata. If only @code{key} is set, select
19334 every frame that has such key in metadata.
19337 Add new metadata @code{key} and @code{value}. If key is already available
19341 Modify value of already present key.
19344 If @code{value} is set, delete only keys that have such value.
19345 Otherwise, delete key. If @code{key} is not set, delete all metadata values in
19349 Print key and its value if metadata was found. If @code{key} is not set print all
19350 metadata values available in frame.
19354 Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}.
19357 Set metadata value which will be used. This option is mandatory for
19358 @code{modify} and @code{add} mode.
19361 Which function to use when comparing metadata value and @code{value}.
19363 Can be one of following:
19367 Values are interpreted as strings, returns true if metadata value is same as @code{value}.
19370 Values are interpreted as strings, returns true if metadata value starts with
19371 the @code{value} option string.
19374 Values are interpreted as floats, returns true if metadata value is less than @code{value}.
19377 Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
19380 Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
19383 Values are interpreted as floats, returns true if expression from option @code{expr}
19388 Set expression which is used when @code{function} is set to @code{expr}.
19389 The expression is evaluated through the eval API and can contain the following
19394 Float representation of @code{value} from metadata key.
19397 Float representation of @code{value} as supplied by user in @code{value} option.
19401 If specified in @code{print} mode, output is written to the named file. Instead of
19402 plain filename any writable url can be specified. Filename ``-'' is a shorthand
19403 for standard output. If @code{file} option is not set, output is written to the log
19404 with AV_LOG_INFO loglevel.
19408 @subsection Examples
19412 Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values
19415 signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
19418 Print silencedetect output to file @file{metadata.txt}.
19420 silencedetect,ametadata=mode=print:file=metadata.txt
19423 Direct all metadata to a pipe with file descriptor 4.
19425 metadata=mode=print:file='pipe\:4'
19429 @section perms, aperms
19431 Set read/write permissions for the output frames.
19433 These filters are mainly aimed at developers to test direct path in the
19434 following filter in the filtergraph.
19436 The filters accept the following options:
19440 Select the permissions mode.
19442 It accepts the following values:
19445 Do nothing. This is the default.
19447 Set all the output frames read-only.
19449 Set all the output frames directly writable.
19451 Make the frame read-only if writable, and writable if read-only.
19453 Set each output frame read-only or writable randomly.
19457 Set the seed for the @var{random} mode, must be an integer included between
19458 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
19459 @code{-1}, the filter will try to use a good random seed on a best effort
19463 Note: in case of auto-inserted filter between the permission filter and the
19464 following one, the permission might not be received as expected in that
19465 following filter. Inserting a @ref{format} or @ref{aformat} filter before the
19466 perms/aperms filter can avoid this problem.
19468 @section realtime, arealtime
19470 Slow down filtering to match real time approximately.
19472 These filters will pause the filtering for a variable amount of time to
19473 match the output rate with the input timestamps.
19474 They are similar to the @option{re} option to @code{ffmpeg}.
19476 They accept the following options:
19480 Time limit for the pauses. Any pause longer than that will be considered
19481 a timestamp discontinuity and reset the timer. Default is 2 seconds.
19485 @section select, aselect
19487 Select frames to pass in output.
19489 This filter accepts the following options:
19494 Set expression, which is evaluated for each input frame.
19496 If the expression is evaluated to zero, the frame is discarded.
19498 If the evaluation result is negative or NaN, the frame is sent to the
19499 first output; otherwise it is sent to the output with index
19500 @code{ceil(val)-1}, assuming that the input index starts from 0.
19502 For example a value of @code{1.2} corresponds to the output with index
19503 @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
19506 Set the number of outputs. The output to which to send the selected
19507 frame is based on the result of the evaluation. Default value is 1.
19510 The expression can contain the following constants:
19514 The (sequential) number of the filtered frame, starting from 0.
19517 The (sequential) number of the selected frame, starting from 0.
19519 @item prev_selected_n
19520 The sequential number of the last selected frame. It's NAN if undefined.
19523 The timebase of the input timestamps.
19526 The PTS (Presentation TimeStamp) of the filtered video frame,
19527 expressed in @var{TB} units. It's NAN if undefined.
19530 The PTS of the filtered video frame,
19531 expressed in seconds. It's NAN if undefined.
19534 The PTS of the previously filtered video frame. It's NAN if undefined.
19536 @item prev_selected_pts
19537 The PTS of the last previously filtered video frame. It's NAN if undefined.
19539 @item prev_selected_t
19540 The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined.
19543 The PTS of the first video frame in the video. It's NAN if undefined.
19546 The time of the first video frame in the video. It's NAN if undefined.
19548 @item pict_type @emph{(video only)}
19549 The type of the filtered frame. It can assume one of the following
19561 @item interlace_type @emph{(video only)}
19562 The frame interlace type. It can assume one of the following values:
19565 The frame is progressive (not interlaced).
19567 The frame is top-field-first.
19569 The frame is bottom-field-first.
19572 @item consumed_sample_n @emph{(audio only)}
19573 the number of selected samples before the current frame
19575 @item samples_n @emph{(audio only)}
19576 the number of samples in the current frame
19578 @item sample_rate @emph{(audio only)}
19579 the input sample rate
19582 This is 1 if the filtered frame is a key-frame, 0 otherwise.
19585 the position in the file of the filtered frame, -1 if the information
19586 is not available (e.g. for synthetic video)
19588 @item scene @emph{(video only)}
19589 value between 0 and 1 to indicate a new scene; a low value reflects a low
19590 probability for the current frame to introduce a new scene, while a higher
19591 value means the current frame is more likely to be one (see the example below)
19593 @item concatdec_select
19594 The concat demuxer can select only part of a concat input file by setting an
19595 inpoint and an outpoint, but the output packets may not be entirely contained
19596 in the selected interval. By using this variable, it is possible to skip frames
19597 generated by the concat demuxer which are not exactly contained in the selected
19600 This works by comparing the frame pts against the @var{lavf.concat.start_time}
19601 and the @var{lavf.concat.duration} packet metadata values which are also
19602 present in the decoded frames.
19604 The @var{concatdec_select} variable is -1 if the frame pts is at least
19605 start_time and either the duration metadata is missing or the frame pts is less
19606 than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
19609 That basically means that an input frame is selected if its pts is within the
19610 interval set by the concat demuxer.
19614 The default value of the select expression is "1".
19616 @subsection Examples
19620 Select all frames in input:
19625 The example above is the same as:
19637 Select only I-frames:
19639 select='eq(pict_type\,I)'
19643 Select one frame every 100:
19645 select='not(mod(n\,100))'
19649 Select only frames contained in the 10-20 time interval:
19651 select=between(t\,10\,20)
19655 Select only I-frames contained in the 10-20 time interval:
19657 select=between(t\,10\,20)*eq(pict_type\,I)
19661 Select frames with a minimum distance of 10 seconds:
19663 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
19667 Use aselect to select only audio frames with samples number > 100:
19669 aselect='gt(samples_n\,100)'
19673 Create a mosaic of the first scenes:
19675 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
19678 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
19682 Send even and odd frames to separate outputs, and compose them:
19684 select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
19688 Select useful frames from an ffconcat file which is using inpoints and
19689 outpoints but where the source files are not intra frame only.
19691 ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
19695 @section sendcmd, asendcmd
19697 Send commands to filters in the filtergraph.
19699 These filters read commands to be sent to other filters in the
19702 @code{sendcmd} must be inserted between two video filters,
19703 @code{asendcmd} must be inserted between two audio filters, but apart
19704 from that they act the same way.
19706 The specification of commands can be provided in the filter arguments
19707 with the @var{commands} option, or in a file specified by the
19708 @var{filename} option.
19710 These filters accept the following options:
19713 Set the commands to be read and sent to the other filters.
19715 Set the filename of the commands to be read and sent to the other
19719 @subsection Commands syntax
19721 A commands description consists of a sequence of interval
19722 specifications, comprising a list of commands to be executed when a
19723 particular event related to that interval occurs. The occurring event
19724 is typically the current frame time entering or leaving a given time
19727 An interval is specified by the following syntax:
19729 @var{START}[-@var{END}] @var{COMMANDS};
19732 The time interval is specified by the @var{START} and @var{END} times.
19733 @var{END} is optional and defaults to the maximum time.
19735 The current frame time is considered within the specified interval if
19736 it is included in the interval [@var{START}, @var{END}), that is when
19737 the time is greater or equal to @var{START} and is lesser than
19740 @var{COMMANDS} consists of a sequence of one or more command
19741 specifications, separated by ",", relating to that interval. The
19742 syntax of a command specification is given by:
19744 [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
19747 @var{FLAGS} is optional and specifies the type of events relating to
19748 the time interval which enable sending the specified command, and must
19749 be a non-null sequence of identifier flags separated by "+" or "|" and
19750 enclosed between "[" and "]".
19752 The following flags are recognized:
19755 The command is sent when the current frame timestamp enters the
19756 specified interval. In other words, the command is sent when the
19757 previous frame timestamp was not in the given interval, and the
19761 The command is sent when the current frame timestamp leaves the
19762 specified interval. In other words, the command is sent when the
19763 previous frame timestamp was in the given interval, and the
19767 If @var{FLAGS} is not specified, a default value of @code{[enter]} is
19770 @var{TARGET} specifies the target of the command, usually the name of
19771 the filter class or a specific filter instance name.
19773 @var{COMMAND} specifies the name of the command for the target filter.
19775 @var{ARG} is optional and specifies the optional list of argument for
19776 the given @var{COMMAND}.
19778 Between one interval specification and another, whitespaces, or
19779 sequences of characters starting with @code{#} until the end of line,
19780 are ignored and can be used to annotate comments.
19782 A simplified BNF description of the commands specification syntax
19785 @var{COMMAND_FLAG} ::= "enter" | "leave"
19786 @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
19787 @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
19788 @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
19789 @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
19790 @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
19793 @subsection Examples
19797 Specify audio tempo change at second 4:
19799 asendcmd=c='4.0 atempo tempo 1.5',atempo
19803 Target a specific filter instance:
19805 asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my
19809 Specify a list of drawtext and hue commands in a file.
19811 # show text in the interval 5-10
19812 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
19813 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
19815 # desaturate the image in the interval 15-20
19816 15.0-20.0 [enter] hue s 0,
19817 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
19819 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
19821 # apply an exponential saturation fade-out effect, starting from time 25
19822 25 [enter] hue s exp(25-t)
19825 A filtergraph allowing to read and process the above command list
19826 stored in a file @file{test.cmd}, can be specified with:
19828 sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
19833 @section setpts, asetpts
19835 Change the PTS (presentation timestamp) of the input frames.
19837 @code{setpts} works on video frames, @code{asetpts} on audio frames.
19839 This filter accepts the following options:
19844 The expression which is evaluated for each frame to construct its timestamp.
19848 The expression is evaluated through the eval API and can contain the following
19852 @item FRAME_RATE, FR
19853 frame rate, only defined for constant frame-rate video
19856 The presentation timestamp in input
19859 The count of the input frame for video or the number of consumed samples,
19860 not including the current frame for audio, starting from 0.
19862 @item NB_CONSUMED_SAMPLES
19863 The number of consumed samples, not including the current frame (only
19866 @item NB_SAMPLES, S
19867 The number of samples in the current frame (only audio)
19869 @item SAMPLE_RATE, SR
19870 The audio sample rate.
19873 The PTS of the first frame.
19876 the time in seconds of the first frame
19879 State whether the current frame is interlaced.
19882 the time in seconds of the current frame
19885 original position in the file of the frame, or undefined if undefined
19886 for the current frame
19889 The previous input PTS.
19892 previous input time in seconds
19895 The previous output PTS.
19898 previous output time in seconds
19901 The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
19905 The wallclock (RTC) time at the start of the movie in microseconds.
19908 The timebase of the input timestamps.
19912 @subsection Examples
19916 Start counting PTS from zero
19918 setpts=PTS-STARTPTS
19922 Apply fast motion effect:
19928 Apply slow motion effect:
19934 Set fixed rate of 25 frames per second:
19940 Set fixed rate 25 fps with some jitter:
19942 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
19946 Apply an offset of 10 seconds to the input PTS:
19952 Generate timestamps from a "live source" and rebase onto the current timebase:
19954 setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
19958 Generate timestamps by counting samples:
19967 Force color range for the output video frame.
19969 The @code{setrange} filter marks the color range property for the
19970 output frames. It does not change the input frame, but only sets the
19971 corresponding property, which affects how the frame is treated by
19974 The filter accepts the following options:
19979 Available values are:
19983 Keep the same color range property.
19985 @item unspecified, unknown
19986 Set the color range as unspecified.
19988 @item limited, tv, mpeg
19989 Set the color range as limited.
19991 @item full, pc, jpeg
19992 Set the color range as full.
19996 @section settb, asettb
19998 Set the timebase to use for the output frames timestamps.
19999 It is mainly useful for testing timebase configuration.
20001 It accepts the following parameters:
20006 The expression which is evaluated into the output timebase.
20010 The value for @option{tb} is an arithmetic expression representing a
20011 rational. The expression can contain the constants "AVTB" (the default
20012 timebase), "intb" (the input timebase) and "sr" (the sample rate,
20013 audio only). Default value is "intb".
20015 @subsection Examples
20019 Set the timebase to 1/25:
20025 Set the timebase to 1/10:
20031 Set the timebase to 1001/1000:
20037 Set the timebase to 2*intb:
20043 Set the default timebase value:
20050 Convert input audio to a video output representing frequency spectrum
20051 logarithmically using Brown-Puckette constant Q transform algorithm with
20052 direct frequency domain coefficient calculation (but the transform itself
20053 is not really constant Q, instead the Q factor is actually variable/clamped),
20054 with musical tone scale, from E0 to D#10.
20056 The filter accepts the following options:
20060 Specify the video size for the output. It must be even. For the syntax of this option,
20061 check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20062 Default value is @code{1920x1080}.
20065 Set the output frame rate. Default value is @code{25}.
20068 Set the bargraph height. It must be even. Default value is @code{-1} which
20069 computes the bargraph height automatically.
20072 Set the axis height. It must be even. Default value is @code{-1} which computes
20073 the axis height automatically.
20076 Set the sonogram height. It must be even. Default value is @code{-1} which
20077 computes the sonogram height automatically.
20080 Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
20081 instead. Default value is @code{1}.
20083 @item sono_v, volume
20084 Specify the sonogram volume expression. It can contain variables:
20087 the @var{bar_v} evaluated expression
20088 @item frequency, freq, f
20089 the frequency where it is evaluated
20090 @item timeclamp, tc
20091 the value of @var{timeclamp} option
20095 @item a_weighting(f)
20096 A-weighting of equal loudness
20097 @item b_weighting(f)
20098 B-weighting of equal loudness
20099 @item c_weighting(f)
20100 C-weighting of equal loudness.
20102 Default value is @code{16}.
20104 @item bar_v, volume2
20105 Specify the bargraph volume expression. It can contain variables:
20108 the @var{sono_v} evaluated expression
20109 @item frequency, freq, f
20110 the frequency where it is evaluated
20111 @item timeclamp, tc
20112 the value of @var{timeclamp} option
20116 @item a_weighting(f)
20117 A-weighting of equal loudness
20118 @item b_weighting(f)
20119 B-weighting of equal loudness
20120 @item c_weighting(f)
20121 C-weighting of equal loudness.
20123 Default value is @code{sono_v}.
20125 @item sono_g, gamma
20126 Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
20127 higher gamma makes the spectrum having more range. Default value is @code{3}.
20128 Acceptable range is @code{[1, 7]}.
20130 @item bar_g, gamma2
20131 Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
20135 Specify the bargraph transparency level. Lower value makes the bargraph sharper.
20136 Default value is @code{1}. Acceptable range is @code{[0, 1]}.
20138 @item timeclamp, tc
20139 Specify the transform timeclamp. At low frequency, there is trade-off between
20140 accuracy in time domain and frequency domain. If timeclamp is lower,
20141 event in time domain is represented more accurately (such as fast bass drum),
20142 otherwise event in frequency domain is represented more accurately
20143 (such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}.
20146 Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it
20147 limits future samples by applying asymmetric windowing in time domain, useful
20148 when low latency is required. Accepted range is @code{[0, 1]}.
20151 Specify the transform base frequency. Default value is @code{20.01523126408007475},
20152 which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
20155 Specify the transform end frequency. Default value is @code{20495.59681441799654},
20156 which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
20159 This option is deprecated and ignored.
20162 Specify the transform length in time domain. Use this option to control accuracy
20163 trade-off between time domain and frequency domain at every frequency sample.
20164 It can contain variables:
20166 @item frequency, freq, f
20167 the frequency where it is evaluated
20168 @item timeclamp, tc
20169 the value of @var{timeclamp} option.
20171 Default value is @code{384*tc/(384+tc*f)}.
20174 Specify the transform count for every video frame. Default value is @code{6}.
20175 Acceptable range is @code{[1, 30]}.
20178 Specify the transform count for every single pixel. Default value is @code{0},
20179 which makes it computed automatically. Acceptable range is @code{[0, 10]}.
20182 Specify font file for use with freetype to draw the axis. If not specified,
20183 use embedded font. Note that drawing with font file or embedded font is not
20184 implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
20188 Specify fontconfig pattern. This has lower priority than @var{fontfile}.
20189 The : in the pattern may be replaced by | to avoid unnecessary escaping.
20192 Specify font color expression. This is arithmetic expression that should return
20193 integer value 0xRRGGBB. It can contain variables:
20195 @item frequency, freq, f
20196 the frequency where it is evaluated
20197 @item timeclamp, tc
20198 the value of @var{timeclamp} option
20203 midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
20204 @item r(x), g(x), b(x)
20205 red, green, and blue value of intensity x.
20207 Default value is @code{st(0, (midi(f)-59.5)/12);
20208 st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
20209 r(1-ld(1)) + b(ld(1))}.
20212 Specify image file to draw the axis. This option override @var{fontfile} and
20213 @var{fontcolor} option.
20216 Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
20217 the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
20218 Default value is @code{1}.
20221 Set colorspace. The accepted values are:
20224 Unspecified (default)
20233 BT.470BG or BT.601-6 625
20236 SMPTE-170M or BT.601-6 525
20242 BT.2020 with non-constant luminance
20247 Set spectrogram color scheme. This is list of floating point values with format
20248 @code{left_r|left_g|left_b|right_r|right_g|right_b}.
20249 The default is @code{1|0.5|0|0|0.5|1}.
20253 @subsection Examples
20257 Playing audio while showing the spectrum:
20259 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
20263 Same as above, but with frame rate 30 fps:
20265 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
20269 Playing at 1280x720:
20271 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
20275 Disable sonogram display:
20281 A1 and its harmonics: A1, A2, (near)E3, A3:
20283 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),
20284 asplit[a][out1]; [a] showcqt [out0]'
20288 Same as above, but with more accuracy in frequency domain:
20290 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),
20291 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
20297 bar_v=10:sono_v=bar_v*a_weighting(f)
20301 Custom gamma, now spectrum is linear to the amplitude.
20307 Custom tlength equation:
20309 tc=0.33:tlength='st(0,0.17); 384*tc / (384 / ld(0) + tc*f /(1-ld(0))) + 384*tc / (tc*f / ld(0) + 384 /(1-ld(0)))'
20313 Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
20315 fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
20319 Custom font using fontconfig:
20321 font='Courier New,Monospace,mono|bold'
20325 Custom frequency range with custom axis using image file:
20327 axisfile=myaxis.png:basefreq=40:endfreq=10000
20333 Convert input audio to video output representing the audio power spectrum.
20334 Audio amplitude is on Y-axis while frequency is on X-axis.
20336 The filter accepts the following options:
20340 Specify size of video. For the syntax of this option, check the
20341 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20342 Default is @code{1024x512}.
20346 This set how each frequency bin will be represented.
20348 It accepts the following values:
20354 Default is @code{bar}.
20357 Set amplitude scale.
20359 It accepts the following values:
20373 Default is @code{log}.
20376 Set frequency scale.
20378 It accepts the following values:
20387 Reverse logarithmic scale.
20389 Default is @code{lin}.
20394 It accepts the following values:
20410 Default is @code{w2048}
20413 Set windowing function.
20415 It accepts the following values:
20437 Default is @code{hanning}.
20440 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
20441 which means optimal overlap for selected window function will be picked.
20444 Set time averaging. Setting this to 0 will display current maximal peaks.
20445 Default is @code{1}, which means time averaging is disabled.
20448 Specify list of colors separated by space or by '|' which will be used to
20449 draw channel frequencies. Unrecognized or missing colors will be replaced
20453 Set channel display mode.
20455 It accepts the following values:
20460 Default is @code{combined}.
20463 Set minimum amplitude used in @code{log} amplitude scaler.
20467 @anchor{showspectrum}
20468 @section showspectrum
20470 Convert input audio to a video output, representing the audio frequency
20473 The filter accepts the following options:
20477 Specify the video size for the output. For the syntax of this option, check the
20478 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20479 Default value is @code{640x512}.
20482 Specify how the spectrum should slide along the window.
20484 It accepts the following values:
20487 the samples start again on the left when they reach the right
20489 the samples scroll from right to left
20491 frames are only produced when the samples reach the right
20493 the samples scroll from left to right
20496 Default value is @code{replace}.
20499 Specify display mode.
20501 It accepts the following values:
20504 all channels are displayed in the same row
20506 all channels are displayed in separate rows
20509 Default value is @samp{combined}.
20512 Specify display color mode.
20514 It accepts the following values:
20517 each channel is displayed in a separate color
20519 each channel is displayed using the same color scheme
20521 each channel is displayed using the rainbow color scheme
20523 each channel is displayed using the moreland color scheme
20525 each channel is displayed using the nebulae color scheme
20527 each channel is displayed using the fire color scheme
20529 each channel is displayed using the fiery color scheme
20531 each channel is displayed using the fruit color scheme
20533 each channel is displayed using the cool color scheme
20535 each channel is displayed using the magma color scheme
20538 Default value is @samp{channel}.
20541 Specify scale used for calculating intensity color values.
20543 It accepts the following values:
20548 square root, default
20559 Default value is @samp{sqrt}.
20562 Set saturation modifier for displayed colors. Negative values provide
20563 alternative color scheme. @code{0} is no saturation at all.
20564 Saturation must be in [-10.0, 10.0] range.
20565 Default value is @code{1}.
20568 Set window function.
20570 It accepts the following values:
20594 Default value is @code{hann}.
20597 Set orientation of time vs frequency axis. Can be @code{vertical} or
20598 @code{horizontal}. Default is @code{vertical}.
20601 Set ratio of overlap window. Default value is @code{0}.
20602 When value is @code{1} overlap is set to recommended size for specific
20603 window function currently used.
20606 Set scale gain for calculating intensity color values.
20607 Default value is @code{1}.
20610 Set which data to display. Can be @code{magnitude}, default or @code{phase}.
20613 Set color rotation, must be in [-1.0, 1.0] range.
20614 Default value is @code{0}.
20617 The usage is very similar to the showwaves filter; see the examples in that
20620 @subsection Examples
20624 Large window with logarithmic color scaling:
20626 showspectrum=s=1280x480:scale=log
20630 Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
20632 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
20633 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
20637 @section showspectrumpic
20639 Convert input audio to a single video frame, representing the audio frequency
20642 The filter accepts the following options:
20646 Specify the video size for the output. For the syntax of this option, check the
20647 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20648 Default value is @code{4096x2048}.
20651 Specify display mode.
20653 It accepts the following values:
20656 all channels are displayed in the same row
20658 all channels are displayed in separate rows
20660 Default value is @samp{combined}.
20663 Specify display color mode.
20665 It accepts the following values:
20668 each channel is displayed in a separate color
20670 each channel is displayed using the same color scheme
20672 each channel is displayed using the rainbow color scheme
20674 each channel is displayed using the moreland color scheme
20676 each channel is displayed using the nebulae color scheme
20678 each channel is displayed using the fire color scheme
20680 each channel is displayed using the fiery color scheme
20682 each channel is displayed using the fruit color scheme
20684 each channel is displayed using the cool color scheme
20686 each channel is displayed using the magma color scheme
20688 Default value is @samp{intensity}.
20691 Specify scale used for calculating intensity color values.
20693 It accepts the following values:
20698 square root, default
20708 Default value is @samp{log}.
20711 Set saturation modifier for displayed colors. Negative values provide
20712 alternative color scheme. @code{0} is no saturation at all.
20713 Saturation must be in [-10.0, 10.0] range.
20714 Default value is @code{1}.
20717 Set window function.
20719 It accepts the following values:
20742 Default value is @code{hann}.
20745 Set orientation of time vs frequency axis. Can be @code{vertical} or
20746 @code{horizontal}. Default is @code{vertical}.
20749 Set scale gain for calculating intensity color values.
20750 Default value is @code{1}.
20753 Draw time and frequency axes and legends. Default is enabled.
20756 Set color rotation, must be in [-1.0, 1.0] range.
20757 Default value is @code{0}.
20760 @subsection Examples
20764 Extract an audio spectrogram of a whole audio track
20765 in a 1024x1024 picture using @command{ffmpeg}:
20767 ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
20771 @section showvolume
20773 Convert input audio volume to a video output.
20775 The filter accepts the following options:
20782 Set border width, allowed range is [0, 5]. Default is 1.
20785 Set channel width, allowed range is [80, 8192]. Default is 400.
20788 Set channel height, allowed range is [1, 900]. Default is 20.
20791 Set fade, allowed range is [0, 1]. Default is 0.95.
20794 Set volume color expression.
20796 The expression can use the following variables:
20800 Current max volume of channel in dB.
20806 Current channel number, starting from 0.
20810 If set, displays channel names. Default is enabled.
20813 If set, displays volume values. Default is enabled.
20816 Set orientation, can be horizontal: @code{h} or vertical: @code{v},
20817 default is @code{h}.
20820 Set step size, allowed range is [0, 5]. Default is 0, which means
20824 Set background opacity, allowed range is [0, 1]. Default is 0.
20827 Set metering mode, can be peak: @code{p} or rms: @code{r},
20828 default is @code{p}.
20831 Set display scale, can be linear: @code{lin} or log: @code{log},
20832 default is @code{lin}.
20836 If set to > 0., display a line for the max level
20837 in the previous seconds.
20838 default is disabled: @code{0.}
20841 The color of the max line. Use when @code{dm} option is set to > 0.
20842 default is: @code{orange}
20847 Convert input audio to a video output, representing the samples waves.
20849 The filter accepts the following options:
20853 Specify the video size for the output. For the syntax of this option, check the
20854 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20855 Default value is @code{600x240}.
20860 Available values are:
20863 Draw a point for each sample.
20866 Draw a vertical line for each sample.
20869 Draw a point for each sample and a line between them.
20872 Draw a centered vertical line for each sample.
20875 Default value is @code{point}.
20878 Set the number of samples which are printed on the same column. A
20879 larger value will decrease the frame rate. Must be a positive
20880 integer. This option can be set only if the value for @var{rate}
20881 is not explicitly specified.
20884 Set the (approximate) output frame rate. This is done by setting the
20885 option @var{n}. Default value is "25".
20887 @item split_channels
20888 Set if channels should be drawn separately or overlap. Default value is 0.
20891 Set colors separated by '|' which are going to be used for drawing of each channel.
20894 Set amplitude scale.
20896 Available values are:
20914 Set the draw mode. This is mostly useful to set for high @var{n}.
20916 Available values are:
20919 Scale pixel values for each drawn sample.
20922 Draw every sample directly.
20925 Default value is @code{scale}.
20928 @subsection Examples
20932 Output the input file audio and the corresponding video representation
20935 amovie=a.mp3,asplit[out0],showwaves[out1]
20939 Create a synthetic signal and show it with showwaves, forcing a
20940 frame rate of 30 frames per second:
20942 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
20946 @section showwavespic
20948 Convert input audio to a single video frame, representing the samples waves.
20950 The filter accepts the following options:
20954 Specify the video size for the output. For the syntax of this option, check the
20955 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20956 Default value is @code{600x240}.
20958 @item split_channels
20959 Set if channels should be drawn separately or overlap. Default value is 0.
20962 Set colors separated by '|' which are going to be used for drawing of each channel.
20965 Set amplitude scale.
20967 Available values are:
20985 @subsection Examples
20989 Extract a channel split representation of the wave form of a whole audio track
20990 in a 1024x800 picture using @command{ffmpeg}:
20992 ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
20996 @section sidedata, asidedata
20998 Delete frame side data, or select frames based on it.
21000 This filter accepts the following options:
21004 Set mode of operation of the filter.
21006 Can be one of the following:
21010 Select every frame with side data of @code{type}.
21013 Delete side data of @code{type}. If @code{type} is not set, delete all side
21019 Set side data type used with all modes. Must be set for @code{select} mode. For
21020 the list of frame side data types, refer to the @code{AVFrameSideDataType} enum
21021 in @file{libavutil/frame.h}. For example, to choose
21022 @code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}.
21026 @section spectrumsynth
21028 Sythesize audio from 2 input video spectrums, first input stream represents
21029 magnitude across time and second represents phase across time.
21030 The filter will transform from frequency domain as displayed in videos back
21031 to time domain as presented in audio output.
21033 This filter is primarily created for reversing processed @ref{showspectrum}
21034 filter outputs, but can synthesize sound from other spectrograms too.
21035 But in such case results are going to be poor if the phase data is not
21036 available, because in such cases phase data need to be recreated, usually
21037 its just recreated from random noise.
21038 For best results use gray only output (@code{channel} color mode in
21039 @ref{showspectrum} filter) and @code{log} scale for magnitude video and
21040 @code{lin} scale for phase video. To produce phase, for 2nd video, use
21041 @code{data} option. Inputs videos should generally use @code{fullframe}
21042 slide mode as that saves resources needed for decoding video.
21044 The filter accepts the following options:
21048 Specify sample rate of output audio, the sample rate of audio from which
21049 spectrum was generated may differ.
21052 Set number of channels represented in input video spectrums.
21055 Set scale which was used when generating magnitude input spectrum.
21056 Can be @code{lin} or @code{log}. Default is @code{log}.
21059 Set slide which was used when generating inputs spectrums.
21060 Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
21061 Default is @code{fullframe}.
21064 Set window function used for resynthesis.
21067 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
21068 which means optimal overlap for selected window function will be picked.
21071 Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
21072 Default is @code{vertical}.
21075 @subsection Examples
21079 First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
21080 then resynthesize videos back to audio with spectrumsynth:
21082 ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=log:overlap=0.875:color=channel:slide=fullframe:data=magnitude -an -c:v rawvideo magnitude.nut
21083 ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=lin:overlap=0.875:color=channel:slide=fullframe:data=phase -an -c:v rawvideo phase.nut
21084 ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
21088 @section split, asplit
21090 Split input into several identical outputs.
21092 @code{asplit} works with audio input, @code{split} with video.
21094 The filter accepts a single parameter which specifies the number of outputs. If
21095 unspecified, it defaults to 2.
21097 @subsection Examples
21101 Create two separate outputs from the same input:
21103 [in] split [out0][out1]
21107 To create 3 or more outputs, you need to specify the number of
21110 [in] asplit=3 [out0][out1][out2]
21114 Create two separate outputs from the same input, one cropped and
21117 [in] split [splitout1][splitout2];
21118 [splitout1] crop=100:100:0:0 [cropout];
21119 [splitout2] pad=200:200:100:100 [padout];
21123 Create 5 copies of the input audio with @command{ffmpeg}:
21125 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
21131 Receive commands sent through a libzmq client, and forward them to
21132 filters in the filtergraph.
21134 @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
21135 must be inserted between two video filters, @code{azmq} between two
21136 audio filters. Both are capable to send messages to any filter type.
21138 To enable these filters you need to install the libzmq library and
21139 headers and configure FFmpeg with @code{--enable-libzmq}.
21141 For more information about libzmq see:
21142 @url{http://www.zeromq.org/}
21144 The @code{zmq} and @code{azmq} filters work as a libzmq server, which
21145 receives messages sent through a network interface defined by the
21146 @option{bind_address} (or the abbreviation "@option{b}") option.
21147 Default value of this option is @file{tcp://localhost:5555}. You may
21148 want to alter this value to your needs, but do not forget to escape any
21149 ':' signs (see @ref{filtergraph escaping}).
21151 The received message must be in the form:
21153 @var{TARGET} @var{COMMAND} [@var{ARG}]
21156 @var{TARGET} specifies the target of the command, usually the name of
21157 the filter class or a specific filter instance name. The default
21158 filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>},
21159 but you can override this by using the @samp{filter_name@@id} syntax
21160 (see @ref{Filtergraph syntax}).
21162 @var{COMMAND} specifies the name of the command for the target filter.
21164 @var{ARG} is optional and specifies the optional argument list for the
21165 given @var{COMMAND}.
21167 Upon reception, the message is processed and the corresponding command
21168 is injected into the filtergraph. Depending on the result, the filter
21169 will send a reply to the client, adopting the format:
21171 @var{ERROR_CODE} @var{ERROR_REASON}
21175 @var{MESSAGE} is optional.
21177 @subsection Examples
21179 Look at @file{tools/zmqsend} for an example of a zmq client which can
21180 be used to send commands processed by these filters.
21182 Consider the following filtergraph generated by @command{ffplay}.
21183 In this example the last overlay filter has an instance name. All other
21184 filters will have default instance names.
21187 ffplay -dumpgraph 1 -f lavfi "
21188 color=s=100x100:c=red [l];
21189 color=s=100x100:c=blue [r];
21190 nullsrc=s=200x100, zmq [bg];
21191 [bg][l] overlay [bg+l];
21192 [bg+l][r] overlay@@my=x=100 "
21195 To change the color of the left side of the video, the following
21196 command can be used:
21198 echo Parsed_color_0 c yellow | tools/zmqsend
21201 To change the right side:
21203 echo Parsed_color_1 c pink | tools/zmqsend
21206 To change the position of the right side:
21208 echo overlay@@my x 150 | tools/zmqsend
21212 @c man end MULTIMEDIA FILTERS
21214 @chapter Multimedia Sources
21215 @c man begin MULTIMEDIA SOURCES
21217 Below is a description of the currently available multimedia sources.
21221 This is the same as @ref{movie} source, except it selects an audio
21227 Read audio and/or video stream(s) from a movie container.
21229 It accepts the following parameters:
21233 The name of the resource to read (not necessarily a file; it can also be a
21234 device or a stream accessed through some protocol).
21236 @item format_name, f
21237 Specifies the format assumed for the movie to read, and can be either
21238 the name of a container or an input device. If not specified, the
21239 format is guessed from @var{movie_name} or by probing.
21241 @item seek_point, sp
21242 Specifies the seek point in seconds. The frames will be output
21243 starting from this seek point. The parameter is evaluated with
21244 @code{av_strtod}, so the numerical value may be suffixed by an IS
21245 postfix. The default value is "0".
21248 Specifies the streams to read. Several streams can be specified,
21249 separated by "+". The source will then have as many outputs, in the
21250 same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers"
21251 section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify
21252 respectively the default (best suited) video and audio stream. Default
21253 is "dv", or "da" if the filter is called as "amovie".
21255 @item stream_index, si
21256 Specifies the index of the video stream to read. If the value is -1,
21257 the most suitable video stream will be automatically selected. The default
21258 value is "-1". Deprecated. If the filter is called "amovie", it will select
21259 audio instead of video.
21262 Specifies how many times to read the stream in sequence.
21263 If the value is 0, the stream will be looped infinitely.
21264 Default value is "1".
21266 Note that when the movie is looped the source timestamps are not
21267 changed, so it will generate non monotonically increasing timestamps.
21269 @item discontinuity
21270 Specifies the time difference between frames above which the point is
21271 considered a timestamp discontinuity which is removed by adjusting the later
21275 It allows overlaying a second video on top of the main input of
21276 a filtergraph, as shown in this graph:
21278 input -----------> deltapts0 --> overlay --> output
21281 movie --> scale--> deltapts1 -------+
21283 @subsection Examples
21287 Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
21288 on top of the input labelled "in":
21290 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
21291 [in] setpts=PTS-STARTPTS [main];
21292 [main][over] overlay=16:16 [out]
21296 Read from a video4linux2 device, and overlay it on top of the input
21299 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
21300 [in] setpts=PTS-STARTPTS [main];
21301 [main][over] overlay=16:16 [out]
21305 Read the first video stream and the audio stream with id 0x81 from
21306 dvd.vob; the video is connected to the pad named "video" and the audio is
21307 connected to the pad named "audio":
21309 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
21313 @subsection Commands
21315 Both movie and amovie support the following commands:
21318 Perform seek using "av_seek_frame".
21319 The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
21322 @var{stream_index}: If stream_index is -1, a default
21323 stream is selected, and @var{timestamp} is automatically converted
21324 from AV_TIME_BASE units to the stream specific time_base.
21326 @var{timestamp}: Timestamp in AVStream.time_base units
21327 or, if no stream is specified, in AV_TIME_BASE units.
21329 @var{flags}: Flags which select direction and seeking mode.
21333 Get movie duration in AV_TIME_BASE units.
21337 @c man end MULTIMEDIA SOURCES