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
498 Reduce audio bit resolution.
500 This filter is bit crusher with enhanced functionality. A bit crusher
501 is used to audibly reduce number of bits an audio signal is sampled
502 with. This doesn't change the bit depth at all, it just produces the
503 effect. Material reduced in bit depth sounds more harsh and "digital".
504 This filter is able to even round to continuous values instead of discrete
506 Additionally it has a D/C offset which results in different crushing of
507 the lower and the upper half of the signal.
508 An Anti-Aliasing setting is able to produce "softer" crushing sounds.
510 Another feature of this filter is the logarithmic mode.
511 This setting switches from linear distances between bits to logarithmic ones.
512 The result is a much more "natural" sounding crusher which doesn't gate low
513 signals for example. The human ear has a logarithmic perception,
514 so this kind of crushing is much more pleasant.
515 Logarithmic crushing is also able to get anti-aliased.
517 The filter accepts the following options:
533 Can be linear: @code{lin} or logarithmic: @code{log}.
542 Set sample reduction.
545 Enable LFO. By default disabled.
556 Delay audio filtering until a given wallclock timestamp. See the @ref{cue}
560 Remove impulsive noise from input audio.
562 Samples detected as impulsive noise are replaced by interpolated samples using
563 autoregressive modelling.
567 Set window size, in milliseconds. Allowed range is from @code{10} to
568 @code{100}. Default value is @code{55} milliseconds.
569 This sets size of window which will be processed at once.
572 Set window overlap, in percentage of window size. Allowed range is from
573 @code{50} to @code{95}. Default value is @code{75} percent.
574 Setting this to a very high value increases impulsive noise removal but makes
575 whole process much slower.
578 Set autoregression order, in percentage of window size. Allowed range is from
579 @code{0} to @code{25}. Default value is @code{2} percent. This option also
580 controls quality of interpolated samples using neighbour good samples.
583 Set threshold value. Allowed range is from @code{1} to @code{100}.
584 Default value is @code{2}.
585 This controls the strength of impulsive noise which is going to be removed.
586 The lower value, the more samples will be detected as impulsive noise.
589 Set burst fusion, in percentage of window size. Allowed range is @code{0} to
590 @code{10}. Default value is @code{2}.
591 If any two samples deteced as noise are spaced less than this value then any
592 sample inbetween those two samples will be also detected as noise.
597 It accepts the following values:
600 Select overlap-add method. Even not interpolated samples are slightly
601 changed with this method.
604 Select overlap-save method. Not interpolated samples remain unchanged.
607 Default value is @code{a}.
611 Remove clipped samples from input audio.
613 Samples detected as clipped are replaced by interpolated samples using
614 autoregressive modelling.
618 Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}.
619 Default value is @code{55} milliseconds.
620 This sets size of window which will be processed at once.
623 Set window overlap, in percentage of window size. Allowed range is from @code{50}
624 to @code{95}. Default value is @code{75} percent.
627 Set autoregression order, in percentage of window size. Allowed range is from
628 @code{0} to @code{25}. Default value is @code{8} percent. This option also controls
629 quality of interpolated samples using neighbour good samples.
632 Set threshold value. Allowed range is from @code{1} to @code{100}.
633 Default value is @code{10}. Higher values make clip detection less aggressive.
636 Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}.
637 Default value is @code{1000}. Higher values make clip detection less aggressive.
642 It accepts the following values:
645 Select overlap-add method. Even not interpolated samples are slightly changed
649 Select overlap-save method. Not interpolated samples remain unchanged.
652 Default value is @code{a}.
657 Delay one or more audio channels.
659 Samples in delayed channel are filled with silence.
661 The filter accepts the following option:
665 Set list of delays in milliseconds for each channel separated by '|'.
666 Unused delays will be silently ignored. If number of given delays is
667 smaller than number of channels all remaining channels will not be delayed.
668 If you want to delay exact number of samples, append 'S' to number.
675 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
676 the second channel (and any other channels that may be present) unchanged.
682 Delay second channel by 500 samples, the third channel by 700 samples and leave
683 the first channel (and any other channels that may be present) unchanged.
689 @section aderivative, aintegral
691 Compute derivative/integral of audio stream.
693 Applying both filters one after another produces original audio.
697 Apply echoing to the input audio.
699 Echoes are reflected sound and can occur naturally amongst mountains
700 (and sometimes large buildings) when talking or shouting; digital echo
701 effects emulate this behaviour and are often used to help fill out the
702 sound of a single instrument or vocal. The time difference between the
703 original signal and the reflection is the @code{delay}, and the
704 loudness of the reflected signal is the @code{decay}.
705 Multiple echoes can have different delays and decays.
707 A description of the accepted parameters follows.
711 Set input gain of reflected signal. Default is @code{0.6}.
714 Set output gain of reflected signal. Default is @code{0.3}.
717 Set list of time intervals in milliseconds between original signal and reflections
718 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
719 Default is @code{1000}.
722 Set list of loudness of reflected signals separated by '|'.
723 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
724 Default is @code{0.5}.
731 Make it sound as if there are twice as many instruments as are actually playing:
733 aecho=0.8:0.88:60:0.4
737 If delay is very short, then it sound like a (metallic) robot playing music:
743 A longer delay will sound like an open air concert in the mountains:
745 aecho=0.8:0.9:1000:0.3
749 Same as above but with one more mountain:
751 aecho=0.8:0.9:1000|1800:0.3|0.25
756 Audio emphasis filter creates or restores material directly taken from LPs or
757 emphased CDs with different filter curves. E.g. to store music on vinyl the
758 signal has to be altered by a filter first to even out the disadvantages of
759 this recording medium.
760 Once the material is played back the inverse filter has to be applied to
761 restore the distortion of the frequency response.
763 The filter accepts the following options:
773 Set filter mode. For restoring material use @code{reproduction} mode, otherwise
774 use @code{production} mode. Default is @code{reproduction} mode.
777 Set filter type. Selects medium. Can be one of the following:
789 select Compact Disc (CD).
795 select 50µs (FM-KF).
797 select 75µs (FM-KF).
803 Modify an audio signal according to the specified expressions.
805 This filter accepts one or more expressions (one for each channel),
806 which are evaluated and used to modify a corresponding audio signal.
808 It accepts the following parameters:
812 Set the '|'-separated expressions list for each separate channel. If
813 the number of input channels is greater than the number of
814 expressions, the last specified expression is used for the remaining
817 @item channel_layout, c
818 Set output channel layout. If not specified, the channel layout is
819 specified by the number of expressions. If set to @samp{same}, it will
820 use by default the same input channel layout.
823 Each expression in @var{exprs} can contain the following constants and functions:
827 channel number of the current expression
830 number of the evaluated sample, starting from 0
836 time of the evaluated sample expressed in seconds
839 @item nb_out_channels
840 input and output number of channels
843 the value of input channel with number @var{CH}
846 Note: this filter is slow. For faster processing you should use a
855 aeval=val(ch)/2:c=same
859 Invert phase of the second channel:
868 Apply fade-in/out effect to input audio.
870 A description of the accepted parameters follows.
874 Specify the effect type, can be either @code{in} for fade-in, or
875 @code{out} for a fade-out effect. Default is @code{in}.
877 @item start_sample, ss
878 Specify the number of the start sample for starting to apply the fade
879 effect. Default is 0.
882 Specify the number of samples for which the fade effect has to last. At
883 the end of the fade-in effect the output audio will have the same
884 volume as the input audio, at the end of the fade-out transition
885 the output audio will be silence. Default is 44100.
888 Specify the start time of the fade effect. Default is 0.
889 The value must be specified as a time duration; see
890 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
891 for the accepted syntax.
892 If set this option is used instead of @var{start_sample}.
895 Specify the duration of the fade effect. See
896 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
897 for the accepted syntax.
898 At the end of the fade-in effect the output audio will have the same
899 volume as the input audio, at the end of the fade-out transition
900 the output audio will be silence.
901 By default the duration is determined by @var{nb_samples}.
902 If set this option is used instead of @var{nb_samples}.
905 Set curve for fade transition.
907 It accepts the following values:
910 select triangular, linear slope (default)
912 select quarter of sine wave
914 select half of sine wave
916 select exponential sine wave
920 select inverted parabola
934 select inverted quarter of sine wave
936 select inverted half of sine wave
938 select double-exponential seat
940 select double-exponential sigmoid
948 Fade in first 15 seconds of audio:
954 Fade out last 25 seconds of a 900 seconds audio:
956 afade=t=out:st=875:d=25
961 Apply arbitrary expressions to samples in frequency domain.
965 Set frequency domain real expression for each separate channel separated
966 by '|'. Default is "1".
967 If the number of input channels is greater than the number of
968 expressions, the last specified expression is used for the remaining
972 Set frequency domain imaginary expression for each separate channel
973 separated by '|'. If not set, @var{real} option is used.
975 Each expression in @var{real} and @var{imag} can contain the following
983 current frequency bin number
986 number of available bins
989 channel number of the current expression
1001 It accepts the following values:
1017 Default is @code{w4096}
1020 Set window function. Default is @code{hann}.
1023 Set window overlap. If set to 1, the recommended overlap for selected
1024 window function will be picked. Default is @code{0.75}.
1027 @subsection Examples
1031 Leave almost only low frequencies in audio:
1033 afftfilt="1-clip((b/nb)*b,0,1)"
1040 Apply an arbitrary Frequency Impulse Response filter.
1042 This filter is designed for applying long FIR filters,
1043 up to 30 seconds long.
1045 It can be used as component for digital crossover filters,
1046 room equalization, cross talk cancellation, wavefield synthesis,
1047 auralization, ambiophonics and ambisonics.
1049 This filter uses second stream as FIR coefficients.
1050 If second stream holds single channel, it will be used
1051 for all input channels in first stream, otherwise
1052 number of channels in second stream must be same as
1053 number of channels in first stream.
1055 It accepts the following parameters:
1059 Set dry gain. This sets input gain.
1062 Set wet gain. This sets final output gain.
1065 Set Impulse Response filter length. Default is 1, which means whole IR is processed.
1068 Enable applying gain measured from power of IR.
1071 Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds.
1072 Allowed range is 0.1 to 60 seconds.
1075 Show IR frequency reponse, magnitude and phase in additional video stream.
1076 By default it is disabled.
1079 Set for which IR channel to display frequency response. By default is first channel
1080 displayed. This option is used only when @var{response} is enabled.
1083 Set video stream size. This option is used only when @var{response} is enabled.
1086 @subsection Examples
1090 Apply reverb to stream using mono IR file as second input, complete command using ffmpeg:
1092 ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
1099 Set output format constraints for the input audio. The framework will
1100 negotiate the most appropriate format to minimize conversions.
1102 It accepts the following parameters:
1106 A '|'-separated list of requested sample formats.
1109 A '|'-separated list of requested sample rates.
1111 @item channel_layouts
1112 A '|'-separated list of requested channel layouts.
1114 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1115 for the required syntax.
1118 If a parameter is omitted, all values are allowed.
1120 Force the output to either unsigned 8-bit or signed 16-bit stereo
1122 aformat=sample_fmts=u8|s16:channel_layouts=stereo
1127 A gate is mainly used to reduce lower parts of a signal. This kind of signal
1128 processing reduces disturbing noise between useful signals.
1130 Gating is done by detecting the volume below a chosen level @var{threshold}
1131 and dividing it by the factor set with @var{ratio}. The bottom of the noise
1132 floor is set via @var{range}. Because an exact manipulation of the signal
1133 would cause distortion of the waveform the reduction can be levelled over
1134 time. This is done by setting @var{attack} and @var{release}.
1136 @var{attack} determines how long the signal has to fall below the threshold
1137 before any reduction will occur and @var{release} sets the time the signal
1138 has to rise above the threshold to reduce the reduction again.
1139 Shorter signals than the chosen attack time will be left untouched.
1143 Set input level before filtering.
1144 Default is 1. Allowed range is from 0.015625 to 64.
1147 Set the level of gain reduction when the signal is below the threshold.
1148 Default is 0.06125. Allowed range is from 0 to 1.
1151 If a signal rises above this level the gain reduction is released.
1152 Default is 0.125. Allowed range is from 0 to 1.
1155 Set a ratio by which the signal is reduced.
1156 Default is 2. Allowed range is from 1 to 9000.
1159 Amount of milliseconds the signal has to rise above the threshold before gain
1161 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
1164 Amount of milliseconds the signal has to fall below the threshold before the
1165 reduction is increased again. Default is 250 milliseconds.
1166 Allowed range is from 0.01 to 9000.
1169 Set amount of amplification of signal after processing.
1170 Default is 1. Allowed range is from 1 to 64.
1173 Curve the sharp knee around the threshold to enter gain reduction more softly.
1174 Default is 2.828427125. Allowed range is from 1 to 8.
1177 Choose if exact signal should be taken for detection or an RMS like one.
1178 Default is @code{rms}. Can be @code{peak} or @code{rms}.
1181 Choose if the average level between all channels or the louder channel affects
1183 Default is @code{average}. Can be @code{average} or @code{maximum}.
1188 Apply an arbitrary Infinite Impulse Response filter.
1190 It accepts the following parameters:
1194 Set numerator/zeros coefficients.
1197 Set denominator/poles coefficients.
1209 Set coefficients format.
1215 Z-plane zeros/poles, cartesian (default)
1217 Z-plane zeros/poles, polar radians
1219 Z-plane zeros/poles, polar degrees
1223 Set kind of processing.
1224 Can be @code{d} - direct or @code{s} - serial cascading. Defauls is @code{s}.
1227 Set filtering precision.
1231 double-precision floating-point (default)
1233 single-precision floating-point
1241 Show IR frequency reponse, magnitude and phase in additional video stream.
1242 By default it is disabled.
1245 Set for which IR channel to display frequency response. By default is first channel
1246 displayed. This option is used only when @var{response} is enabled.
1249 Set video stream size. This option is used only when @var{response} is enabled.
1252 Coefficients in @code{tf} format are separated by spaces and are in ascending
1255 Coefficients in @code{zp} format are separated by spaces and order of coefficients
1256 doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i}
1259 Different coefficients and gains can be provided for every channel, in such case
1260 use '|' to separate coefficients or gains. Last provided coefficients will be
1261 used for all remaining channels.
1263 @subsection Examples
1267 Apply 2 pole elliptic notch at arround 5000Hz for 48000 Hz sample rate:
1269 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
1273 Same as above but in @code{zp} format:
1275 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
1281 The limiter prevents an input signal from rising over a desired threshold.
1282 This limiter uses lookahead technology to prevent your signal from distorting.
1283 It means that there is a small delay after the signal is processed. Keep in mind
1284 that the delay it produces is the attack time you set.
1286 The filter accepts the following options:
1290 Set input gain. Default is 1.
1293 Set output gain. Default is 1.
1296 Don't let signals above this level pass the limiter. Default is 1.
1299 The limiter will reach its attenuation level in this amount of time in
1300 milliseconds. Default is 5 milliseconds.
1303 Come back from limiting to attenuation 1.0 in this amount of milliseconds.
1304 Default is 50 milliseconds.
1307 When gain reduction is always needed ASC takes care of releasing to an
1308 average reduction level rather than reaching a reduction of 0 in the release
1312 Select how much the release time is affected by ASC, 0 means nearly no changes
1313 in release time while 1 produces higher release times.
1316 Auto level output signal. Default is enabled.
1317 This normalizes audio back to 0dB if enabled.
1320 Depending on picked setting it is recommended to upsample input 2x or 4x times
1321 with @ref{aresample} before applying this filter.
1325 Apply a two-pole all-pass filter with central frequency (in Hz)
1326 @var{frequency}, and filter-width @var{width}.
1327 An all-pass filter changes the audio's frequency to phase relationship
1328 without changing its frequency to amplitude relationship.
1330 The filter accepts the following options:
1334 Set frequency in Hz.
1337 Set method to specify band-width of filter.
1352 Specify the band-width of a filter in width_type units.
1355 Specify which channels to filter, by default all available are filtered.
1358 @subsection Commands
1360 This filter supports the following commands:
1363 Change allpass frequency.
1364 Syntax for the command is : "@var{frequency}"
1367 Change allpass width_type.
1368 Syntax for the command is : "@var{width_type}"
1371 Change allpass width.
1372 Syntax for the command is : "@var{width}"
1379 The filter accepts the following options:
1383 Set the number of loops. Setting this value to -1 will result in infinite loops.
1387 Set maximal number of samples. Default is 0.
1390 Set first sample of loop. Default is 0.
1396 Merge two or more audio streams into a single multi-channel stream.
1398 The filter accepts the following options:
1403 Set the number of inputs. Default is 2.
1407 If the channel layouts of the inputs are disjoint, and therefore compatible,
1408 the channel layout of the output will be set accordingly and the channels
1409 will be reordered as necessary. If the channel layouts of the inputs are not
1410 disjoint, the output will have all the channels of the first input then all
1411 the channels of the second input, in that order, and the channel layout of
1412 the output will be the default value corresponding to the total number of
1415 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
1416 is FC+BL+BR, then the output will be in 5.1, with the channels in the
1417 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
1418 first input, b1 is the first channel of the second input).
1420 On the other hand, if both input are in stereo, the output channels will be
1421 in the default order: a1, a2, b1, b2, and the channel layout will be
1422 arbitrarily set to 4.0, which may or may not be the expected value.
1424 All inputs must have the same sample rate, and format.
1426 If inputs do not have the same duration, the output will stop with the
1429 @subsection Examples
1433 Merge two mono files into a stereo stream:
1435 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
1439 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
1441 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
1447 Mixes multiple audio inputs into a single output.
1449 Note that this filter only supports float samples (the @var{amerge}
1450 and @var{pan} audio filters support many formats). If the @var{amix}
1451 input has integer samples then @ref{aresample} will be automatically
1452 inserted to perform the conversion to float samples.
1456 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
1458 will mix 3 input audio streams to a single output with the same duration as the
1459 first input and a dropout transition time of 3 seconds.
1461 It accepts the following parameters:
1465 The number of inputs. If unspecified, it defaults to 2.
1468 How to determine the end-of-stream.
1472 The duration of the longest input. (default)
1475 The duration of the shortest input.
1478 The duration of the first input.
1482 @item dropout_transition
1483 The transition time, in seconds, for volume renormalization when an input
1484 stream ends. The default value is 2 seconds.
1487 Specify weight of each input audio stream as sequence.
1488 Each weight is separated by space. By default all inputs have same weight.
1493 Multiply first audio stream with second audio stream and store result
1494 in output audio stream. Multiplication is done by multiplying each
1495 sample from first stream with sample at same position from second stream.
1497 With this element-wise multiplication one can create amplitude fades and
1498 amplitude modulations.
1500 @section anequalizer
1502 High-order parametric multiband equalizer for each channel.
1504 It accepts the following parameters:
1508 This option string is in format:
1509 "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
1510 Each equalizer band is separated by '|'.
1514 Set channel number to which equalization will be applied.
1515 If input doesn't have that channel the entry is ignored.
1518 Set central frequency for band.
1519 If input doesn't have that frequency the entry is ignored.
1522 Set band width in hertz.
1525 Set band gain in dB.
1528 Set filter type for band, optional, can be:
1532 Butterworth, this is default.
1543 With this option activated frequency response of anequalizer is displayed
1547 Set video stream size. Only useful if curves option is activated.
1550 Set max gain that will be displayed. Only useful if curves option is activated.
1551 Setting this to a reasonable value makes it possible to display gain which is derived from
1552 neighbour bands which are too close to each other and thus produce higher gain
1553 when both are activated.
1556 Set frequency scale used to draw frequency response in video output.
1557 Can be linear or logarithmic. Default is logarithmic.
1560 Set color for each channel curve which is going to be displayed in video stream.
1561 This is list of color names separated by space or by '|'.
1562 Unrecognised or missing colors will be replaced by white color.
1565 @subsection Examples
1569 Lower gain by 10 of central frequency 200Hz and width 100 Hz
1570 for first 2 channels using Chebyshev type 1 filter:
1572 anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
1576 @subsection Commands
1578 This filter supports the following commands:
1581 Alter existing filter parameters.
1582 Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
1584 @var{fN} is existing filter number, starting from 0, if no such filter is available
1586 @var{freq} set new frequency parameter.
1587 @var{width} set new width parameter in herz.
1588 @var{gain} set new gain parameter in dB.
1590 Full filter invocation with asendcmd may look like this:
1591 asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
1596 Pass the audio source unchanged to the output.
1600 Pad the end of an audio stream with silence.
1602 This can be used together with @command{ffmpeg} @option{-shortest} to
1603 extend audio streams to the same length as the video stream.
1605 A description of the accepted options follows.
1609 Set silence packet size. Default value is 4096.
1612 Set the number of samples of silence to add to the end. After the
1613 value is reached, the stream is terminated. This option is mutually
1614 exclusive with @option{whole_len}.
1617 Set the minimum total number of samples in the output audio stream. If
1618 the value is longer than the input audio length, silence is added to
1619 the end, until the value is reached. This option is mutually exclusive
1620 with @option{pad_len}.
1623 If neither the @option{pad_len} nor the @option{whole_len} option is
1624 set, the filter will add silence to the end of the input stream
1627 @subsection Examples
1631 Add 1024 samples of silence to the end of the input:
1637 Make sure the audio output will contain at least 10000 samples, pad
1638 the input with silence if required:
1640 apad=whole_len=10000
1644 Use @command{ffmpeg} to pad the audio input with silence, so that the
1645 video stream will always result the shortest and will be converted
1646 until the end in the output file when using the @option{shortest}
1649 ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
1654 Add a phasing effect to the input audio.
1656 A phaser filter creates series of peaks and troughs in the frequency spectrum.
1657 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
1659 A description of the accepted parameters follows.
1663 Set input gain. Default is 0.4.
1666 Set output gain. Default is 0.74
1669 Set delay in milliseconds. Default is 3.0.
1672 Set decay. Default is 0.4.
1675 Set modulation speed in Hz. Default is 0.5.
1678 Set modulation type. Default is triangular.
1680 It accepts the following values:
1689 Audio pulsator is something between an autopanner and a tremolo.
1690 But it can produce funny stereo effects as well. Pulsator changes the volume
1691 of the left and right channel based on a LFO (low frequency oscillator) with
1692 different waveforms and shifted phases.
1693 This filter have the ability to define an offset between left and right
1694 channel. An offset of 0 means that both LFO shapes match each other.
1695 The left and right channel are altered equally - a conventional tremolo.
1696 An offset of 50% means that the shape of the right channel is exactly shifted
1697 in phase (or moved backwards about half of the frequency) - pulsator acts as
1698 an autopanner. At 1 both curves match again. Every setting in between moves the
1699 phase shift gapless between all stages and produces some "bypassing" sounds with
1700 sine and triangle waveforms. The more you set the offset near 1 (starting from
1701 the 0.5) the faster the signal passes from the left to the right speaker.
1703 The filter accepts the following options:
1707 Set input gain. By default it is 1. Range is [0.015625 - 64].
1710 Set output gain. By default it is 1. Range is [0.015625 - 64].
1713 Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
1714 sawup or sawdown. Default is sine.
1717 Set modulation. Define how much of original signal is affected by the LFO.
1720 Set left channel offset. Default is 0. Allowed range is [0 - 1].
1723 Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
1726 Set pulse width. Default is 1. Allowed range is [0 - 2].
1729 Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
1732 Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
1736 Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
1740 Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
1741 if timing is set to hz.
1747 Resample the input audio to the specified parameters, using the
1748 libswresample library. If none are specified then the filter will
1749 automatically convert between its input and output.
1751 This filter is also able to stretch/squeeze the audio data to make it match
1752 the timestamps or to inject silence / cut out audio to make it match the
1753 timestamps, do a combination of both or do neither.
1755 The filter accepts the syntax
1756 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
1757 expresses a sample rate and @var{resampler_options} is a list of
1758 @var{key}=@var{value} pairs, separated by ":". See the
1759 @ref{Resampler Options,,"Resampler Options" section in the
1760 ffmpeg-resampler(1) manual,ffmpeg-resampler}
1761 for the complete list of supported options.
1763 @subsection Examples
1767 Resample the input audio to 44100Hz:
1773 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
1774 samples per second compensation:
1776 aresample=async=1000
1782 Reverse an audio clip.
1784 Warning: This filter requires memory to buffer the entire clip, so trimming
1787 @subsection Examples
1791 Take the first 5 seconds of a clip, and reverse it.
1793 atrim=end=5,areverse
1797 @section asetnsamples
1799 Set the number of samples per each output audio frame.
1801 The last output packet may contain a different number of samples, as
1802 the filter will flush all the remaining samples when the input audio
1805 The filter accepts the following options:
1809 @item nb_out_samples, n
1810 Set the number of frames per each output audio frame. The number is
1811 intended as the number of samples @emph{per each channel}.
1812 Default value is 1024.
1815 If set to 1, the filter will pad the last audio frame with zeroes, so
1816 that the last frame will contain the same number of samples as the
1817 previous ones. Default value is 1.
1820 For example, to set the number of per-frame samples to 1234 and
1821 disable padding for the last frame, use:
1823 asetnsamples=n=1234:p=0
1828 Set the sample rate without altering the PCM data.
1829 This will result in a change of speed and pitch.
1831 The filter accepts the following options:
1834 @item sample_rate, r
1835 Set the output sample rate. Default is 44100 Hz.
1840 Show a line containing various information for each input audio frame.
1841 The input audio is not modified.
1843 The shown line contains a sequence of key/value pairs of the form
1844 @var{key}:@var{value}.
1846 The following values are shown in the output:
1850 The (sequential) number of the input frame, starting from 0.
1853 The presentation timestamp of the input frame, in time base units; the time base
1854 depends on the filter input pad, and is usually 1/@var{sample_rate}.
1857 The presentation timestamp of the input frame in seconds.
1860 position of the frame in the input stream, -1 if this information in
1861 unavailable and/or meaningless (for example in case of synthetic audio)
1870 The sample rate for the audio frame.
1873 The number of samples (per channel) in the frame.
1876 The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
1877 audio, the data is treated as if all the planes were concatenated.
1879 @item plane_checksums
1880 A list of Adler-32 checksums for each data plane.
1886 Display time domain statistical information about the audio channels.
1887 Statistics are calculated and displayed for each audio channel and,
1888 where applicable, an overall figure is also given.
1890 It accepts the following option:
1893 Short window length in seconds, used for peak and trough RMS measurement.
1894 Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}.
1898 Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
1899 where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
1902 Available keys for each channel are:
1936 For example full key look like this @code{lavfi.astats.1.DC_offset} or
1937 this @code{lavfi.astats.Overall.Peak_count}.
1939 For description what each key means read below.
1942 Set number of frame after which stats are going to be recalculated.
1943 Default is disabled.
1946 A description of each shown parameter follows:
1950 Mean amplitude displacement from zero.
1953 Minimal sample level.
1956 Maximal sample level.
1958 @item Min difference
1959 Minimal difference between two consecutive samples.
1961 @item Max difference
1962 Maximal difference between two consecutive samples.
1964 @item Mean difference
1965 Mean difference between two consecutive samples.
1966 The average of each difference between two consecutive samples.
1968 @item RMS difference
1969 Root Mean Square difference between two consecutive samples.
1973 Standard peak and RMS level measured in dBFS.
1977 Peak and trough values for RMS level measured over a short window.
1980 Standard ratio of peak to RMS level (note: not in dB).
1983 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
1984 (i.e. either @var{Min level} or @var{Max level}).
1987 Number of occasions (not the number of samples) that the signal attained either
1988 @var{Min level} or @var{Max level}.
1991 Overall bit depth of audio. Number of bits used for each sample.
1994 Measured dynamic range of audio in dB.
2001 The filter accepts exactly one parameter, the audio tempo. If not
2002 specified then the filter will assume nominal 1.0 tempo. Tempo must
2003 be in the [0.5, 100.0] range.
2005 Note that tempo greater than 2 will skip some samples rather than
2006 blend them in. If for any reason this is a concern it is always
2007 possible to daisy-chain several instances of atempo to achieve the
2008 desired product tempo.
2010 @subsection Examples
2014 Slow down audio to 80% tempo:
2020 To speed up audio to 300% tempo:
2026 To speed up audio to 300% tempo by daisy-chaining two atempo instances:
2028 atempo=sqrt(3),atempo=sqrt(3)
2034 Trim the input so that the output contains one continuous subpart of the input.
2036 It accepts the following parameters:
2039 Timestamp (in seconds) of the start of the section to keep. I.e. the audio
2040 sample with the timestamp @var{start} will be the first sample in the output.
2043 Specify time of the first audio sample that will be dropped, i.e. the
2044 audio sample immediately preceding the one with the timestamp @var{end} will be
2045 the last sample in the output.
2048 Same as @var{start}, except this option sets the start timestamp in samples
2052 Same as @var{end}, except this option sets the end timestamp in samples instead
2056 The maximum duration of the output in seconds.
2059 The number of the first sample that should be output.
2062 The number of the first sample that should be dropped.
2065 @option{start}, @option{end}, and @option{duration} are expressed as time
2066 duration specifications; see
2067 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
2069 Note that the first two sets of the start/end options and the @option{duration}
2070 option look at the frame timestamp, while the _sample options simply count the
2071 samples that pass through the filter. So start/end_pts and start/end_sample will
2072 give different results when the timestamps are wrong, inexact or do not start at
2073 zero. Also note that this filter does not modify the timestamps. If you wish
2074 to have the output timestamps start at zero, insert the asetpts filter after the
2077 If multiple start or end options are set, this filter tries to be greedy and
2078 keep all samples that match at least one of the specified constraints. To keep
2079 only the part that matches all the constraints at once, chain multiple atrim
2082 The defaults are such that all the input is kept. So it is possible to set e.g.
2083 just the end values to keep everything before the specified time.
2088 Drop everything except the second minute of input:
2090 ffmpeg -i INPUT -af atrim=60:120
2094 Keep only the first 1000 samples:
2096 ffmpeg -i INPUT -af atrim=end_sample=1000
2103 Apply a two-pole Butterworth band-pass filter with central
2104 frequency @var{frequency}, and (3dB-point) band-width width.
2105 The @var{csg} option selects a constant skirt gain (peak gain = Q)
2106 instead of the default: constant 0dB peak gain.
2107 The filter roll off at 6dB per octave (20dB per decade).
2109 The filter accepts the following options:
2113 Set the filter's central frequency. Default is @code{3000}.
2116 Constant skirt gain if set to 1. Defaults to 0.
2119 Set method to specify band-width of filter.
2134 Specify the band-width of a filter in width_type units.
2137 Specify which channels to filter, by default all available are filtered.
2140 @subsection Commands
2142 This filter supports the following commands:
2145 Change bandpass frequency.
2146 Syntax for the command is : "@var{frequency}"
2149 Change bandpass width_type.
2150 Syntax for the command is : "@var{width_type}"
2153 Change bandpass width.
2154 Syntax for the command is : "@var{width}"
2159 Apply a two-pole Butterworth band-reject filter with central
2160 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
2161 The filter roll off at 6dB per octave (20dB per decade).
2163 The filter accepts the following options:
2167 Set the filter's central frequency. Default is @code{3000}.
2170 Set method to specify band-width of filter.
2185 Specify the band-width of a filter in width_type units.
2188 Specify which channels to filter, by default all available are filtered.
2191 @subsection Commands
2193 This filter supports the following commands:
2196 Change bandreject frequency.
2197 Syntax for the command is : "@var{frequency}"
2200 Change bandreject width_type.
2201 Syntax for the command is : "@var{width_type}"
2204 Change bandreject width.
2205 Syntax for the command is : "@var{width}"
2208 @section bass, lowshelf
2210 Boost or cut the bass (lower) frequencies of the audio using a two-pole
2211 shelving filter with a response similar to that of a standard
2212 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
2214 The filter accepts the following options:
2218 Give the gain at 0 Hz. Its useful range is about -20
2219 (for a large cut) to +20 (for a large boost).
2220 Beware of clipping when using a positive gain.
2223 Set the filter's central frequency and so can be used
2224 to extend or reduce the frequency range to be boosted or cut.
2225 The default value is @code{100} Hz.
2228 Set method to specify band-width of filter.
2243 Determine how steep is the filter's shelf transition.
2246 Specify which channels to filter, by default all available are filtered.
2249 @subsection Commands
2251 This filter supports the following commands:
2254 Change bass frequency.
2255 Syntax for the command is : "@var{frequency}"
2258 Change bass width_type.
2259 Syntax for the command is : "@var{width_type}"
2263 Syntax for the command is : "@var{width}"
2267 Syntax for the command is : "@var{gain}"
2272 Apply a biquad IIR filter with the given coefficients.
2273 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
2274 are the numerator and denominator coefficients respectively.
2275 and @var{channels}, @var{c} specify which channels to filter, by default all
2276 available are filtered.
2278 @subsection Commands
2280 This filter supports the following commands:
2288 Change biquad parameter.
2289 Syntax for the command is : "@var{value}"
2293 Bauer stereo to binaural transformation, which improves headphone listening of
2294 stereo audio records.
2296 To enable compilation of this filter you need to configure FFmpeg with
2297 @code{--enable-libbs2b}.
2299 It accepts the following parameters:
2303 Pre-defined crossfeed level.
2307 Default level (fcut=700, feed=50).
2310 Chu Moy circuit (fcut=700, feed=60).
2313 Jan Meier circuit (fcut=650, feed=95).
2318 Cut frequency (in Hz).
2327 Remap input channels to new locations.
2329 It accepts the following parameters:
2332 Map channels from input to output. The argument is a '|'-separated list of
2333 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
2334 @var{in_channel} form. @var{in_channel} can be either the name of the input
2335 channel (e.g. FL for front left) or its index in the input channel layout.
2336 @var{out_channel} is the name of the output channel or its index in the output
2337 channel layout. If @var{out_channel} is not given then it is implicitly an
2338 index, starting with zero and increasing by one for each mapping.
2340 @item channel_layout
2341 The channel layout of the output stream.
2344 If no mapping is present, the filter will implicitly map input channels to
2345 output channels, preserving indices.
2347 @subsection Examples
2351 For example, assuming a 5.1+downmix input MOV file,
2353 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
2355 will create an output WAV file tagged as stereo from the downmix channels of
2359 To fix a 5.1 WAV improperly encoded in AAC's native channel order
2361 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
2365 @section channelsplit
2367 Split each channel from an input audio stream into a separate output stream.
2369 It accepts the following parameters:
2371 @item channel_layout
2372 The channel layout of the input stream. The default is "stereo".
2374 A channel layout describing the channels to be extracted as separate output streams
2375 or "all" to extract each input channel as a separate stream. The default is "all".
2377 Choosing channels not present in channel layout in the input will result in an error.
2380 @subsection Examples
2384 For example, assuming a stereo input MP3 file,
2386 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
2388 will create an output Matroska file with two audio streams, one containing only
2389 the left channel and the other the right channel.
2392 Split a 5.1 WAV file into per-channel files:
2394 ffmpeg -i in.wav -filter_complex
2395 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
2396 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
2397 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
2402 Extract only LFE from a 5.1 WAV file:
2404 ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
2405 -map '[LFE]' lfe.wav
2410 Add a chorus effect to the audio.
2412 Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
2414 Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
2415 constant, with chorus, it is varied using using sinusoidal or triangular modulation.
2416 The modulation depth defines the range the modulated delay is played before or after
2417 the delay. Hence the delayed sound will sound slower or faster, that is the delayed
2418 sound tuned around the original one, like in a chorus where some vocals are slightly
2421 It accepts the following parameters:
2424 Set input gain. Default is 0.4.
2427 Set output gain. Default is 0.4.
2430 Set delays. A typical delay is around 40ms to 60ms.
2442 @subsection Examples
2448 chorus=0.7:0.9:55:0.4:0.25:2
2454 chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
2458 Fuller sounding chorus with three delays:
2460 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
2465 Compress or expand the audio's dynamic range.
2467 It accepts the following parameters:
2473 A list of times in seconds for each channel over which the instantaneous level
2474 of the input signal is averaged to determine its volume. @var{attacks} refers to
2475 increase of volume and @var{decays} refers to decrease of volume. For most
2476 situations, the attack time (response to the audio getting louder) should be
2477 shorter than the decay time, because the human ear is more sensitive to sudden
2478 loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
2479 a typical value for decay is 0.8 seconds.
2480 If specified number of attacks & decays is lower than number of channels, the last
2481 set attack/decay will be used for all remaining channels.
2484 A list of points for the transfer function, specified in dB relative to the
2485 maximum possible signal amplitude. Each key points list must be defined using
2486 the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
2487 @code{x0/y0 x1/y1 x2/y2 ....}
2489 The input values must be in strictly increasing order but the transfer function
2490 does not have to be monotonically rising. The point @code{0/0} is assumed but
2491 may be overridden (by @code{0/out-dBn}). Typical values for the transfer
2492 function are @code{-70/-70|-60/-20|1/0}.
2495 Set the curve radius in dB for all joints. It defaults to 0.01.
2498 Set the additional gain in dB to be applied at all points on the transfer
2499 function. This allows for easy adjustment of the overall gain.
2503 Set an initial volume, in dB, to be assumed for each channel when filtering
2504 starts. This permits the user to supply a nominal level initially, so that, for
2505 example, a very large gain is not applied to initial signal levels before the
2506 companding has begun to operate. A typical value for audio which is initially
2507 quiet is -90 dB. It defaults to 0.
2510 Set a delay, in seconds. The input audio is analyzed immediately, but audio is
2511 delayed before being fed to the volume adjuster. Specifying a delay
2512 approximately equal to the attack/decay times allows the filter to effectively
2513 operate in predictive rather than reactive mode. It defaults to 0.
2517 @subsection Examples
2521 Make music with both quiet and loud passages suitable for listening to in a
2524 compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
2527 Another example for audio with whisper and explosion parts:
2529 compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
2533 A noise gate for when the noise is at a lower level than the signal:
2535 compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
2539 Here is another noise gate, this time for when the noise is at a higher level
2540 than the signal (making it, in some ways, similar to squelch):
2542 compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
2546 2:1 compression starting at -6dB:
2548 compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
2552 2:1 compression starting at -9dB:
2554 compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
2558 2:1 compression starting at -12dB:
2560 compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
2564 2:1 compression starting at -18dB:
2566 compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
2570 3:1 compression starting at -15dB:
2572 compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
2578 compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
2584 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
2588 Hard limiter at -6dB:
2590 compand=attacks=0:points=-80/-80|-6/-6|20/-6
2594 Hard limiter at -12dB:
2596 compand=attacks=0:points=-80/-80|-12/-12|20/-12
2600 Hard noise gate at -35 dB:
2602 compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
2608 compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
2612 @section compensationdelay
2614 Compensation Delay Line is a metric based delay to compensate differing
2615 positions of microphones or speakers.
2617 For example, you have recorded guitar with two microphones placed in
2618 different location. Because the front of sound wave has fixed speed in
2619 normal conditions, the phasing of microphones can vary and depends on
2620 their location and interposition. The best sound mix can be achieved when
2621 these microphones are in phase (synchronized). Note that distance of
2622 ~30 cm between microphones makes one microphone to capture signal in
2623 antiphase to another microphone. That makes the final mix sounding moody.
2624 This filter helps to solve phasing problems by adding different delays
2625 to each microphone track and make them synchronized.
2627 The best result can be reached when you take one track as base and
2628 synchronize other tracks one by one with it.
2629 Remember that synchronization/delay tolerance depends on sample rate, too.
2630 Higher sample rates will give more tolerance.
2632 It accepts the following parameters:
2636 Set millimeters distance. This is compensation distance for fine tuning.
2640 Set cm distance. This is compensation distance for tightening distance setup.
2644 Set meters distance. This is compensation distance for hard distance setup.
2648 Set dry amount. Amount of unprocessed (dry) signal.
2652 Set wet amount. Amount of processed (wet) signal.
2656 Set temperature degree in Celsius. This is the temperature of the environment.
2661 Apply headphone crossfeed filter.
2663 Crossfeed is the process of blending the left and right channels of stereo
2665 It is mainly used to reduce extreme stereo separation of low frequencies.
2667 The intent is to produce more speaker like sound to the listener.
2669 The filter accepts the following options:
2673 Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1.
2674 This sets gain of low shelf filter for side part of stereo image.
2675 Default is -6dB. Max allowed is -30db when strength is set to 1.
2678 Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1.
2679 This sets cut off frequency of low shelf filter. Default is cut off near
2680 1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz.
2683 Set input gain. Default is 0.9.
2686 Set output gain. Default is 1.
2689 @section crystalizer
2690 Simple algorithm to expand audio dynamic range.
2692 The filter accepts the following options:
2696 Sets the intensity of effect (default: 2.0). Must be in range between 0.0
2697 (unchanged sound) to 10.0 (maximum effect).
2700 Enable clipping. By default is enabled.
2704 Apply a DC shift to the audio.
2706 This can be useful to remove a DC offset (caused perhaps by a hardware problem
2707 in the recording chain) from the audio. The effect of a DC offset is reduced
2708 headroom and hence volume. The @ref{astats} filter can be used to determine if
2709 a signal has a DC offset.
2713 Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
2717 Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
2718 used to prevent clipping.
2722 Measure audio dynamic range.
2724 DR values of 14 and higher is found in very dynamic material. DR of 8 to 13
2725 is found in transition material. And anything less that 8 have very poor dynamics
2726 and is very compressed.
2728 The filter accepts the following options:
2732 Set window length in seconds used to split audio into segments of equal length.
2733 Default is 3 seconds.
2737 Dynamic Audio Normalizer.
2739 This filter applies a certain amount of gain to the input audio in order
2740 to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
2741 contrast to more "simple" normalization algorithms, the Dynamic Audio
2742 Normalizer *dynamically* re-adjusts the gain factor to the input audio.
2743 This allows for applying extra gain to the "quiet" sections of the audio
2744 while avoiding distortions or clipping the "loud" sections. In other words:
2745 The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
2746 sections, in the sense that the volume of each section is brought to the
2747 same target level. Note, however, that the Dynamic Audio Normalizer achieves
2748 this goal *without* applying "dynamic range compressing". It will retain 100%
2749 of the dynamic range *within* each section of the audio file.
2753 Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
2754 Default is 500 milliseconds.
2755 The Dynamic Audio Normalizer processes the input audio in small chunks,
2756 referred to as frames. This is required, because a peak magnitude has no
2757 meaning for just a single sample value. Instead, we need to determine the
2758 peak magnitude for a contiguous sequence of sample values. While a "standard"
2759 normalizer would simply use the peak magnitude of the complete file, the
2760 Dynamic Audio Normalizer determines the peak magnitude individually for each
2761 frame. The length of a frame is specified in milliseconds. By default, the
2762 Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
2763 been found to give good results with most files.
2764 Note that the exact frame length, in number of samples, will be determined
2765 automatically, based on the sampling rate of the individual input audio file.
2768 Set the Gaussian filter window size. In range from 3 to 301, must be odd
2769 number. Default is 31.
2770 Probably the most important parameter of the Dynamic Audio Normalizer is the
2771 @code{window size} of the Gaussian smoothing filter. The filter's window size
2772 is specified in frames, centered around the current frame. For the sake of
2773 simplicity, this must be an odd number. Consequently, the default value of 31
2774 takes into account the current frame, as well as the 15 preceding frames and
2775 the 15 subsequent frames. Using a larger window results in a stronger
2776 smoothing effect and thus in less gain variation, i.e. slower gain
2777 adaptation. Conversely, using a smaller window results in a weaker smoothing
2778 effect and thus in more gain variation, i.e. faster gain adaptation.
2779 In other words, the more you increase this value, the more the Dynamic Audio
2780 Normalizer will behave like a "traditional" normalization filter. On the
2781 contrary, the more you decrease this value, the more the Dynamic Audio
2782 Normalizer will behave like a dynamic range compressor.
2785 Set the target peak value. This specifies the highest permissible magnitude
2786 level for the normalized audio input. This filter will try to approach the
2787 target peak magnitude as closely as possible, but at the same time it also
2788 makes sure that the normalized signal will never exceed the peak magnitude.
2789 A frame's maximum local gain factor is imposed directly by the target peak
2790 magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
2791 It is not recommended to go above this value.
2794 Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
2795 The Dynamic Audio Normalizer determines the maximum possible (local) gain
2796 factor for each input frame, i.e. the maximum gain factor that does not
2797 result in clipping or distortion. The maximum gain factor is determined by
2798 the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
2799 additionally bounds the frame's maximum gain factor by a predetermined
2800 (global) maximum gain factor. This is done in order to avoid excessive gain
2801 factors in "silent" or almost silent frames. By default, the maximum gain
2802 factor is 10.0, For most inputs the default value should be sufficient and
2803 it usually is not recommended to increase this value. Though, for input
2804 with an extremely low overall volume level, it may be necessary to allow even
2805 higher gain factors. Note, however, that the Dynamic Audio Normalizer does
2806 not simply apply a "hard" threshold (i.e. cut off values above the threshold).
2807 Instead, a "sigmoid" threshold function will be applied. This way, the
2808 gain factors will smoothly approach the threshold value, but never exceed that
2812 Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
2813 By default, the Dynamic Audio Normalizer performs "peak" normalization.
2814 This means that the maximum local gain factor for each frame is defined
2815 (only) by the frame's highest magnitude sample. This way, the samples can
2816 be amplified as much as possible without exceeding the maximum signal
2817 level, i.e. without clipping. Optionally, however, the Dynamic Audio
2818 Normalizer can also take into account the frame's root mean square,
2819 abbreviated RMS. In electrical engineering, the RMS is commonly used to
2820 determine the power of a time-varying signal. It is therefore considered
2821 that the RMS is a better approximation of the "perceived loudness" than
2822 just looking at the signal's peak magnitude. Consequently, by adjusting all
2823 frames to a constant RMS value, a uniform "perceived loudness" can be
2824 established. If a target RMS value has been specified, a frame's local gain
2825 factor is defined as the factor that would result in exactly that RMS value.
2826 Note, however, that the maximum local gain factor is still restricted by the
2827 frame's highest magnitude sample, in order to prevent clipping.
2830 Enable channels coupling. By default is enabled.
2831 By default, the Dynamic Audio Normalizer will amplify all channels by the same
2832 amount. This means the same gain factor will be applied to all channels, i.e.
2833 the maximum possible gain factor is determined by the "loudest" channel.
2834 However, in some recordings, it may happen that the volume of the different
2835 channels is uneven, e.g. one channel may be "quieter" than the other one(s).
2836 In this case, this option can be used to disable the channel coupling. This way,
2837 the gain factor will be determined independently for each channel, depending
2838 only on the individual channel's highest magnitude sample. This allows for
2839 harmonizing the volume of the different channels.
2842 Enable DC bias correction. By default is disabled.
2843 An audio signal (in the time domain) is a sequence of sample values.
2844 In the Dynamic Audio Normalizer these sample values are represented in the
2845 -1.0 to 1.0 range, regardless of the original input format. Normally, the
2846 audio signal, or "waveform", should be centered around the zero point.
2847 That means if we calculate the mean value of all samples in a file, or in a
2848 single frame, then the result should be 0.0 or at least very close to that
2849 value. If, however, there is a significant deviation of the mean value from
2850 0.0, in either positive or negative direction, this is referred to as a
2851 DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
2852 Audio Normalizer provides optional DC bias correction.
2853 With DC bias correction enabled, the Dynamic Audio Normalizer will determine
2854 the mean value, or "DC correction" offset, of each input frame and subtract
2855 that value from all of the frame's sample values which ensures those samples
2856 are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
2857 boundaries, the DC correction offset values will be interpolated smoothly
2858 between neighbouring frames.
2861 Enable alternative boundary mode. By default is disabled.
2862 The Dynamic Audio Normalizer takes into account a certain neighbourhood
2863 around each frame. This includes the preceding frames as well as the
2864 subsequent frames. However, for the "boundary" frames, located at the very
2865 beginning and at the very end of the audio file, not all neighbouring
2866 frames are available. In particular, for the first few frames in the audio
2867 file, the preceding frames are not known. And, similarly, for the last few
2868 frames in the audio file, the subsequent frames are not known. Thus, the
2869 question arises which gain factors should be assumed for the missing frames
2870 in the "boundary" region. The Dynamic Audio Normalizer implements two modes
2871 to deal with this situation. The default boundary mode assumes a gain factor
2872 of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
2873 "fade out" at the beginning and at the end of the input, respectively.
2876 Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
2877 By default, the Dynamic Audio Normalizer does not apply "traditional"
2878 compression. This means that signal peaks will not be pruned and thus the
2879 full dynamic range will be retained within each local neighbourhood. However,
2880 in some cases it may be desirable to combine the Dynamic Audio Normalizer's
2881 normalization algorithm with a more "traditional" compression.
2882 For this purpose, the Dynamic Audio Normalizer provides an optional compression
2883 (thresholding) function. If (and only if) the compression feature is enabled,
2884 all input frames will be processed by a soft knee thresholding function prior
2885 to the actual normalization process. Put simply, the thresholding function is
2886 going to prune all samples whose magnitude exceeds a certain threshold value.
2887 However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
2888 value. Instead, the threshold value will be adjusted for each individual
2890 In general, smaller parameters result in stronger compression, and vice versa.
2891 Values below 3.0 are not recommended, because audible distortion may appear.
2896 Make audio easier to listen to on headphones.
2898 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
2899 so that when listened to on headphones the stereo image is moved from
2900 inside your head (standard for headphones) to outside and in front of
2901 the listener (standard for speakers).
2907 Apply a two-pole peaking equalisation (EQ) filter. With this
2908 filter, the signal-level at and around a selected frequency can
2909 be increased or decreased, whilst (unlike bandpass and bandreject
2910 filters) that at all other frequencies is unchanged.
2912 In order to produce complex equalisation curves, this filter can
2913 be given several times, each with a different central frequency.
2915 The filter accepts the following options:
2919 Set the filter's central frequency in Hz.
2922 Set method to specify band-width of filter.
2937 Specify the band-width of a filter in width_type units.
2940 Set the required gain or attenuation in dB.
2941 Beware of clipping when using a positive gain.
2944 Specify which channels to filter, by default all available are filtered.
2947 @subsection Examples
2950 Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
2952 equalizer=f=1000:t=h:width=200:g=-10
2956 Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
2958 equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
2962 @subsection Commands
2964 This filter supports the following commands:
2967 Change equalizer frequency.
2968 Syntax for the command is : "@var{frequency}"
2971 Change equalizer width_type.
2972 Syntax for the command is : "@var{width_type}"
2975 Change equalizer width.
2976 Syntax for the command is : "@var{width}"
2979 Change equalizer gain.
2980 Syntax for the command is : "@var{gain}"
2983 @section extrastereo
2985 Linearly increases the difference between left and right channels which
2986 adds some sort of "live" effect to playback.
2988 The filter accepts the following options:
2992 Sets the difference coefficient (default: 2.5). 0.0 means mono sound
2993 (average of both channels), with 1.0 sound will be unchanged, with
2994 -1.0 left and right channels will be swapped.
2997 Enable clipping. By default is enabled.
3000 @section firequalizer
3001 Apply FIR Equalization using arbitrary frequency response.
3003 The filter accepts the following option:
3007 Set gain curve equation (in dB). The expression can contain variables:
3010 the evaluated frequency
3014 channel number, set to 0 when multichannels evaluation is disabled
3016 channel id, see libavutil/channel_layout.h, set to the first channel id when
3017 multichannels evaluation is disabled
3021 channel_layout, see libavutil/channel_layout.h
3026 @item gain_interpolate(f)
3027 interpolate gain on frequency f based on gain_entry
3028 @item cubic_interpolate(f)
3029 same as gain_interpolate, but smoother
3031 This option is also available as command. Default is @code{gain_interpolate(f)}.
3034 Set gain entry for gain_interpolate function. The expression can
3038 store gain entry at frequency f with value g
3040 This option is also available as command.
3043 Set filter delay in seconds. Higher value means more accurate.
3044 Default is @code{0.01}.
3047 Set filter accuracy in Hz. Lower value means more accurate.
3048 Default is @code{5}.
3051 Set window function. Acceptable values are:
3054 rectangular window, useful when gain curve is already smooth
3056 hann window (default)
3062 3-terms continuous 1st derivative nuttall window
3064 minimum 3-terms discontinuous nuttall window
3066 4-terms continuous 1st derivative nuttall window
3068 minimum 4-terms discontinuous nuttall (blackman-nuttall) window
3070 blackman-harris window
3076 If enabled, use fixed number of audio samples. This improves speed when
3077 filtering with large delay. Default is disabled.
3080 Enable multichannels evaluation on gain. Default is disabled.
3083 Enable zero phase mode by subtracting timestamp to compensate delay.
3084 Default is disabled.
3087 Set scale used by gain. Acceptable values are:
3090 linear frequency, linear gain
3092 linear frequency, logarithmic (in dB) gain (default)
3094 logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain
3096 logarithmic frequency, logarithmic gain
3100 Set file for dumping, suitable for gnuplot.
3103 Set scale for dumpfile. Acceptable values are same with scale option.
3107 Enable 2-channel convolution using complex FFT. This improves speed significantly.
3108 Default is disabled.
3111 Enable minimum phase impulse response. Default is disabled.
3114 @subsection Examples
3119 firequalizer=gain='if(lt(f,1000), 0, -INF)'
3122 lowpass at 1000 Hz with gain_entry:
3124 firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
3127 custom equalization:
3129 firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
3132 higher delay with zero phase to compensate delay:
3134 firequalizer=delay=0.1:fixed=on:zero_phase=on
3137 lowpass on left channel, highpass on right channel:
3139 firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
3140 :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
3145 Apply a flanging effect to the audio.
3147 The filter accepts the following options:
3151 Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
3154 Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2.
3157 Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
3161 Set percentage of delayed signal mixed with original. Range from 0 to 100.
3162 Default value is 71.
3165 Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
3168 Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
3169 Default value is @var{sinusoidal}.
3172 Set swept wave percentage-shift for multi channel. Range from 0 to 100.
3173 Default value is 25.
3176 Set delay-line interpolation, @var{linear} or @var{quadratic}.
3177 Default is @var{linear}.
3181 Apply Haas effect to audio.
3183 Note that this makes most sense to apply on mono signals.
3184 With this filter applied to mono signals it give some directionality and
3185 stretches its stereo image.
3187 The filter accepts the following options:
3191 Set input level. By default is @var{1}, or 0dB
3194 Set output level. By default is @var{1}, or 0dB.
3197 Set gain applied to side part of signal. By default is @var{1}.
3200 Set kind of middle source. Can be one of the following:
3210 Pick middle part signal of stereo image.
3213 Pick side part signal of stereo image.
3217 Change middle phase. By default is disabled.
3220 Set left channel delay. By default is @var{2.05} milliseconds.
3223 Set left channel balance. By default is @var{-1}.
3226 Set left channel gain. By default is @var{1}.
3229 Change left phase. By default is disabled.
3232 Set right channel delay. By defaults is @var{2.12} milliseconds.
3235 Set right channel balance. By default is @var{1}.
3238 Set right channel gain. By default is @var{1}.
3241 Change right phase. By default is enabled.
3246 Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
3247 embedded HDCD codes is expanded into a 20-bit PCM stream.
3249 The filter supports the Peak Extend and Low-level Gain Adjustment features
3250 of HDCD, and detects the Transient Filter flag.
3253 ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
3256 When using the filter with wav, note the default encoding for wav is 16-bit,
3257 so the resulting 20-bit stream will be truncated back to 16-bit. Use something
3258 like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
3260 ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
3261 ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
3264 The filter accepts the following options:
3267 @item disable_autoconvert
3268 Disable any automatic format conversion or resampling in the filter graph.
3270 @item process_stereo
3271 Process the stereo channels together. If target_gain does not match between
3272 channels, consider it invalid and use the last valid target_gain.
3275 Set the code detect timer period in ms.
3278 Always extend peaks above -3dBFS even if PE isn't signaled.
3281 Replace audio with a solid tone and adjust the amplitude to signal some
3282 specific aspect of the decoding process. The output file can be loaded in
3283 an audio editor alongside the original to aid analysis.
3285 @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
3292 Gain adjustment level at each sample
3294 Samples where peak extend occurs
3296 Samples where the code detect timer is active
3298 Samples where the target gain does not match between channels
3304 Apply head-related transfer functions (HRTFs) to create virtual
3305 loudspeakers around the user for binaural listening via headphones.
3306 The HRIRs are provided via additional streams, for each channel
3307 one stereo input stream is needed.
3309 The filter accepts the following options:
3313 Set mapping of input streams for convolution.
3314 The argument is a '|'-separated list of channel names in order as they
3315 are given as additional stream inputs for filter.
3316 This also specify number of input streams. Number of input streams
3317 must be not less than number of channels in first stream plus one.
3320 Set gain applied to audio. Value is in dB. Default is 0.
3323 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
3324 processing audio in time domain which is slow.
3325 @var{freq} is processing audio in frequency domain which is fast.
3326 Default is @var{freq}.
3329 Set custom gain for LFE channels. Value is in dB. Default is 0.
3332 Set size of frame in number of samples which will be processed at once.
3333 Default value is @var{1024}. Allowed range is from 1024 to 96000.
3336 Set format of hrir stream.
3337 Default value is @var{stereo}. Alternative value is @var{multich}.
3338 If value is set to @var{stereo}, number of additional streams should
3339 be greater or equal to number of input channels in first input stream.
3340 Also each additional stream should have stereo number of channels.
3341 If value is set to @var{multich}, number of additional streams should
3342 be exactly one. Also number of input channels of additional stream
3343 should be equal or greater than twice number of channels of first input
3347 @subsection Examples
3351 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
3352 each amovie filter use stereo file with IR coefficients as input.
3353 The files give coefficients for each position of virtual loudspeaker:
3355 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"
3360 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
3361 but now in @var{multich} @var{hrir} format.
3363 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"
3370 Apply a high-pass filter with 3dB point frequency.
3371 The filter can be either single-pole, or double-pole (the default).
3372 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
3374 The filter accepts the following options:
3378 Set frequency in Hz. Default is 3000.
3381 Set number of poles. Default is 2.
3384 Set method to specify band-width of filter.
3399 Specify the band-width of a filter in width_type units.
3400 Applies only to double-pole filter.
3401 The default is 0.707q and gives a Butterworth response.
3404 Specify which channels to filter, by default all available are filtered.
3407 @subsection Commands
3409 This filter supports the following commands:
3412 Change highpass frequency.
3413 Syntax for the command is : "@var{frequency}"
3416 Change highpass width_type.
3417 Syntax for the command is : "@var{width_type}"
3420 Change highpass width.
3421 Syntax for the command is : "@var{width}"
3426 Join multiple input streams into one multi-channel stream.
3428 It accepts the following parameters:
3432 The number of input streams. It defaults to 2.
3434 @item channel_layout
3435 The desired output channel layout. It defaults to stereo.
3438 Map channels from inputs to output. The argument is a '|'-separated list of
3439 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
3440 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
3441 can be either the name of the input channel (e.g. FL for front left) or its
3442 index in the specified input stream. @var{out_channel} is the name of the output
3446 The filter will attempt to guess the mappings when they are not specified
3447 explicitly. It does so by first trying to find an unused matching input channel
3448 and if that fails it picks the first unused input channel.
3450 Join 3 inputs (with properly set channel layouts):
3452 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
3455 Build a 5.1 output from 6 single-channel streams:
3457 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
3458 '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'
3464 Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
3466 To enable compilation of this filter you need to configure FFmpeg with
3467 @code{--enable-ladspa}.
3471 Specifies the name of LADSPA plugin library to load. If the environment
3472 variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
3473 each one of the directories specified by the colon separated list in
3474 @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
3475 this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
3476 @file{/usr/lib/ladspa/}.
3479 Specifies the plugin within the library. Some libraries contain only
3480 one plugin, but others contain many of them. If this is not set filter
3481 will list all available plugins within the specified library.
3484 Set the '|' separated list of controls which are zero or more floating point
3485 values that determine the behavior of the loaded plugin (for example delay,
3487 Controls need to be defined using the following syntax:
3488 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
3489 @var{valuei} is the value set on the @var{i}-th control.
3490 Alternatively they can be also defined using the following syntax:
3491 @var{value0}|@var{value1}|@var{value2}|..., where
3492 @var{valuei} is the value set on the @var{i}-th control.
3493 If @option{controls} is set to @code{help}, all available controls and
3494 their valid ranges are printed.
3496 @item sample_rate, s
3497 Specify the sample rate, default to 44100. Only used if plugin have
3501 Set the number of samples per channel per each output frame, default
3502 is 1024. Only used if plugin have zero inputs.
3505 Set the minimum duration of the sourced audio. See
3506 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
3507 for the accepted syntax.
3508 Note that the resulting duration may be greater than the specified duration,
3509 as the generated audio is always cut at the end of a complete frame.
3510 If not specified, or the expressed duration is negative, the audio is
3511 supposed to be generated forever.
3512 Only used if plugin have zero inputs.
3516 @subsection Examples
3520 List all available plugins within amp (LADSPA example plugin) library:
3526 List all available controls and their valid ranges for @code{vcf_notch}
3527 plugin from @code{VCF} library:
3529 ladspa=f=vcf:p=vcf_notch:c=help
3533 Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
3536 ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
3540 Add reverberation to the audio using TAP-plugins
3541 (Tom's Audio Processing plugins):
3543 ladspa=file=tap_reverb:tap_reverb
3547 Generate white noise, with 0.2 amplitude:
3549 ladspa=file=cmt:noise_source_white:c=c0=.2
3553 Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
3554 @code{C* Audio Plugin Suite} (CAPS) library:
3556 ladspa=file=caps:Click:c=c1=20'
3560 Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
3562 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
3566 Increase volume by 20dB using fast lookahead limiter from Steve Harris
3567 @code{SWH Plugins} collection:
3569 ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
3573 Attenuate low frequencies using Multiband EQ from Steve Harris
3574 @code{SWH Plugins} collection:
3576 ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
3580 Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite}
3583 ladspa=caps:Narrower
3587 Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library:
3589 ladspa=caps:White:.2
3593 Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library:
3595 ladspa=caps:Fractal:c=c1=1
3599 Dynamic volume normalization using @code{VLevel} plugin:
3601 ladspa=vlevel-ladspa:vlevel_mono
3605 @subsection Commands
3607 This filter supports the following commands:
3610 Modify the @var{N}-th control value.
3612 If the specified value is not valid, it is ignored and prior one is kept.
3617 EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
3618 Support for both single pass (livestreams, files) and double pass (files) modes.
3619 This algorithm can target IL, LRA, and maximum true peak. To accurately detect true peaks,
3620 the audio stream will be upsampled to 192 kHz unless the normalization mode is linear.
3621 Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate.
3623 The filter accepts the following options:
3627 Set integrated loudness target.
3628 Range is -70.0 - -5.0. Default value is -24.0.
3631 Set loudness range target.
3632 Range is 1.0 - 20.0. Default value is 7.0.
3635 Set maximum true peak.
3636 Range is -9.0 - +0.0. Default value is -2.0.
3638 @item measured_I, measured_i
3639 Measured IL of input file.
3640 Range is -99.0 - +0.0.
3642 @item measured_LRA, measured_lra
3643 Measured LRA of input file.
3644 Range is 0.0 - 99.0.
3646 @item measured_TP, measured_tp
3647 Measured true peak of input file.
3648 Range is -99.0 - +99.0.
3650 @item measured_thresh
3651 Measured threshold of input file.
3652 Range is -99.0 - +0.0.
3655 Set offset gain. Gain is applied before the true-peak limiter.
3656 Range is -99.0 - +99.0. Default is +0.0.
3659 Normalize linearly if possible.
3660 measured_I, measured_LRA, measured_TP, and measured_thresh must also
3661 to be specified in order to use this mode.
3662 Options are true or false. Default is true.
3665 Treat mono input files as "dual-mono". If a mono file is intended for playback
3666 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
3667 If set to @code{true}, this option will compensate for this effect.
3668 Multi-channel input files are not affected by this option.
3669 Options are true or false. Default is false.
3672 Set print format for stats. Options are summary, json, or none.
3673 Default value is none.
3678 Apply a low-pass filter with 3dB point frequency.
3679 The filter can be either single-pole or double-pole (the default).
3680 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
3682 The filter accepts the following options:
3686 Set frequency in Hz. Default is 500.
3689 Set number of poles. Default is 2.
3692 Set method to specify band-width of filter.
3707 Specify the band-width of a filter in width_type units.
3708 Applies only to double-pole filter.
3709 The default is 0.707q and gives a Butterworth response.
3712 Specify which channels to filter, by default all available are filtered.
3715 @subsection Examples
3718 Lowpass only LFE channel, it LFE is not present it does nothing:
3724 @subsection Commands
3726 This filter supports the following commands:
3729 Change lowpass frequency.
3730 Syntax for the command is : "@var{frequency}"
3733 Change lowpass width_type.
3734 Syntax for the command is : "@var{width_type}"
3737 Change lowpass width.
3738 Syntax for the command is : "@var{width}"
3743 Load a LV2 (LADSPA Version 2) plugin.
3745 To enable compilation of this filter you need to configure FFmpeg with
3746 @code{--enable-lv2}.
3750 Specifies the plugin URI. You may need to escape ':'.
3753 Set the '|' separated list of controls which are zero or more floating point
3754 values that determine the behavior of the loaded plugin (for example delay,
3756 If @option{controls} is set to @code{help}, all available controls and
3757 their valid ranges are printed.
3759 @item sample_rate, s
3760 Specify the sample rate, default to 44100. Only used if plugin have
3764 Set the number of samples per channel per each output frame, default
3765 is 1024. Only used if plugin have zero inputs.
3768 Set the minimum duration of the sourced audio. See
3769 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
3770 for the accepted syntax.
3771 Note that the resulting duration may be greater than the specified duration,
3772 as the generated audio is always cut at the end of a complete frame.
3773 If not specified, or the expressed duration is negative, the audio is
3774 supposed to be generated forever.
3775 Only used if plugin have zero inputs.
3778 @subsection Examples
3782 Apply bass enhancer plugin from Calf:
3784 lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
3788 Apply vinyl plugin from Calf:
3790 lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
3794 Apply bit crusher plugin from ArtyFX:
3796 lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
3801 Multiband Compress or expand the audio's dynamic range.
3803 The input audio is divided into bands using 4th order Linkwitz-Riley IIRs.
3804 This is akin to the crossover of a loudspeaker, and results in flat frequency
3805 response when absent compander action.
3807 It accepts the following parameters:
3811 This option syntax is:
3812 attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ...
3813 For explanation of each item refer to compand filter documentation.
3819 Mix channels with specific gain levels. The filter accepts the output
3820 channel layout followed by a set of channels definitions.
3822 This filter is also designed to efficiently remap the channels of an audio
3825 The filter accepts parameters of the form:
3826 "@var{l}|@var{outdef}|@var{outdef}|..."
3830 output channel layout or number of channels
3833 output channel specification, of the form:
3834 "@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]"
3837 output channel to define, either a channel name (FL, FR, etc.) or a channel
3838 number (c0, c1, etc.)
3841 multiplicative coefficient for the channel, 1 leaving the volume unchanged
3844 input channel to use, see out_name for details; it is not possible to mix
3845 named and numbered input channels
3848 If the `=' in a channel specification is replaced by `<', then the gains for
3849 that specification will be renormalized so that the total is 1, thus
3850 avoiding clipping noise.
3852 @subsection Mixing examples
3854 For example, if you want to down-mix from stereo to mono, but with a bigger
3855 factor for the left channel:
3857 pan=1c|c0=0.9*c0+0.1*c1
3860 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
3861 7-channels surround:
3863 pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
3866 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
3867 that should be preferred (see "-ac" option) unless you have very specific
3870 @subsection Remapping examples
3872 The channel remapping will be effective if, and only if:
3875 @item gain coefficients are zeroes or ones,
3876 @item only one input per channel output,
3879 If all these conditions are satisfied, the filter will notify the user ("Pure
3880 channel mapping detected"), and use an optimized and lossless method to do the
3883 For example, if you have a 5.1 source and want a stereo audio stream by
3884 dropping the extra channels:
3886 pan="stereo| c0=FL | c1=FR"
3889 Given the same source, you can also switch front left and front right channels
3890 and keep the input channel layout:
3892 pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
3895 If the input is a stereo audio stream, you can mute the front left channel (and
3896 still keep the stereo channel layout) with:
3901 Still with a stereo audio stream input, you can copy the right channel in both
3902 front left and right:
3904 pan="stereo| c0=FR | c1=FR"
3909 ReplayGain scanner filter. This filter takes an audio stream as an input and
3910 outputs it unchanged.
3911 At end of filtering it displays @code{track_gain} and @code{track_peak}.
3915 Convert the audio sample format, sample rate and channel layout. It is
3916 not meant to be used directly.
3919 Apply time-stretching and pitch-shifting with librubberband.
3921 To enable compilation of this filter, you need to configure FFmpeg with
3922 @code{--enable-librubberband}.
3924 The filter accepts the following options:
3928 Set tempo scale factor.
3931 Set pitch scale factor.
3934 Set transients detector.
3935 Possible values are:
3944 Possible values are:
3953 Possible values are:
3960 Set processing window size.
3961 Possible values are:
3970 Possible values are:
3977 Enable formant preservation when shift pitching.
3978 Possible values are:
3986 Possible values are:
3995 Possible values are:
4002 @section sidechaincompress
4004 This filter acts like normal compressor but has the ability to compress
4005 detected signal using second input signal.
4006 It needs two input streams and returns one output stream.
4007 First input stream will be processed depending on second stream signal.
4008 The filtered signal then can be filtered with other filters in later stages of
4009 processing. See @ref{pan} and @ref{amerge} filter.
4011 The filter accepts the following options:
4015 Set input gain. Default is 1. Range is between 0.015625 and 64.
4018 If a signal of second stream raises above this level it will affect the gain
4019 reduction of first stream.
4020 By default is 0.125. Range is between 0.00097563 and 1.
4023 Set a ratio about which the signal is reduced. 1:2 means that if the level
4024 raised 4dB above the threshold, it will be only 2dB above after the reduction.
4025 Default is 2. Range is between 1 and 20.
4028 Amount of milliseconds the signal has to rise above the threshold before gain
4029 reduction starts. Default is 20. Range is between 0.01 and 2000.
4032 Amount of milliseconds the signal has to fall below the threshold before
4033 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
4036 Set the amount by how much signal will be amplified after processing.
4037 Default is 1. Range is from 1 to 64.
4040 Curve the sharp knee around the threshold to enter gain reduction more softly.
4041 Default is 2.82843. Range is between 1 and 8.
4044 Choose if the @code{average} level between all channels of side-chain stream
4045 or the louder(@code{maximum}) channel of side-chain stream affects the
4046 reduction. Default is @code{average}.
4049 Should the exact signal be taken in case of @code{peak} or an RMS one in case
4050 of @code{rms}. Default is @code{rms} which is mainly smoother.
4053 Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
4056 How much to use compressed signal in output. Default is 1.
4057 Range is between 0 and 1.
4060 @subsection Examples
4064 Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
4065 depending on the signal of 2nd input and later compressed signal to be
4066 merged with 2nd input:
4068 ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
4072 @section sidechaingate
4074 A sidechain gate acts like a normal (wideband) gate but has the ability to
4075 filter the detected signal before sending it to the gain reduction stage.
4076 Normally a gate uses the full range signal to detect a level above the
4078 For example: If you cut all lower frequencies from your sidechain signal
4079 the gate will decrease the volume of your track only if not enough highs
4080 appear. With this technique you are able to reduce the resonation of a
4081 natural drum or remove "rumbling" of muted strokes from a heavily distorted
4083 It needs two input streams and returns one output stream.
4084 First input stream will be processed depending on second stream signal.
4086 The filter accepts the following options:
4090 Set input level before filtering.
4091 Default is 1. Allowed range is from 0.015625 to 64.
4094 Set the level of gain reduction when the signal is below the threshold.
4095 Default is 0.06125. Allowed range is from 0 to 1.
4098 If a signal rises above this level the gain reduction is released.
4099 Default is 0.125. Allowed range is from 0 to 1.
4102 Set a ratio about which the signal is reduced.
4103 Default is 2. Allowed range is from 1 to 9000.
4106 Amount of milliseconds the signal has to rise above the threshold before gain
4108 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
4111 Amount of milliseconds the signal has to fall below the threshold before the
4112 reduction is increased again. Default is 250 milliseconds.
4113 Allowed range is from 0.01 to 9000.
4116 Set amount of amplification of signal after processing.
4117 Default is 1. Allowed range is from 1 to 64.
4120 Curve the sharp knee around the threshold to enter gain reduction more softly.
4121 Default is 2.828427125. Allowed range is from 1 to 8.
4124 Choose if exact signal should be taken for detection or an RMS like one.
4125 Default is rms. Can be peak or rms.
4128 Choose if the average level between all channels or the louder channel affects
4130 Default is average. Can be average or maximum.
4133 Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
4136 @section silencedetect
4138 Detect silence in an audio stream.
4140 This filter logs a message when it detects that the input audio volume is less
4141 or equal to a noise tolerance value for a duration greater or equal to the
4142 minimum detected noise duration.
4144 The printed times and duration are expressed in seconds.
4146 The filter accepts the following options:
4150 Set silence duration until notification (default is 2 seconds).
4153 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
4154 specified value) or amplitude ratio. Default is -60dB, or 0.001.
4157 @subsection Examples
4161 Detect 5 seconds of silence with -50dB noise tolerance:
4163 silencedetect=n=-50dB:d=5
4167 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
4168 tolerance in @file{silence.mp3}:
4170 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
4174 @section silenceremove
4176 Remove silence from the beginning, middle or end of the audio.
4178 The filter accepts the following options:
4182 This value is used to indicate if audio should be trimmed at beginning of
4183 the audio. A value of zero indicates no silence should be trimmed from the
4184 beginning. When specifying a non-zero value, it trims audio up until it
4185 finds non-silence. Normally, when trimming silence from beginning of audio
4186 the @var{start_periods} will be @code{1} but it can be increased to higher
4187 values to trim all audio up to specific count of non-silence periods.
4188 Default value is @code{0}.
4190 @item start_duration
4191 Specify the amount of time that non-silence must be detected before it stops
4192 trimming audio. By increasing the duration, bursts of noises can be treated
4193 as silence and trimmed off. Default value is @code{0}.
4195 @item start_threshold
4196 This indicates what sample value should be treated as silence. For digital
4197 audio, a value of @code{0} may be fine but for audio recorded from analog,
4198 you may wish to increase the value to account for background noise.
4199 Can be specified in dB (in case "dB" is appended to the specified value)
4200 or amplitude ratio. Default value is @code{0}.
4203 Set the count for trimming silence from the end of audio.
4204 To remove silence from the middle of a file, specify a @var{stop_periods}
4205 that is negative. This value is then treated as a positive value and is
4206 used to indicate the effect should restart processing as specified by
4207 @var{start_periods}, making it suitable for removing periods of silence
4208 in the middle of the audio.
4209 Default value is @code{0}.
4212 Specify a duration of silence that must exist before audio is not copied any
4213 more. By specifying a higher duration, silence that is wanted can be left in
4215 Default value is @code{0}.
4217 @item stop_threshold
4218 This is the same as @option{start_threshold} but for trimming silence from
4220 Can be specified in dB (in case "dB" is appended to the specified value)
4221 or amplitude ratio. Default value is @code{0}.
4224 This indicates that @var{stop_duration} length of audio should be left intact
4225 at the beginning of each period of silence.
4226 For example, if you want to remove long pauses between words but do not want
4227 to remove the pauses completely. Default value is @code{0}.
4230 Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
4231 and works better with digital silence which is exactly 0.
4232 Default value is @code{rms}.
4235 Set ratio used to calculate size of window for detecting silence.
4236 Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
4239 @subsection Examples
4243 The following example shows how this filter can be used to start a recording
4244 that does not contain the delay at the start which usually occurs between
4245 pressing the record button and the start of the performance:
4247 silenceremove=1:5:0.02
4251 Trim all silence encountered from beginning to end where there is more than 1
4252 second of silence in audio:
4254 silenceremove=0:0:0:-1:1:-90dB
4260 SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
4261 loudspeakers around the user for binaural listening via headphones (audio
4262 formats up to 9 channels supported).
4263 The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
4264 SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
4265 Austrian Academy of Sciences.
4267 To enable compilation of this filter you need to configure FFmpeg with
4268 @code{--enable-libmysofa}.
4270 The filter accepts the following options:
4274 Set the SOFA file used for rendering.
4277 Set gain applied to audio. Value is in dB. Default is 0.
4280 Set rotation of virtual loudspeakers in deg. Default is 0.
4283 Set elevation of virtual speakers in deg. Default is 0.
4286 Set distance in meters between loudspeakers and the listener with near-field
4287 HRTFs. Default is 1.
4290 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
4291 processing audio in time domain which is slow.
4292 @var{freq} is processing audio in frequency domain which is fast.
4293 Default is @var{freq}.
4296 Set custom positions of virtual loudspeakers. Syntax for this option is:
4297 <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
4298 Each virtual loudspeaker is described with short channel name following with
4299 azimuth and elevation in degrees.
4300 Each virtual loudspeaker description is separated by '|'.
4301 For example to override front left and front right channel positions use:
4302 'speakers=FL 45 15|FR 345 15'.
4303 Descriptions with unrecognised channel names are ignored.
4306 Set custom gain for LFE channels. Value is in dB. Default is 0.
4309 @subsection Examples
4313 Using ClubFritz6 sofa file:
4315 sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
4319 Using ClubFritz12 sofa file and bigger radius with small rotation:
4321 sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
4325 Similar as above but with custom speaker positions for front left, front right, back left and back right
4326 and also with custom gain:
4328 "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
4332 @section stereotools
4334 This filter has some handy utilities to manage stereo signals, for converting
4335 M/S stereo recordings to L/R signal while having control over the parameters
4336 or spreading the stereo image of master track.
4338 The filter accepts the following options:
4342 Set input level before filtering for both channels. Defaults is 1.
4343 Allowed range is from 0.015625 to 64.
4346 Set output level after filtering for both channels. Defaults is 1.
4347 Allowed range is from 0.015625 to 64.
4350 Set input balance between both channels. Default is 0.
4351 Allowed range is from -1 to 1.
4354 Set output balance between both channels. Default is 0.
4355 Allowed range is from -1 to 1.
4358 Enable softclipping. Results in analog distortion instead of harsh digital 0dB
4359 clipping. Disabled by default.
4362 Mute the left channel. Disabled by default.
4365 Mute the right channel. Disabled by default.
4368 Change the phase of the left channel. Disabled by default.
4371 Change the phase of the right channel. Disabled by default.
4374 Set stereo mode. Available values are:
4378 Left/Right to Left/Right, this is default.
4381 Left/Right to Mid/Side.
4384 Mid/Side to Left/Right.
4387 Left/Right to Left/Left.
4390 Left/Right to Right/Right.
4393 Left/Right to Left + Right.
4396 Left/Right to Right/Left.
4399 Mid/Side to Left/Left.
4402 Mid/Side to Right/Right.
4406 Set level of side signal. Default is 1.
4407 Allowed range is from 0.015625 to 64.
4410 Set balance of side signal. Default is 0.
4411 Allowed range is from -1 to 1.
4414 Set level of the middle signal. Default is 1.
4415 Allowed range is from 0.015625 to 64.
4418 Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
4421 Set stereo base between mono and inversed channels. Default is 0.
4422 Allowed range is from -1 to 1.
4425 Set delay in milliseconds how much to delay left from right channel and
4426 vice versa. Default is 0. Allowed range is from -20 to 20.
4429 Set S/C level. Default is 1. Allowed range is from 1 to 100.
4432 Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
4434 @item bmode_in, bmode_out
4435 Set balance mode for balance_in/balance_out option.
4437 Can be one of the following:
4441 Classic balance mode. Attenuate one channel at time.
4442 Gain is raised up to 1.
4445 Similar as classic mode above but gain is raised up to 2.
4448 Equal power distribution, from -6dB to +6dB range.
4452 @subsection Examples
4456 Apply karaoke like effect:
4458 stereotools=mlev=0.015625
4462 Convert M/S signal to L/R:
4464 "stereotools=mode=ms>lr"
4468 @section stereowiden
4470 This filter enhance the stereo effect by suppressing signal common to both
4471 channels and by delaying the signal of left into right and vice versa,
4472 thereby widening the stereo effect.
4474 The filter accepts the following options:
4478 Time in milliseconds of the delay of left signal into right and vice versa.
4479 Default is 20 milliseconds.
4482 Amount of gain in delayed signal into right and vice versa. Gives a delay
4483 effect of left signal in right output and vice versa which gives widening
4484 effect. Default is 0.3.
4487 Cross feed of left into right with inverted phase. This helps in suppressing
4488 the mono. If the value is 1 it will cancel all the signal common to both
4489 channels. Default is 0.3.
4492 Set level of input signal of original channel. Default is 0.8.
4495 @section superequalizer
4496 Apply 18 band equalizer.
4498 The filter accepts the following options:
4505 Set 131Hz band gain.
4507 Set 185Hz band gain.
4509 Set 262Hz band gain.
4511 Set 370Hz band gain.
4513 Set 523Hz band gain.
4515 Set 740Hz band gain.
4517 Set 1047Hz band gain.
4519 Set 1480Hz band gain.
4521 Set 2093Hz band gain.
4523 Set 2960Hz band gain.
4525 Set 4186Hz band gain.
4527 Set 5920Hz band gain.
4529 Set 8372Hz band gain.
4531 Set 11840Hz band gain.
4533 Set 16744Hz band gain.
4535 Set 20000Hz band gain.
4539 Apply audio surround upmix filter.
4541 This filter allows to produce multichannel output from audio stream.
4543 The filter accepts the following options:
4547 Set output channel layout. By default, this is @var{5.1}.
4549 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4550 for the required syntax.
4553 Set input channel layout. By default, this is @var{stereo}.
4555 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4556 for the required syntax.
4559 Set input volume level. By default, this is @var{1}.
4562 Set output volume level. By default, this is @var{1}.
4565 Enable LFE channel output if output channel layout has it. By default, this is enabled.
4568 Set LFE low cut off frequency. By default, this is @var{128} Hz.
4571 Set LFE high cut off frequency. By default, this is @var{256} Hz.
4574 Set front center input volume. By default, this is @var{1}.
4577 Set front center output volume. By default, this is @var{1}.
4580 Set LFE input volume. By default, this is @var{1}.
4583 Set LFE output volume. By default, this is @var{1}.
4586 @section treble, highshelf
4588 Boost or cut treble (upper) frequencies of the audio using a two-pole
4589 shelving filter with a response similar to that of a standard
4590 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
4592 The filter accepts the following options:
4596 Give the gain at whichever is the lower of ~22 kHz and the
4597 Nyquist frequency. Its useful range is about -20 (for a large cut)
4598 to +20 (for a large boost). Beware of clipping when using a positive gain.
4601 Set the filter's central frequency and so can be used
4602 to extend or reduce the frequency range to be boosted or cut.
4603 The default value is @code{3000} Hz.
4606 Set method to specify band-width of filter.
4621 Determine how steep is the filter's shelf transition.
4624 Specify which channels to filter, by default all available are filtered.
4627 @subsection Commands
4629 This filter supports the following commands:
4632 Change treble frequency.
4633 Syntax for the command is : "@var{frequency}"
4636 Change treble width_type.
4637 Syntax for the command is : "@var{width_type}"
4640 Change treble width.
4641 Syntax for the command is : "@var{width}"
4645 Syntax for the command is : "@var{gain}"
4650 Sinusoidal amplitude modulation.
4652 The filter accepts the following options:
4656 Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
4657 (20 Hz or lower) will result in a tremolo effect.
4658 This filter may also be used as a ring modulator by specifying
4659 a modulation frequency higher than 20 Hz.
4660 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
4663 Depth of modulation as a percentage. Range is 0.0 - 1.0.
4664 Default value is 0.5.
4669 Sinusoidal phase modulation.
4671 The filter accepts the following options:
4675 Modulation frequency in Hertz.
4676 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
4679 Depth of modulation as a percentage. Range is 0.0 - 1.0.
4680 Default value is 0.5.
4685 Adjust the input audio volume.
4687 It accepts the following parameters:
4691 Set audio volume expression.
4693 Output values are clipped to the maximum value.
4695 The output audio volume is given by the relation:
4697 @var{output_volume} = @var{volume} * @var{input_volume}
4700 The default value for @var{volume} is "1.0".
4703 This parameter represents the mathematical precision.
4705 It determines which input sample formats will be allowed, which affects the
4706 precision of the volume scaling.
4710 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
4712 32-bit floating-point; this limits input sample format to FLT. (default)
4714 64-bit floating-point; this limits input sample format to DBL.
4718 Choose the behaviour on encountering ReplayGain side data in input frames.
4722 Remove ReplayGain side data, ignoring its contents (the default).
4725 Ignore ReplayGain side data, but leave it in the frame.
4728 Prefer the track gain, if present.
4731 Prefer the album gain, if present.
4734 @item replaygain_preamp
4735 Pre-amplification gain in dB to apply to the selected replaygain gain.
4737 Default value for @var{replaygain_preamp} is 0.0.
4740 Set when the volume expression is evaluated.
4742 It accepts the following values:
4745 only evaluate expression once during the filter initialization, or
4746 when the @samp{volume} command is sent
4749 evaluate expression for each incoming frame
4752 Default value is @samp{once}.
4755 The volume expression can contain the following parameters.
4759 frame number (starting at zero)
4762 @item nb_consumed_samples
4763 number of samples consumed by the filter
4765 number of samples in the current frame
4767 original frame position in the file
4773 PTS at start of stream
4775 time at start of stream
4781 last set volume value
4784 Note that when @option{eval} is set to @samp{once} only the
4785 @var{sample_rate} and @var{tb} variables are available, all other
4786 variables will evaluate to NAN.
4788 @subsection Commands
4790 This filter supports the following commands:
4793 Modify the volume expression.
4794 The command accepts the same syntax of the corresponding option.
4796 If the specified expression is not valid, it is kept at its current
4798 @item replaygain_noclip
4799 Prevent clipping by limiting the gain applied.
4801 Default value for @var{replaygain_noclip} is 1.
4805 @subsection Examples
4809 Halve the input audio volume:
4813 volume=volume=-6.0206dB
4816 In all the above example the named key for @option{volume} can be
4817 omitted, for example like in:
4823 Increase input audio power by 6 decibels using fixed-point precision:
4825 volume=volume=6dB:precision=fixed
4829 Fade volume after time 10 with an annihilation period of 5 seconds:
4831 volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
4835 @section volumedetect
4837 Detect the volume of the input video.
4839 The filter has no parameters. The input is not modified. Statistics about
4840 the volume will be printed in the log when the input stream end is reached.
4842 In particular it will show the mean volume (root mean square), maximum
4843 volume (on a per-sample basis), and the beginning of a histogram of the
4844 registered volume values (from the maximum value to a cumulated 1/1000 of
4847 All volumes are in decibels relative to the maximum PCM value.
4849 @subsection Examples
4851 Here is an excerpt of the output:
4853 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
4854 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
4855 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
4856 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
4857 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
4858 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
4859 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
4860 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
4861 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
4867 The mean square energy is approximately -27 dB, or 10^-2.7.
4869 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
4871 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
4874 In other words, raising the volume by +4 dB does not cause any clipping,
4875 raising it by +5 dB causes clipping for 6 samples, etc.
4877 @c man end AUDIO FILTERS
4879 @chapter Audio Sources
4880 @c man begin AUDIO SOURCES
4882 Below is a description of the currently available audio sources.
4886 Buffer audio frames, and make them available to the filter chain.
4888 This source is mainly intended for a programmatic use, in particular
4889 through the interface defined in @file{libavfilter/asrc_abuffer.h}.
4891 It accepts the following parameters:
4895 The timebase which will be used for timestamps of submitted frames. It must be
4896 either a floating-point number or in @var{numerator}/@var{denominator} form.
4899 The sample rate of the incoming audio buffers.
4902 The sample format of the incoming audio buffers.
4903 Either a sample format name or its corresponding integer representation from
4904 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
4906 @item channel_layout
4907 The channel layout of the incoming audio buffers.
4908 Either a channel layout name from channel_layout_map in
4909 @file{libavutil/channel_layout.c} or its corresponding integer representation
4910 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
4913 The number of channels of the incoming audio buffers.
4914 If both @var{channels} and @var{channel_layout} are specified, then they
4919 @subsection Examples
4922 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
4925 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
4926 Since the sample format with name "s16p" corresponds to the number
4927 6 and the "stereo" channel layout corresponds to the value 0x3, this is
4930 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
4935 Generate an audio signal specified by an expression.
4937 This source accepts in input one or more expressions (one for each
4938 channel), which are evaluated and used to generate a corresponding
4941 This source accepts the following options:
4945 Set the '|'-separated expressions list for each separate channel. In case the
4946 @option{channel_layout} option is not specified, the selected channel layout
4947 depends on the number of provided expressions. Otherwise the last
4948 specified expression is applied to the remaining output channels.
4950 @item channel_layout, c
4951 Set the channel layout. The number of channels in the specified layout
4952 must be equal to the number of specified expressions.
4955 Set the minimum duration of the sourced audio. See
4956 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4957 for the accepted syntax.
4958 Note that the resulting duration may be greater than the specified
4959 duration, as the generated audio is always cut at the end of a
4962 If not specified, or the expressed duration is negative, the audio is
4963 supposed to be generated forever.
4966 Set the number of samples per channel per each output frame,
4969 @item sample_rate, s
4970 Specify the sample rate, default to 44100.
4973 Each expression in @var{exprs} can contain the following constants:
4977 number of the evaluated sample, starting from 0
4980 time of the evaluated sample expressed in seconds, starting from 0
4987 @subsection Examples
4997 Generate a sin signal with frequency of 440 Hz, set sample rate to
5000 aevalsrc="sin(440*2*PI*t):s=8000"
5004 Generate a two channels signal, specify the channel layout (Front
5005 Center + Back Center) explicitly:
5007 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
5011 Generate white noise:
5013 aevalsrc="-2+random(0)"
5017 Generate an amplitude modulated signal:
5019 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
5023 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
5025 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
5032 The null audio source, return unprocessed audio frames. It is mainly useful
5033 as a template and to be employed in analysis / debugging tools, or as
5034 the source for filters which ignore the input data (for example the sox
5037 This source accepts the following options:
5041 @item channel_layout, cl
5043 Specifies the channel layout, and can be either an integer or a string
5044 representing a channel layout. The default value of @var{channel_layout}
5047 Check the channel_layout_map definition in
5048 @file{libavutil/channel_layout.c} for the mapping between strings and
5049 channel layout values.
5051 @item sample_rate, r
5052 Specifies the sample rate, and defaults to 44100.
5055 Set the number of samples per requested frames.
5059 @subsection Examples
5063 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
5065 anullsrc=r=48000:cl=4
5069 Do the same operation with a more obvious syntax:
5071 anullsrc=r=48000:cl=mono
5075 All the parameters need to be explicitly defined.
5079 Synthesize a voice utterance using the libflite library.
5081 To enable compilation of this filter you need to configure FFmpeg with
5082 @code{--enable-libflite}.
5084 Note that versions of the flite library prior to 2.0 are not thread-safe.
5086 The filter accepts the following options:
5091 If set to 1, list the names of the available voices and exit
5092 immediately. Default value is 0.
5095 Set the maximum number of samples per frame. Default value is 512.
5098 Set the filename containing the text to speak.
5101 Set the text to speak.
5104 Set the voice to use for the speech synthesis. Default value is
5105 @code{kal}. See also the @var{list_voices} option.
5108 @subsection Examples
5112 Read from file @file{speech.txt}, and synthesize the text using the
5113 standard flite voice:
5115 flite=textfile=speech.txt
5119 Read the specified text selecting the @code{slt} voice:
5121 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
5125 Input text to ffmpeg:
5127 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
5131 Make @file{ffplay} speak the specified text, using @code{flite} and
5132 the @code{lavfi} device:
5134 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
5138 For more information about libflite, check:
5139 @url{http://www.festvox.org/flite/}
5143 Generate a noise audio signal.
5145 The filter accepts the following options:
5148 @item sample_rate, r
5149 Specify the sample rate. Default value is 48000 Hz.
5152 Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value
5156 Specify the duration of the generated audio stream. Not specifying this option
5157 results in noise with an infinite length.
5159 @item color, colour, c
5160 Specify the color of noise. Available noise colors are white, pink, brown,
5161 blue and violet. Default color is white.
5164 Specify a value used to seed the PRNG.
5167 Set the number of samples per each output frame, default is 1024.
5170 @subsection Examples
5175 Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5:
5177 anoisesrc=d=60:c=pink:r=44100:a=0.5
5183 Generate odd-tap Hilbert transform FIR coefficients.
5185 The resulting stream can be used with @ref{afir} filter for phase-shifting
5186 the signal by 90 degrees.
5188 This is used in many matrix coding schemes and for analytic signal generation.
5189 The process is often written as a multiplication by i (or j), the imaginary unit.
5191 The filter accepts the following options:
5195 @item sample_rate, s
5196 Set sample rate, default is 44100.
5199 Set length of FIR filter, default is 22051.
5202 Set number of samples per each frame.
5205 Set window function to be used when generating FIR coefficients.
5210 Generate an audio signal made of a sine wave with amplitude 1/8.
5212 The audio signal is bit-exact.
5214 The filter accepts the following options:
5219 Set the carrier frequency. Default is 440 Hz.
5221 @item beep_factor, b
5222 Enable a periodic beep every second with frequency @var{beep_factor} times
5223 the carrier frequency. Default is 0, meaning the beep is disabled.
5225 @item sample_rate, r
5226 Specify the sample rate, default is 44100.
5229 Specify the duration of the generated audio stream.
5231 @item samples_per_frame
5232 Set the number of samples per output frame.
5234 The expression can contain the following constants:
5238 The (sequential) number of the output audio frame, starting from 0.
5241 The PTS (Presentation TimeStamp) of the output audio frame,
5242 expressed in @var{TB} units.
5245 The PTS of the output audio frame, expressed in seconds.
5248 The timebase of the output audio frames.
5251 Default is @code{1024}.
5254 @subsection Examples
5259 Generate a simple 440 Hz sine wave:
5265 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
5269 sine=frequency=220:beep_factor=4:duration=5
5273 Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC
5276 sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
5280 @c man end AUDIO SOURCES
5282 @chapter Audio Sinks
5283 @c man begin AUDIO SINKS
5285 Below is a description of the currently available audio sinks.
5287 @section abuffersink
5289 Buffer audio frames, and make them available to the end of filter chain.
5291 This sink is mainly intended for programmatic use, in particular
5292 through the interface defined in @file{libavfilter/buffersink.h}
5293 or the options system.
5295 It accepts a pointer to an AVABufferSinkContext structure, which
5296 defines the incoming buffers' formats, to be passed as the opaque
5297 parameter to @code{avfilter_init_filter} for initialization.
5300 Null audio sink; do absolutely nothing with the input audio. It is
5301 mainly useful as a template and for use in analysis / debugging
5304 @c man end AUDIO SINKS
5306 @chapter Video Filters
5307 @c man begin VIDEO FILTERS
5309 When you configure your FFmpeg build, you can disable any of the
5310 existing filters using @code{--disable-filters}.
5311 The configure output will show the video filters included in your
5314 Below is a description of the currently available video filters.
5316 @section alphaextract
5318 Extract the alpha component from the input as a grayscale video. This
5319 is especially useful with the @var{alphamerge} filter.
5323 Add or replace the alpha component of the primary input with the
5324 grayscale value of a second input. This is intended for use with
5325 @var{alphaextract} to allow the transmission or storage of frame
5326 sequences that have alpha in a format that doesn't support an alpha
5329 For example, to reconstruct full frames from a normal YUV-encoded video
5330 and a separate video created with @var{alphaextract}, you might use:
5332 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
5335 Since this filter is designed for reconstruction, it operates on frame
5336 sequences without considering timestamps, and terminates when either
5337 input reaches end of stream. This will cause problems if your encoding
5338 pipeline drops frames. If you're trying to apply an image as an
5339 overlay to a video stream, consider the @var{overlay} filter instead.
5343 Amplify differences between current pixel and pixels of adjacent frames in
5344 same pixel location.
5346 This filter accepts the following options:
5350 Set frame radius. Default is 2. Allowed range is from 1 to 63.
5351 For example radius of 3 will instruct filter to calculate average of 7 frames.
5354 Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535.
5357 Set threshold for difference amplification. Any differrence greater or equal to
5358 this value will not alter source pixel. Default is 10.
5359 Allowed range is from 0 to 65535.
5362 Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
5363 This option controls maximum possible value that will decrease source pixel value.
5366 Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
5367 This option controls maximum possible value that will increase source pixel value.
5370 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
5375 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
5376 and libavformat to work. On the other hand, it is limited to ASS (Advanced
5377 Substation Alpha) subtitles files.
5379 This filter accepts the following option in addition to the common options from
5380 the @ref{subtitles} filter:
5384 Set the shaping engine
5386 Available values are:
5389 The default libass shaping engine, which is the best available.
5391 Fast, font-agnostic shaper that can do only substitutions
5393 Slower shaper using OpenType for substitutions and positioning
5396 The default is @code{auto}.
5400 Apply an Adaptive Temporal Averaging Denoiser to the video input.
5402 The filter accepts the following options:
5406 Set threshold A for 1st plane. Default is 0.02.
5407 Valid range is 0 to 0.3.
5410 Set threshold B for 1st plane. Default is 0.04.
5411 Valid range is 0 to 5.
5414 Set threshold A for 2nd plane. Default is 0.02.
5415 Valid range is 0 to 0.3.
5418 Set threshold B for 2nd plane. Default is 0.04.
5419 Valid range is 0 to 5.
5422 Set threshold A for 3rd plane. Default is 0.02.
5423 Valid range is 0 to 0.3.
5426 Set threshold B for 3rd plane. Default is 0.04.
5427 Valid range is 0 to 5.
5429 Threshold A is designed to react on abrupt changes in the input signal and
5430 threshold B is designed to react on continuous changes in the input signal.
5433 Set number of frames filter will use for averaging. Default is 9. Must be odd
5434 number in range [5, 129].
5437 Set what planes of frame filter will use for averaging. Default is all.
5442 Apply average blur filter.
5444 The filter accepts the following options:
5448 Set horizontal radius size.
5451 Set which planes to filter. By default all planes are filtered.
5454 Set vertical radius size, if zero it will be same as @code{sizeX}.
5455 Default is @code{0}.
5460 Compute the bounding box for the non-black pixels in the input frame
5463 This filter computes the bounding box containing all the pixels with a
5464 luminance value greater than the minimum allowed value.
5465 The parameters describing the bounding box are printed on the filter
5468 The filter accepts the following option:
5472 Set the minimal luminance value. Default is @code{16}.
5475 @section bitplanenoise
5477 Show and measure bit plane noise.
5479 The filter accepts the following options:
5483 Set which plane to analyze. Default is @code{1}.
5486 Filter out noisy pixels from @code{bitplane} set above.
5487 Default is disabled.
5490 @section blackdetect
5492 Detect video intervals that are (almost) completely black. Can be
5493 useful to detect chapter transitions, commercials, or invalid
5494 recordings. Output lines contains the time for the start, end and
5495 duration of the detected black interval expressed in seconds.
5497 In order to display the output lines, you need to set the loglevel at
5498 least to the AV_LOG_INFO value.
5500 The filter accepts the following options:
5503 @item black_min_duration, d
5504 Set the minimum detected black duration expressed in seconds. It must
5505 be a non-negative floating point number.
5507 Default value is 2.0.
5509 @item picture_black_ratio_th, pic_th
5510 Set the threshold for considering a picture "black".
5511 Express the minimum value for the ratio:
5513 @var{nb_black_pixels} / @var{nb_pixels}
5516 for which a picture is considered black.
5517 Default value is 0.98.
5519 @item pixel_black_th, pix_th
5520 Set the threshold for considering a pixel "black".
5522 The threshold expresses the maximum pixel luminance value for which a
5523 pixel is considered "black". The provided value is scaled according to
5524 the following equation:
5526 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
5529 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
5530 the input video format, the range is [0-255] for YUV full-range
5531 formats and [16-235] for YUV non full-range formats.
5533 Default value is 0.10.
5536 The following example sets the maximum pixel threshold to the minimum
5537 value, and detects only black intervals of 2 or more seconds:
5539 blackdetect=d=2:pix_th=0.00
5544 Detect frames that are (almost) completely black. Can be useful to
5545 detect chapter transitions or commercials. Output lines consist of
5546 the frame number of the detected frame, the percentage of blackness,
5547 the position in the file if known or -1 and the timestamp in seconds.
5549 In order to display the output lines, you need to set the loglevel at
5550 least to the AV_LOG_INFO value.
5552 This filter exports frame metadata @code{lavfi.blackframe.pblack}.
5553 The value represents the percentage of pixels in the picture that
5554 are below the threshold value.
5556 It accepts the following parameters:
5561 The percentage of the pixels that have to be below the threshold; it defaults to
5564 @item threshold, thresh
5565 The threshold below which a pixel value is considered black; it defaults to
5570 @section blend, tblend
5572 Blend two video frames into each other.
5574 The @code{blend} filter takes two input streams and outputs one
5575 stream, the first input is the "top" layer and second input is
5576 "bottom" layer. By default, the output terminates when the longest input terminates.
5578 The @code{tblend} (time blend) filter takes two consecutive frames
5579 from one single stream, and outputs the result obtained by blending
5580 the new frame on top of the old frame.
5582 A description of the accepted options follows.
5590 Set blend mode for specific pixel component or all pixel components in case
5591 of @var{all_mode}. Default value is @code{normal}.
5593 Available values for component modes are:
5635 Set blend opacity for specific pixel component or all pixel components in case
5636 of @var{all_opacity}. Only used in combination with pixel component blend modes.
5643 Set blend expression for specific pixel component or all pixel components in case
5644 of @var{all_expr}. Note that related mode options will be ignored if those are set.
5646 The expressions can use the following variables:
5650 The sequential number of the filtered frame, starting from @code{0}.
5654 the coordinates of the current sample
5658 the width and height of currently filtered plane
5662 Width and height scale for the plane being filtered. It is the
5663 ratio between the dimensions of the current plane to the luma plane,
5664 e.g. for a @code{yuv420p} frame, the values are @code{1,1} for
5665 the luma plane and @code{0.5,0.5} for the chroma planes.
5668 Time of the current frame, expressed in seconds.
5671 Value of pixel component at current location for first video frame (top layer).
5674 Value of pixel component at current location for second video frame (bottom layer).
5678 The @code{blend} filter also supports the @ref{framesync} options.
5680 @subsection Examples
5684 Apply transition from bottom layer to top layer in first 10 seconds:
5686 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
5690 Apply linear horizontal transition from top layer to bottom layer:
5692 blend=all_expr='A*(X/W)+B*(1-X/W)'
5696 Apply 1x1 checkerboard effect:
5698 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
5702 Apply uncover left effect:
5704 blend=all_expr='if(gte(N*SW+X,W),A,B)'
5708 Apply uncover down effect:
5710 blend=all_expr='if(gte(Y-N*SH,0),A,B)'
5714 Apply uncover up-left effect:
5716 blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
5720 Split diagonally video and shows top and bottom layer on each side:
5722 blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
5726 Display differences between the current and the previous frame:
5728 tblend=all_mode=grainextract
5734 Apply a boxblur algorithm to the input video.
5736 It accepts the following parameters:
5740 @item luma_radius, lr
5741 @item luma_power, lp
5742 @item chroma_radius, cr
5743 @item chroma_power, cp
5744 @item alpha_radius, ar
5745 @item alpha_power, ap
5749 A description of the accepted options follows.
5752 @item luma_radius, lr
5753 @item chroma_radius, cr
5754 @item alpha_radius, ar
5755 Set an expression for the box radius in pixels used for blurring the
5756 corresponding input plane.
5758 The radius value must be a non-negative number, and must not be
5759 greater than the value of the expression @code{min(w,h)/2} for the
5760 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
5763 Default value for @option{luma_radius} is "2". If not specified,
5764 @option{chroma_radius} and @option{alpha_radius} default to the
5765 corresponding value set for @option{luma_radius}.
5767 The expressions can contain the following constants:
5771 The input width and height in pixels.
5775 The input chroma image width and height in pixels.
5779 The horizontal and vertical chroma subsample values. For example, for the
5780 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
5783 @item luma_power, lp
5784 @item chroma_power, cp
5785 @item alpha_power, ap
5786 Specify how many times the boxblur filter is applied to the
5787 corresponding plane.
5789 Default value for @option{luma_power} is 2. If not specified,
5790 @option{chroma_power} and @option{alpha_power} default to the
5791 corresponding value set for @option{luma_power}.
5793 A value of 0 will disable the effect.
5796 @subsection Examples
5800 Apply a boxblur filter with the luma, chroma, and alpha radii
5803 boxblur=luma_radius=2:luma_power=1
5808 Set the luma radius to 2, and alpha and chroma radius to 0:
5810 boxblur=2:1:cr=0:ar=0
5814 Set the luma and chroma radii to a fraction of the video dimension:
5816 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
5822 Deinterlace the input video ("bwdif" stands for "Bob Weaver
5823 Deinterlacing Filter").
5825 Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
5826 interpolation algorithms.
5827 It accepts the following parameters:
5831 The interlacing mode to adopt. It accepts one of the following values:
5835 Output one frame for each frame.
5837 Output one frame for each field.
5840 The default value is @code{send_field}.
5843 The picture field parity assumed for the input interlaced video. It accepts one
5844 of the following values:
5848 Assume the top field is first.
5850 Assume the bottom field is first.
5852 Enable automatic detection of field parity.
5855 The default value is @code{auto}.
5856 If the interlacing is unknown or the decoder does not export this information,
5857 top field first will be assumed.
5860 Specify which frames to deinterlace. Accept one of the following
5865 Deinterlace all frames.
5867 Only deinterlace frames marked as interlaced.
5870 The default value is @code{all}.
5874 YUV colorspace color/chroma keying.
5876 The filter accepts the following options:
5880 The color which will be replaced with transparency.
5883 Similarity percentage with the key color.
5885 0.01 matches only the exact key color, while 1.0 matches everything.
5890 0.0 makes pixels either fully transparent, or not transparent at all.
5892 Higher values result in semi-transparent pixels, with a higher transparency
5893 the more similar the pixels color is to the key color.
5896 Signals that the color passed is already in YUV instead of RGB.
5898 Literal colors like "green" or "red" don't make sense with this enabled anymore.
5899 This can be used to pass exact YUV values as hexadecimal numbers.
5902 @subsection Examples
5906 Make every green pixel in the input image transparent:
5908 ffmpeg -i input.png -vf chromakey=green out.png
5912 Overlay a greenscreen-video on top of a static black background.
5914 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
5920 Display CIE color diagram with pixels overlaid onto it.
5922 The filter accepts the following options:
5937 @item uhdtv, rec2020
5950 Set what gamuts to draw.
5952 See @code{system} option for available values.
5955 Set ciescope size, by default set to 512.
5958 Set intensity used to map input pixel values to CIE diagram.
5961 Set contrast used to draw tongue colors that are out of active color system gamut.
5964 Correct gamma displayed on scope, by default enabled.
5967 Show white point on CIE diagram, by default disabled.
5970 Set input gamma. Used only with XYZ input color space.
5975 Visualize information exported by some codecs.
5977 Some codecs can export information through frames using side-data or other
5978 means. For example, some MPEG based codecs export motion vectors through the
5979 @var{export_mvs} flag in the codec @option{flags2} option.
5981 The filter accepts the following option:
5985 Set motion vectors to visualize.
5987 Available flags for @var{mv} are:
5991 forward predicted MVs of P-frames
5993 forward predicted MVs of B-frames
5995 backward predicted MVs of B-frames
5999 Display quantization parameters using the chroma planes.
6002 Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
6004 Available flags for @var{mv_type} are:
6008 forward predicted MVs
6010 backward predicted MVs
6013 @item frame_type, ft
6014 Set frame type to visualize motion vectors of.
6016 Available flags for @var{frame_type} are:
6020 intra-coded frames (I-frames)
6022 predicted frames (P-frames)
6024 bi-directionally predicted frames (B-frames)
6028 @subsection Examples
6032 Visualize forward predicted MVs of all frames using @command{ffplay}:
6034 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
6038 Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
6040 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
6044 @section colorbalance
6045 Modify intensity of primary colors (red, green and blue) of input frames.
6047 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
6048 regions for the red-cyan, green-magenta or blue-yellow balance.
6050 A positive adjustment value shifts the balance towards the primary color, a negative
6051 value towards the complementary color.
6053 The filter accepts the following options:
6059 Adjust red, green and blue shadows (darkest pixels).
6064 Adjust red, green and blue midtones (medium pixels).
6069 Adjust red, green and blue highlights (brightest pixels).
6071 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
6074 @subsection Examples
6078 Add red color cast to shadows:
6085 RGB colorspace color keying.
6087 The filter accepts the following options:
6091 The color which will be replaced with transparency.
6094 Similarity percentage with the key color.
6096 0.01 matches only the exact key color, while 1.0 matches everything.
6101 0.0 makes pixels either fully transparent, or not transparent at all.
6103 Higher values result in semi-transparent pixels, with a higher transparency
6104 the more similar the pixels color is to the key color.
6107 @subsection Examples
6111 Make every green pixel in the input image transparent:
6113 ffmpeg -i input.png -vf colorkey=green out.png
6117 Overlay a greenscreen-video on top of a static background image.
6119 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
6123 @section colorlevels
6125 Adjust video input frames using levels.
6127 The filter accepts the following options:
6134 Adjust red, green, blue and alpha input black point.
6135 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
6141 Adjust red, green, blue and alpha input white point.
6142 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
6144 Input levels are used to lighten highlights (bright tones), darken shadows
6145 (dark tones), change the balance of bright and dark tones.
6151 Adjust red, green, blue and alpha output black point.
6152 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
6158 Adjust red, green, blue and alpha output white point.
6159 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
6161 Output levels allows manual selection of a constrained output level range.
6164 @subsection Examples
6168 Make video output darker:
6170 colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
6176 colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
6180 Make video output lighter:
6182 colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
6186 Increase brightness:
6188 colorlevels=romin=0.5:gomin=0.5:bomin=0.5
6192 @section colorchannelmixer
6194 Adjust video input frames by re-mixing color channels.
6196 This filter modifies a color channel by adding the values associated to
6197 the other channels of the same pixels. For example if the value to
6198 modify is red, the output value will be:
6200 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
6203 The filter accepts the following options:
6210 Adjust contribution of input red, green, blue and alpha channels for output red channel.
6211 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
6217 Adjust contribution of input red, green, blue and alpha channels for output green channel.
6218 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
6224 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
6225 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
6231 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
6232 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
6234 Allowed ranges for options are @code{[-2.0, 2.0]}.
6237 @subsection Examples
6241 Convert source to grayscale:
6243 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
6246 Simulate sepia tones:
6248 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
6252 @section colormatrix
6254 Convert color matrix.
6256 The filter accepts the following options:
6261 Specify the source and destination color matrix. Both values must be
6264 The accepted values are:
6292 For example to convert from BT.601 to SMPTE-240M, use the command:
6294 colormatrix=bt601:smpte240m
6299 Convert colorspace, transfer characteristics or color primaries.
6300 Input video needs to have an even size.
6302 The filter accepts the following options:
6307 Specify all color properties at once.
6309 The accepted values are:
6339 Specify output colorspace.
6341 The accepted values are:
6350 BT.470BG or BT.601-6 625
6353 SMPTE-170M or BT.601-6 525
6362 BT.2020 with non-constant luminance
6368 Specify output transfer characteristics.
6370 The accepted values are:
6382 Constant gamma of 2.2
6385 Constant gamma of 2.8
6388 SMPTE-170M, BT.601-6 625 or BT.601-6 525
6406 BT.2020 for 10-bits content
6409 BT.2020 for 12-bits content
6415 Specify output color primaries.
6417 The accepted values are:
6426 BT.470BG or BT.601-6 625
6429 SMPTE-170M or BT.601-6 525
6453 Specify output color range.
6455 The accepted values are:
6458 TV (restricted) range
6461 MPEG (restricted) range
6472 Specify output color format.
6474 The accepted values are:
6477 YUV 4:2:0 planar 8-bits
6480 YUV 4:2:0 planar 10-bits
6483 YUV 4:2:0 planar 12-bits
6486 YUV 4:2:2 planar 8-bits
6489 YUV 4:2:2 planar 10-bits
6492 YUV 4:2:2 planar 12-bits
6495 YUV 4:4:4 planar 8-bits
6498 YUV 4:4:4 planar 10-bits
6501 YUV 4:4:4 planar 12-bits
6506 Do a fast conversion, which skips gamma/primary correction. This will take
6507 significantly less CPU, but will be mathematically incorrect. To get output
6508 compatible with that produced by the colormatrix filter, use fast=1.
6511 Specify dithering mode.
6513 The accepted values are:
6519 Floyd-Steinberg dithering
6523 Whitepoint adaptation mode.
6525 The accepted values are:
6528 Bradford whitepoint adaptation
6531 von Kries whitepoint adaptation
6534 identity whitepoint adaptation (i.e. no whitepoint adaptation)
6538 Override all input properties at once. Same accepted values as @ref{all}.
6541 Override input colorspace. Same accepted values as @ref{space}.
6544 Override input color primaries. Same accepted values as @ref{primaries}.
6547 Override input transfer characteristics. Same accepted values as @ref{trc}.
6550 Override input color range. Same accepted values as @ref{range}.
6554 The filter converts the transfer characteristics, color space and color
6555 primaries to the specified user values. The output value, if not specified,
6556 is set to a default value based on the "all" property. If that property is
6557 also not specified, the filter will log an error. The output color range and
6558 format default to the same value as the input color range and format. The
6559 input transfer characteristics, color space, color primaries and color range
6560 should be set on the input data. If any of these are missing, the filter will
6561 log an error and no conversion will take place.
6563 For example to convert the input to SMPTE-240M, use the command:
6565 colorspace=smpte240m
6568 @section convolution
6570 Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
6572 The filter accepts the following options:
6579 Set matrix for each plane.
6580 Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode,
6581 and from 1 to 49 odd number of signed integers in @var{row} mode.
6587 Set multiplier for calculated value for each plane.
6588 If unset or 0, it will be sum of all matrix elements.
6594 Set bias for each plane. This value is added to the result of the multiplication.
6595 Useful for making the overall image brighter or darker. Default is 0.0.
6601 Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}.
6602 Default is @var{square}.
6605 @subsection Examples
6611 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"
6617 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"
6623 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"
6629 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"
6633 Apply laplacian edge detector which includes diagonals:
6635 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"
6641 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"
6647 Apply 2D convolution of video stream in frequency domain using second stream
6650 The filter accepts the following options:
6654 Set which planes to process.
6657 Set which impulse video frames will be processed, can be @var{first}
6658 or @var{all}. Default is @var{all}.
6661 The @code{convolve} filter also supports the @ref{framesync} options.
6665 Copy the input video source unchanged to the output. This is mainly useful for
6670 Video filtering on GPU using Apple's CoreImage API on OSX.
6672 Hardware acceleration is based on an OpenGL context. Usually, this means it is
6673 processed by video hardware. However, software-based OpenGL implementations
6674 exist which means there is no guarantee for hardware processing. It depends on
6677 There are many filters and image generators provided by Apple that come with a
6678 large variety of options. The filter has to be referenced by its name along
6681 The coreimage filter accepts the following options:
6684 List all available filters and generators along with all their respective
6685 options as well as possible minimum and maximum values along with the default
6692 Specify all filters by their respective name and options.
6693 Use @var{list_filters} to determine all valid filter names and options.
6694 Numerical options are specified by a float value and are automatically clamped
6695 to their respective value range. Vector and color options have to be specified
6696 by a list of space separated float values. Character escaping has to be done.
6697 A special option name @code{default} is available to use default options for a
6700 It is required to specify either @code{default} or at least one of the filter options.
6701 All omitted options are used with their default values.
6702 The syntax of the filter string is as follows:
6704 filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
6708 Specify a rectangle where the output of the filter chain is copied into the
6709 input image. It is given by a list of space separated float values:
6711 output_rect=x\ y\ width\ height
6713 If not given, the output rectangle equals the dimensions of the input image.
6714 The output rectangle is automatically cropped at the borders of the input
6715 image. Negative values are valid for each component.
6717 output_rect=25\ 25\ 100\ 100
6721 Several filters can be chained for successive processing without GPU-HOST
6722 transfers allowing for fast processing of complex filter chains.
6723 Currently, only filters with zero (generators) or exactly one (filters) input
6724 image and one output image are supported. Also, transition filters are not yet
6727 Some filters generate output images with additional padding depending on the
6728 respective filter kernel. The padding is automatically removed to ensure the
6729 filter output has the same size as the input image.
6731 For image generators, the size of the output image is determined by the
6732 previous output image of the filter chain or the input image of the whole
6733 filterchain, respectively. The generators do not use the pixel information of
6734 this image to generate their output. However, the generated output is
6735 blended onto this image, resulting in partial or complete coverage of the
6738 The @ref{coreimagesrc} video source can be used for generating input images
6739 which are directly fed into the filter chain. By using it, providing input
6740 images by another video source or an input video is not required.
6742 @subsection Examples
6747 List all filters available:
6749 coreimage=list_filters=true
6753 Use the CIBoxBlur filter with default options to blur an image:
6755 coreimage=filter=CIBoxBlur@@default
6759 Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
6760 its center at 100x100 and a radius of 50 pixels:
6762 coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
6766 Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
6767 given as complete and escaped command-line for Apple's standard bash shell:
6769 ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
6775 Crop the input video to given dimensions.
6777 It accepts the following parameters:
6781 The width of the output video. It defaults to @code{iw}.
6782 This expression is evaluated only once during the filter
6783 configuration, or when the @samp{w} or @samp{out_w} command is sent.
6786 The height of the output video. It defaults to @code{ih}.
6787 This expression is evaluated only once during the filter
6788 configuration, or when the @samp{h} or @samp{out_h} command is sent.
6791 The horizontal position, in the input video, of the left edge of the output
6792 video. It defaults to @code{(in_w-out_w)/2}.
6793 This expression is evaluated per-frame.
6796 The vertical position, in the input video, of the top edge of the output video.
6797 It defaults to @code{(in_h-out_h)/2}.
6798 This expression is evaluated per-frame.
6801 If set to 1 will force the output display aspect ratio
6802 to be the same of the input, by changing the output sample aspect
6803 ratio. It defaults to 0.
6806 Enable exact cropping. If enabled, subsampled videos will be cropped at exact
6807 width/height/x/y as specified and will not be rounded to nearest smaller value.
6811 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
6812 expressions containing the following constants:
6817 The computed values for @var{x} and @var{y}. They are evaluated for
6822 The input width and height.
6826 These are the same as @var{in_w} and @var{in_h}.
6830 The output (cropped) width and height.
6834 These are the same as @var{out_w} and @var{out_h}.
6837 same as @var{iw} / @var{ih}
6840 input sample aspect ratio
6843 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
6847 horizontal and vertical chroma subsample values. For example for the
6848 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
6851 The number of the input frame, starting from 0.
6854 the position in the file of the input frame, NAN if unknown
6857 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
6861 The expression for @var{out_w} may depend on the value of @var{out_h},
6862 and the expression for @var{out_h} may depend on @var{out_w}, but they
6863 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
6864 evaluated after @var{out_w} and @var{out_h}.
6866 The @var{x} and @var{y} parameters specify the expressions for the
6867 position of the top-left corner of the output (non-cropped) area. They
6868 are evaluated for each frame. If the evaluated value is not valid, it
6869 is approximated to the nearest valid value.
6871 The expression for @var{x} may depend on @var{y}, and the expression
6872 for @var{y} may depend on @var{x}.
6874 @subsection Examples
6878 Crop area with size 100x100 at position (12,34).
6883 Using named options, the example above becomes:
6885 crop=w=100:h=100:x=12:y=34
6889 Crop the central input area with size 100x100:
6895 Crop the central input area with size 2/3 of the input video:
6897 crop=2/3*in_w:2/3*in_h
6901 Crop the input video central square:
6908 Delimit the rectangle with the top-left corner placed at position
6909 100:100 and the right-bottom corner corresponding to the right-bottom
6910 corner of the input image.
6912 crop=in_w-100:in_h-100:100:100
6916 Crop 10 pixels from the left and right borders, and 20 pixels from
6917 the top and bottom borders
6919 crop=in_w-2*10:in_h-2*20
6923 Keep only the bottom right quarter of the input image:
6925 crop=in_w/2:in_h/2:in_w/2:in_h/2
6929 Crop height for getting Greek harmony:
6931 crop=in_w:1/PHI*in_w
6935 Apply trembling effect:
6937 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)
6941 Apply erratic camera effect depending on timestamp:
6943 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)"
6947 Set x depending on the value of y:
6949 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
6953 @subsection Commands
6955 This filter supports the following commands:
6961 Set width/height of the output video and the horizontal/vertical position
6963 The command accepts the same syntax of the corresponding option.
6965 If the specified expression is not valid, it is kept at its current
6971 Auto-detect the crop size.
6973 It calculates the necessary cropping parameters and prints the
6974 recommended parameters via the logging system. The detected dimensions
6975 correspond to the non-black area of the input video.
6977 It accepts the following parameters:
6982 Set higher black value threshold, which can be optionally specified
6983 from nothing (0) to everything (255 for 8-bit based formats). An intensity
6984 value greater to the set value is considered non-black. It defaults to 24.
6985 You can also specify a value between 0.0 and 1.0 which will be scaled depending
6986 on the bitdepth of the pixel format.
6989 The value which the width/height should be divisible by. It defaults to
6990 16. The offset is automatically adjusted to center the video. Use 2 to
6991 get only even dimensions (needed for 4:2:2 video). 16 is best when
6992 encoding to most video codecs.
6994 @item reset_count, reset
6995 Set the counter that determines after how many frames cropdetect will
6996 reset the previously detected largest video area and start over to
6997 detect the current optimal crop area. Default value is 0.
6999 This can be useful when channel logos distort the video area. 0
7000 indicates 'never reset', and returns the largest area encountered during
7007 Delay video filtering until a given wallclock timestamp. The filter first
7008 passes on @option{preroll} amount of frames, then it buffers at most
7009 @option{buffer} amount of frames and waits for the cue. After reaching the cue
7010 it forwards the buffered frames and also any subsequent frames coming in its
7013 The filter can be used synchronize the output of multiple ffmpeg processes for
7014 realtime output devices like decklink. By putting the delay in the filtering
7015 chain and pre-buffering frames the process can pass on data to output almost
7016 immediately after the target wallclock timestamp is reached.
7018 Perfect frame accuracy cannot be guaranteed, but the result is good enough for
7024 The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0.
7027 The duration of content to pass on as preroll expressed in seconds. Default is 0.
7030 The maximum duration of content to buffer before waiting for the cue expressed
7031 in seconds. Default is 0.
7038 Apply color adjustments using curves.
7040 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
7041 component (red, green and blue) has its values defined by @var{N} key points
7042 tied from each other using a smooth curve. The x-axis represents the pixel
7043 values from the input frame, and the y-axis the new pixel values to be set for
7046 By default, a component curve is defined by the two points @var{(0;0)} and
7047 @var{(1;1)}. This creates a straight line where each original pixel value is
7048 "adjusted" to its own value, which means no change to the image.
7050 The filter allows you to redefine these two points and add some more. A new
7051 curve (using a natural cubic spline interpolation) will be define to pass
7052 smoothly through all these new coordinates. The new defined points needs to be
7053 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
7054 be in the @var{[0;1]} interval. If the computed curves happened to go outside
7055 the vector spaces, the values will be clipped accordingly.
7057 The filter accepts the following options:
7061 Select one of the available color presets. This option can be used in addition
7062 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
7063 options takes priority on the preset values.
7064 Available presets are:
7067 @item color_negative
7070 @item increase_contrast
7072 @item linear_contrast
7073 @item medium_contrast
7075 @item strong_contrast
7078 Default is @code{none}.
7080 Set the master key points. These points will define a second pass mapping. It
7081 is sometimes called a "luminance" or "value" mapping. It can be used with
7082 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
7083 post-processing LUT.
7085 Set the key points for the red component.
7087 Set the key points for the green component.
7089 Set the key points for the blue component.
7091 Set the key points for all components (not including master).
7092 Can be used in addition to the other key points component
7093 options. In this case, the unset component(s) will fallback on this
7094 @option{all} setting.
7096 Specify a Photoshop curves file (@code{.acv}) to import the settings from.
7098 Save Gnuplot script of the curves in specified file.
7101 To avoid some filtergraph syntax conflicts, each key points list need to be
7102 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
7104 @subsection Examples
7108 Increase slightly the middle level of blue:
7110 curves=blue='0/0 0.5/0.58 1/1'
7116 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'
7118 Here we obtain the following coordinates for each components:
7121 @code{(0;0.11) (0.42;0.51) (1;0.95)}
7123 @code{(0;0) (0.50;0.48) (1;1)}
7125 @code{(0;0.22) (0.49;0.44) (1;0.80)}
7129 The previous example can also be achieved with the associated built-in preset:
7131 curves=preset=vintage
7141 Use a Photoshop preset and redefine the points of the green component:
7143 curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
7147 Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
7148 and @command{gnuplot}:
7150 ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
7151 gnuplot -p /tmp/curves.plt
7157 Video data analysis filter.
7159 This filter shows hexadecimal pixel values of part of video.
7161 The filter accepts the following options:
7165 Set output video size.
7168 Set x offset from where to pick pixels.
7171 Set y offset from where to pick pixels.
7174 Set scope mode, can be one of the following:
7177 Draw hexadecimal pixel values with white color on black background.
7180 Draw hexadecimal pixel values with input video pixel color on black
7184 Draw hexadecimal pixel values on color background picked from input video,
7185 the text color is picked in such way so its always visible.
7189 Draw rows and columns numbers on left and top of video.
7192 Set background opacity.
7197 Denoise frames using 2D DCT (frequency domain filtering).
7199 This filter is not designed for real time.
7201 The filter accepts the following options:
7205 Set the noise sigma constant.
7207 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
7208 coefficient (absolute value) below this threshold with be dropped.
7210 If you need a more advanced filtering, see @option{expr}.
7212 Default is @code{0}.
7215 Set number overlapping pixels for each block. Since the filter can be slow, you
7216 may want to reduce this value, at the cost of a less effective filter and the
7217 risk of various artefacts.
7219 If the overlapping value doesn't permit processing the whole input width or
7220 height, a warning will be displayed and according borders won't be denoised.
7222 Default value is @var{blocksize}-1, which is the best possible setting.
7225 Set the coefficient factor expression.
7227 For each coefficient of a DCT block, this expression will be evaluated as a
7228 multiplier value for the coefficient.
7230 If this is option is set, the @option{sigma} option will be ignored.
7232 The absolute value of the coefficient can be accessed through the @var{c}
7236 Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
7237 @var{blocksize}, which is the width and height of the processed blocks.
7239 The default value is @var{3} (8x8) and can be raised to @var{4} for a
7240 @var{blocksize} of 16x16. Note that changing this setting has huge consequences
7241 on the speed processing. Also, a larger block size does not necessarily means a
7245 @subsection Examples
7247 Apply a denoise with a @option{sigma} of @code{4.5}:
7252 The same operation can be achieved using the expression system:
7254 dctdnoiz=e='gte(c, 4.5*3)'
7257 Violent denoise using a block size of @code{16x16}:
7264 Remove banding artifacts from input video.
7265 It works by replacing banded pixels with average value of referenced pixels.
7267 The filter accepts the following options:
7274 Set banding detection threshold for each plane. Default is 0.02.
7275 Valid range is 0.00003 to 0.5.
7276 If difference between current pixel and reference pixel is less than threshold,
7277 it will be considered as banded.
7280 Banding detection range in pixels. Default is 16. If positive, random number
7281 in range 0 to set value will be used. If negative, exact absolute value
7283 The range defines square of four pixels around current pixel.
7286 Set direction in radians from which four pixel will be compared. If positive,
7287 random direction from 0 to set direction will be picked. If negative, exact of
7288 absolute value will be picked. For example direction 0, -PI or -2*PI radians
7289 will pick only pixels on same row and -PI/2 will pick only pixels on same
7293 If enabled, current pixel is compared with average value of all four
7294 surrounding pixels. The default is enabled. If disabled current pixel is
7295 compared with all four surrounding pixels. The pixel is considered banded
7296 if only all four differences with surrounding pixels are less than threshold.
7299 If enabled, current pixel is changed if and only if all pixel components are banded,
7300 e.g. banding detection threshold is triggered for all color components.
7301 The default is disabled.
7306 Remove blocking artifacts from input video.
7308 The filter accepts the following options:
7312 Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}.
7313 This controls what kind of deblocking is applied.
7316 Set size of block, allowed range is from 4 to 512. Default is @var{8}.
7322 Set blocking detection thresholds. Allowed range is 0 to 1.
7323 Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest.
7324 Using higher threshold gives more deblocking strength.
7325 Setting @var{alpha} controls threshold detection at exact edge of block.
7326 Remaining options controls threshold detection near the edge. Each one for
7327 below/above or left/right. Setting any of those to @var{0} disables
7331 Set planes to filter. Default is to filter all available planes.
7334 @subsection Examples
7338 Deblock using weak filter and block size of 4 pixels.
7340 deblock=filter=weak:block=4
7344 Deblock using strong filter, block size of 4 pixels and custom thresholds for
7345 deblocking more edges.
7347 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
7351 Similar as above, but filter only first plane.
7353 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
7357 Similar as above, but filter only second and third plane.
7359 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
7366 Drop duplicated frames at regular intervals.
7368 The filter accepts the following options:
7372 Set the number of frames from which one will be dropped. Setting this to
7373 @var{N} means one frame in every batch of @var{N} frames will be dropped.
7374 Default is @code{5}.
7377 Set the threshold for duplicate detection. If the difference metric for a frame
7378 is less than or equal to this value, then it is declared as duplicate. Default
7382 Set scene change threshold. Default is @code{15}.
7386 Set the size of the x and y-axis blocks used during metric calculations.
7387 Larger blocks give better noise suppression, but also give worse detection of
7388 small movements. Must be a power of two. Default is @code{32}.
7391 Mark main input as a pre-processed input and activate clean source input
7392 stream. This allows the input to be pre-processed with various filters to help
7393 the metrics calculation while keeping the frame selection lossless. When set to
7394 @code{1}, the first stream is for the pre-processed input, and the second
7395 stream is the clean source from where the kept frames are chosen. Default is
7399 Set whether or not chroma is considered in the metric calculations. Default is
7405 Apply 2D deconvolution of video stream in frequency domain using second stream
7408 The filter accepts the following options:
7412 Set which planes to process.
7415 Set which impulse video frames will be processed, can be @var{first}
7416 or @var{all}. Default is @var{all}.
7419 Set noise when doing divisions. Default is @var{0.0000001}. Useful when width
7420 and height are not same and not power of 2 or if stream prior to convolving
7424 The @code{deconvolve} filter also supports the @ref{framesync} options.
7428 Apply deflate effect to the video.
7430 This filter replaces the pixel by the local(3x3) average by taking into account
7431 only values lower than the pixel.
7433 It accepts the following options:
7440 Limit the maximum change for each plane, default is 65535.
7441 If 0, plane will remain unchanged.
7446 Remove temporal frame luminance variations.
7448 It accepts the following options:
7452 Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129.
7455 Set averaging mode to smooth temporal luminance variations.
7457 Available values are:
7482 Do not actually modify frame. Useful when one only wants metadata.
7487 Remove judder produced by partially interlaced telecined content.
7489 Judder can be introduced, for instance, by @ref{pullup} filter. If the original
7490 source was partially telecined content then the output of @code{pullup,dejudder}
7491 will have a variable frame rate. May change the recorded frame rate of the
7492 container. Aside from that change, this filter will not affect constant frame
7495 The option available in this filter is:
7499 Specify the length of the window over which the judder repeats.
7501 Accepts any integer greater than 1. Useful values are:
7505 If the original was telecined from 24 to 30 fps (Film to NTSC).
7508 If the original was telecined from 25 to 30 fps (PAL to NTSC).
7511 If a mixture of the two.
7514 The default is @samp{4}.
7519 Suppress a TV station logo by a simple interpolation of the surrounding
7520 pixels. Just set a rectangle covering the logo and watch it disappear
7521 (and sometimes something even uglier appear - your mileage may vary).
7523 It accepts the following parameters:
7528 Specify the top left corner coordinates of the logo. They must be
7533 Specify the width and height of the logo to clear. They must be
7537 Specify the thickness of the fuzzy edge of the rectangle (added to
7538 @var{w} and @var{h}). The default value is 1. This option is
7539 deprecated, setting higher values should no longer be necessary and
7543 When set to 1, a green rectangle is drawn on the screen to simplify
7544 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
7545 The default value is 0.
7547 The rectangle is drawn on the outermost pixels which will be (partly)
7548 replaced with interpolated values. The values of the next pixels
7549 immediately outside this rectangle in each direction will be used to
7550 compute the interpolated pixel values inside the rectangle.
7554 @subsection Examples
7558 Set a rectangle covering the area with top left corner coordinates 0,0
7559 and size 100x77, and a band of size 10:
7561 delogo=x=0:y=0:w=100:h=77:band=10
7568 Attempt to fix small changes in horizontal and/or vertical shift. This
7569 filter helps remove camera shake from hand-holding a camera, bumping a
7570 tripod, moving on a vehicle, etc.
7572 The filter accepts the following options:
7580 Specify a rectangular area where to limit the search for motion
7582 If desired the search for motion vectors can be limited to a
7583 rectangular area of the frame defined by its top left corner, width
7584 and height. These parameters have the same meaning as the drawbox
7585 filter which can be used to visualise the position of the bounding
7588 This is useful when simultaneous movement of subjects within the frame
7589 might be confused for camera motion by the motion vector search.
7591 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
7592 then the full frame is used. This allows later options to be set
7593 without specifying the bounding box for the motion vector search.
7595 Default - search the whole frame.
7599 Specify the maximum extent of movement in x and y directions in the
7600 range 0-64 pixels. Default 16.
7603 Specify how to generate pixels to fill blanks at the edge of the
7604 frame. Available values are:
7607 Fill zeroes at blank locations
7609 Original image at blank locations
7611 Extruded edge value at blank locations
7613 Mirrored edge at blank locations
7615 Default value is @samp{mirror}.
7618 Specify the blocksize to use for motion search. Range 4-128 pixels,
7622 Specify the contrast threshold for blocks. Only blocks with more than
7623 the specified contrast (difference between darkest and lightest
7624 pixels) will be considered. Range 1-255, default 125.
7627 Specify the search strategy. Available values are:
7630 Set exhaustive search
7632 Set less exhaustive search.
7634 Default value is @samp{exhaustive}.
7637 If set then a detailed log of the motion search is written to the
7644 Remove unwanted contamination of foreground colors, caused by reflected color of
7645 greenscreen or bluescreen.
7647 This filter accepts the following options:
7651 Set what type of despill to use.
7654 Set how spillmap will be generated.
7657 Set how much to get rid of still remaining spill.
7660 Controls amount of red in spill area.
7663 Controls amount of green in spill area.
7664 Should be -1 for greenscreen.
7667 Controls amount of blue in spill area.
7668 Should be -1 for bluescreen.
7671 Controls brightness of spill area, preserving colors.
7674 Modify alpha from generated spillmap.
7679 Apply an exact inverse of the telecine operation. It requires a predefined
7680 pattern specified using the pattern option which must be the same as that passed
7681 to the telecine filter.
7683 This filter accepts the following options:
7692 The default value is @code{top}.
7696 A string of numbers representing the pulldown pattern you wish to apply.
7697 The default value is @code{23}.
7700 A number representing position of the first frame with respect to the telecine
7701 pattern. This is to be used if the stream is cut. The default value is @code{0}.
7706 Apply dilation effect to the video.
7708 This filter replaces the pixel by the local(3x3) maximum.
7710 It accepts the following options:
7717 Limit the maximum change for each plane, default is 65535.
7718 If 0, plane will remain unchanged.
7721 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
7724 Flags to local 3x3 coordinates maps like this:
7733 Displace pixels as indicated by second and third input stream.
7735 It takes three input streams and outputs one stream, the first input is the
7736 source, and second and third input are displacement maps.
7738 The second input specifies how much to displace pixels along the
7739 x-axis, while the third input specifies how much to displace pixels
7741 If one of displacement map streams terminates, last frame from that
7742 displacement map will be used.
7744 Note that once generated, displacements maps can be reused over and over again.
7746 A description of the accepted options follows.
7750 Set displace behavior for pixels that are out of range.
7752 Available values are:
7755 Missing pixels are replaced by black pixels.
7758 Adjacent pixels will spread out to replace missing pixels.
7761 Out of range pixels are wrapped so they point to pixels of other side.
7764 Out of range pixels will be replaced with mirrored pixels.
7766 Default is @samp{smear}.
7770 @subsection Examples
7774 Add ripple effect to rgb input of video size hd720:
7776 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
7780 Add wave effect to rgb input of video size hd720:
7782 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
7788 Draw a colored box on the input image.
7790 It accepts the following parameters:
7795 The expressions which specify the top left corner coordinates of the box. It defaults to 0.
7799 The expressions which specify the width and height of the box; if 0 they are interpreted as
7800 the input width and height. It defaults to 0.
7803 Specify the color of the box to write. For the general syntax of this option,
7804 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
7805 value @code{invert} is used, the box edge color is the same as the
7806 video with inverted luma.
7809 The expression which sets the thickness of the box edge.
7810 A value of @code{fill} will create a filled box. Default value is @code{3}.
7812 See below for the list of accepted constants.
7815 Applicable if the input has alpha. With value @code{1}, the pixels of the painted box
7816 will overwrite the video's color and alpha pixels.
7817 Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact.
7820 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
7821 following constants:
7825 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
7829 horizontal and vertical chroma subsample values. For example for the
7830 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
7834 The input width and height.
7837 The input sample aspect ratio.
7841 The x and y offset coordinates where the box is drawn.
7845 The width and height of the drawn box.
7848 The thickness of the drawn box.
7850 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
7851 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
7855 @subsection Examples
7859 Draw a black box around the edge of the input image:
7865 Draw a box with color red and an opacity of 50%:
7867 drawbox=10:20:200:60:red@@0.5
7870 The previous example can be specified as:
7872 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
7876 Fill the box with pink color:
7878 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill
7882 Draw a 2-pixel red 2.40:1 mask:
7884 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
7890 Draw a grid on the input image.
7892 It accepts the following parameters:
7897 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
7901 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
7902 input width and height, respectively, minus @code{thickness}, so image gets
7903 framed. Default to 0.
7906 Specify the color of the grid. For the general syntax of this option,
7907 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
7908 value @code{invert} is used, the grid color is the same as the
7909 video with inverted luma.
7912 The expression which sets the thickness of the grid line. Default value is @code{1}.
7914 See below for the list of accepted constants.
7917 Applicable if the input has alpha. With @code{1} the pixels of the painted grid
7918 will overwrite the video's color and alpha pixels.
7919 Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact.
7922 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
7923 following constants:
7927 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
7931 horizontal and vertical chroma subsample values. For example for the
7932 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
7936 The input grid cell width and height.
7939 The input sample aspect ratio.
7943 The x and y coordinates of some point of grid intersection (meant to configure offset).
7947 The width and height of the drawn cell.
7950 The thickness of the drawn cell.
7952 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
7953 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
7957 @subsection Examples
7961 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
7963 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
7967 Draw a white 3x3 grid with an opacity of 50%:
7969 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
7976 Draw a text string or text from a specified file on top of a video, using the
7977 libfreetype library.
7979 To enable compilation of this filter, you need to configure FFmpeg with
7980 @code{--enable-libfreetype}.
7981 To enable default font fallback and the @var{font} option you need to
7982 configure FFmpeg with @code{--enable-libfontconfig}.
7983 To enable the @var{text_shaping} option, you need to configure FFmpeg with
7984 @code{--enable-libfribidi}.
7988 It accepts the following parameters:
7993 Used to draw a box around text using the background color.
7994 The value must be either 1 (enable) or 0 (disable).
7995 The default value of @var{box} is 0.
7998 Set the width of the border to be drawn around the box using @var{boxcolor}.
7999 The default value of @var{boxborderw} is 0.
8002 The color to be used for drawing box around text. For the syntax of this
8003 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
8005 The default value of @var{boxcolor} is "white".
8008 Set the line spacing in pixels of the border to be drawn around the box using @var{box}.
8009 The default value of @var{line_spacing} is 0.
8012 Set the width of the border to be drawn around the text using @var{bordercolor}.
8013 The default value of @var{borderw} is 0.
8016 Set the color to be used for drawing border around text. For the syntax of this
8017 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
8019 The default value of @var{bordercolor} is "black".
8022 Select how the @var{text} is expanded. Can be either @code{none},
8023 @code{strftime} (deprecated) or
8024 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
8028 Set a start time for the count. Value is in microseconds. Only applied
8029 in the deprecated strftime expansion mode. To emulate in normal expansion
8030 mode use the @code{pts} function, supplying the start time (in seconds)
8031 as the second argument.
8034 If true, check and fix text coords to avoid clipping.
8037 The color to be used for drawing fonts. For the syntax of this option, check
8038 the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
8040 The default value of @var{fontcolor} is "black".
8042 @item fontcolor_expr
8043 String which is expanded the same way as @var{text} to obtain dynamic
8044 @var{fontcolor} value. By default this option has empty value and is not
8045 processed. When this option is set, it overrides @var{fontcolor} option.
8048 The font family to be used for drawing text. By default Sans.
8051 The font file to be used for drawing text. The path must be included.
8052 This parameter is mandatory if the fontconfig support is disabled.
8055 Draw the text applying alpha blending. The value can
8056 be a number between 0.0 and 1.0.
8057 The expression accepts the same variables @var{x, y} as well.
8058 The default value is 1.
8059 Please see @var{fontcolor_expr}.
8062 The font size to be used for drawing text.
8063 The default value of @var{fontsize} is 16.
8066 If set to 1, attempt to shape the text (for example, reverse the order of
8067 right-to-left text and join Arabic characters) before drawing it.
8068 Otherwise, just draw the text exactly as given.
8069 By default 1 (if supported).
8072 The flags to be used for loading the fonts.
8074 The flags map the corresponding flags supported by libfreetype, and are
8075 a combination of the following values:
8082 @item vertical_layout
8083 @item force_autohint
8086 @item ignore_global_advance_width
8088 @item ignore_transform
8094 Default value is "default".
8096 For more information consult the documentation for the FT_LOAD_*
8100 The color to be used for drawing a shadow behind the drawn text. For the
8101 syntax of this option, check the @ref{color syntax,,"Color" section in the
8102 ffmpeg-utils manual,ffmpeg-utils}.
8104 The default value of @var{shadowcolor} is "black".
8108 The x and y offsets for the text shadow position with respect to the
8109 position of the text. They can be either positive or negative
8110 values. The default value for both is "0".
8113 The starting frame number for the n/frame_num variable. The default value
8117 The size in number of spaces to use for rendering the tab.
8121 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
8122 format. It can be used with or without text parameter. @var{timecode_rate}
8123 option must be specified.
8125 @item timecode_rate, rate, r
8126 Set the timecode frame rate (timecode only). Value will be rounded to nearest
8127 integer. Minimum value is "1".
8128 Drop-frame timecode is supported for frame rates 30 & 60.
8131 If set to 1, the output of the timecode option will wrap around at 24 hours.
8132 Default is 0 (disabled).
8135 The text string to be drawn. The text must be a sequence of UTF-8
8137 This parameter is mandatory if no file is specified with the parameter
8141 A text file containing text to be drawn. The text must be a sequence
8142 of UTF-8 encoded characters.
8144 This parameter is mandatory if no text string is specified with the
8145 parameter @var{text}.
8147 If both @var{text} and @var{textfile} are specified, an error is thrown.
8150 If set to 1, the @var{textfile} will be reloaded before each frame.
8151 Be sure to update it atomically, or it may be read partially, or even fail.
8155 The expressions which specify the offsets where text will be drawn
8156 within the video frame. They are relative to the top/left border of the
8159 The default value of @var{x} and @var{y} is "0".
8161 See below for the list of accepted constants and functions.
8164 The parameters for @var{x} and @var{y} are expressions containing the
8165 following constants and functions:
8169 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
8173 horizontal and vertical chroma subsample values. For example for the
8174 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8177 the height of each text line
8185 @item max_glyph_a, ascent
8186 the maximum distance from the baseline to the highest/upper grid
8187 coordinate used to place a glyph outline point, for all the rendered
8189 It is a positive value, due to the grid's orientation with the Y axis
8192 @item max_glyph_d, descent
8193 the maximum distance from the baseline to the lowest grid coordinate
8194 used to place a glyph outline point, for all the rendered glyphs.
8195 This is a negative value, due to the grid's orientation, with the Y axis
8199 maximum glyph height, that is the maximum height for all the glyphs
8200 contained in the rendered text, it is equivalent to @var{ascent} -
8204 maximum glyph width, that is the maximum width for all the glyphs
8205 contained in the rendered text
8208 the number of input frame, starting from 0
8210 @item rand(min, max)
8211 return a random number included between @var{min} and @var{max}
8214 The input sample aspect ratio.
8217 timestamp expressed in seconds, NAN if the input timestamp is unknown
8220 the height of the rendered text
8223 the width of the rendered text
8227 the x and y offset coordinates where the text is drawn.
8229 These parameters allow the @var{x} and @var{y} expressions to refer
8230 each other, so you can for example specify @code{y=x/dar}.
8233 @anchor{drawtext_expansion}
8234 @subsection Text expansion
8236 If @option{expansion} is set to @code{strftime},
8237 the filter recognizes strftime() sequences in the provided text and
8238 expands them accordingly. Check the documentation of strftime(). This
8239 feature is deprecated.
8241 If @option{expansion} is set to @code{none}, the text is printed verbatim.
8243 If @option{expansion} is set to @code{normal} (which is the default),
8244 the following expansion mechanism is used.
8246 The backslash character @samp{\}, followed by any character, always expands to
8247 the second character.
8249 Sequences of the form @code{%@{...@}} are expanded. The text between the
8250 braces is a function name, possibly followed by arguments separated by ':'.
8251 If the arguments contain special characters or delimiters (':' or '@}'),
8252 they should be escaped.
8254 Note that they probably must also be escaped as the value for the
8255 @option{text} option in the filter argument string and as the filter
8256 argument in the filtergraph description, and possibly also for the shell,
8257 that makes up to four levels of escaping; using a text file avoids these
8260 The following functions are available:
8265 The expression evaluation result.
8267 It must take one argument specifying the expression to be evaluated,
8268 which accepts the same constants and functions as the @var{x} and
8269 @var{y} values. Note that not all constants should be used, for
8270 example the text size is not known when evaluating the expression, so
8271 the constants @var{text_w} and @var{text_h} will have an undefined
8274 @item expr_int_format, eif
8275 Evaluate the expression's value and output as formatted integer.
8277 The first argument is the expression to be evaluated, just as for the @var{expr} function.
8278 The second argument specifies the output format. Allowed values are @samp{x},
8279 @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
8280 @code{printf} function.
8281 The third parameter is optional and sets the number of positions taken by the output.
8282 It can be used to add padding with zeros from the left.
8285 The time at which the filter is running, expressed in UTC.
8286 It can accept an argument: a strftime() format string.
8289 The time at which the filter is running, expressed in the local time zone.
8290 It can accept an argument: a strftime() format string.
8293 Frame metadata. Takes one or two arguments.
8295 The first argument is mandatory and specifies the metadata key.
8297 The second argument is optional and specifies a default value, used when the
8298 metadata key is not found or empty.
8301 The frame number, starting from 0.
8304 A 1 character description of the current picture type.
8307 The timestamp of the current frame.
8308 It can take up to three arguments.
8310 The first argument is the format of the timestamp; it defaults to @code{flt}
8311 for seconds as a decimal number with microsecond accuracy; @code{hms} stands
8312 for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
8313 @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
8314 @code{localtime} stands for the timestamp of the frame formatted as
8315 local time zone time.
8317 The second argument is an offset added to the timestamp.
8319 If the format is set to @code{hms}, a third argument @code{24HH} may be
8320 supplied to present the hour part of the formatted timestamp in 24h format
8323 If the format is set to @code{localtime} or @code{gmtime},
8324 a third argument may be supplied: a strftime() format string.
8325 By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
8328 @subsection Examples
8332 Draw "Test Text" with font FreeSerif, using the default values for the
8333 optional parameters.
8336 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
8340 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
8341 and y=50 (counting from the top-left corner of the screen), text is
8342 yellow with a red box around it. Both the text and the box have an
8346 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
8347 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
8350 Note that the double quotes are not necessary if spaces are not used
8351 within the parameter list.
8354 Show the text at the center of the video frame:
8356 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
8360 Show the text at a random position, switching to a new position every 30 seconds:
8362 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)"
8366 Show a text line sliding from right to left in the last row of the video
8367 frame. The file @file{LONG_LINE} is assumed to contain a single line
8370 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
8374 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
8376 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
8380 Draw a single green letter "g", at the center of the input video.
8381 The glyph baseline is placed at half screen height.
8383 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
8387 Show text for 1 second every 3 seconds:
8389 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
8393 Use fontconfig to set the font. Note that the colons need to be escaped.
8395 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
8399 Print the date of a real-time encoding (see strftime(3)):
8401 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
8405 Show text fading in and out (appearing/disappearing):
8408 DS=1.0 # display start
8409 DE=10.0 # display end
8410 FID=1.5 # fade in duration
8411 FOD=5 # fade out duration
8412 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 @}"
8416 Horizontally align multiple separate texts. Note that @option{max_glyph_a}
8417 and the @option{fontsize} value are included in the @option{y} offset.
8419 drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
8420 drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
8425 For more information about libfreetype, check:
8426 @url{http://www.freetype.org/}.
8428 For more information about fontconfig, check:
8429 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
8431 For more information about libfribidi, check:
8432 @url{http://fribidi.org/}.
8436 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
8438 The filter accepts the following options:
8443 Set low and high threshold values used by the Canny thresholding
8446 The high threshold selects the "strong" edge pixels, which are then
8447 connected through 8-connectivity with the "weak" edge pixels selected
8448 by the low threshold.
8450 @var{low} and @var{high} threshold values must be chosen in the range
8451 [0,1], and @var{low} should be lesser or equal to @var{high}.
8453 Default value for @var{low} is @code{20/255}, and default value for @var{high}
8457 Define the drawing mode.
8461 Draw white/gray wires on black background.
8464 Mix the colors to create a paint/cartoon effect.
8467 Apply Canny edge detector on all selected planes.
8469 Default value is @var{wires}.
8472 Select planes for filtering. By default all available planes are filtered.
8475 @subsection Examples
8479 Standard edge detection with custom values for the hysteresis thresholding:
8481 edgedetect=low=0.1:high=0.4
8485 Painting effect without thresholding:
8487 edgedetect=mode=colormix:high=0
8492 Set brightness, contrast, saturation and approximate gamma adjustment.
8494 The filter accepts the following options:
8498 Set the contrast expression. The value must be a float value in range
8499 @code{-2.0} to @code{2.0}. The default value is "1".
8502 Set the brightness expression. The value must be a float value in
8503 range @code{-1.0} to @code{1.0}. The default value is "0".
8506 Set the saturation expression. The value must be a float in
8507 range @code{0.0} to @code{3.0}. The default value is "1".
8510 Set the gamma expression. The value must be a float in range
8511 @code{0.1} to @code{10.0}. The default value is "1".
8514 Set the gamma expression for red. The value must be a float in
8515 range @code{0.1} to @code{10.0}. The default value is "1".
8518 Set the gamma expression for green. The value must be a float in range
8519 @code{0.1} to @code{10.0}. The default value is "1".
8522 Set the gamma expression for blue. The value must be a float in range
8523 @code{0.1} to @code{10.0}. The default value is "1".
8526 Set the gamma weight expression. It can be used to reduce the effect
8527 of a high gamma value on bright image areas, e.g. keep them from
8528 getting overamplified and just plain white. The value must be a float
8529 in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
8530 gamma correction all the way down while @code{1.0} leaves it at its
8531 full strength. Default is "1".
8534 Set when the expressions for brightness, contrast, saturation and
8535 gamma expressions are evaluated.
8537 It accepts the following values:
8540 only evaluate expressions once during the filter initialization or
8541 when a command is processed
8544 evaluate expressions for each incoming frame
8547 Default value is @samp{init}.
8550 The expressions accept the following parameters:
8553 frame count of the input frame starting from 0
8556 byte position of the corresponding packet in the input file, NAN if
8560 frame rate of the input video, NAN if the input frame rate is unknown
8563 timestamp expressed in seconds, NAN if the input timestamp is unknown
8566 @subsection Commands
8567 The filter supports the following commands:
8571 Set the contrast expression.
8574 Set the brightness expression.
8577 Set the saturation expression.
8580 Set the gamma expression.
8583 Set the gamma_r expression.
8586 Set gamma_g expression.
8589 Set gamma_b expression.
8592 Set gamma_weight expression.
8594 The command accepts the same syntax of the corresponding option.
8596 If the specified expression is not valid, it is kept at its current
8603 Apply erosion effect to the video.
8605 This filter replaces the pixel by the local(3x3) minimum.
8607 It accepts the following options:
8614 Limit the maximum change for each plane, default is 65535.
8615 If 0, plane will remain unchanged.
8618 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
8621 Flags to local 3x3 coordinates maps like this:
8628 @section extractplanes
8630 Extract color channel components from input video stream into
8631 separate grayscale video streams.
8633 The filter accepts the following option:
8637 Set plane(s) to extract.
8639 Available values for planes are:
8650 Choosing planes not available in the input will result in an error.
8651 That means you cannot select @code{r}, @code{g}, @code{b} planes
8652 with @code{y}, @code{u}, @code{v} planes at same time.
8655 @subsection Examples
8659 Extract luma, u and v color channel component from input video frame
8660 into 3 grayscale outputs:
8662 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
8668 Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
8670 For each input image, the filter will compute the optimal mapping from
8671 the input to the output given the codebook length, that is the number
8672 of distinct output colors.
8674 This filter accepts the following options.
8677 @item codebook_length, l
8678 Set codebook length. The value must be a positive integer, and
8679 represents the number of distinct output colors. Default value is 256.
8682 Set the maximum number of iterations to apply for computing the optimal
8683 mapping. The higher the value the better the result and the higher the
8684 computation time. Default value is 1.
8687 Set a random seed, must be an integer included between 0 and
8688 UINT32_MAX. If not specified, or if explicitly set to -1, the filter
8689 will try to use a good random seed on a best effort basis.
8692 Set pal8 output pixel format. This option does not work with codebook
8693 length greater than 256.
8698 Measure graylevel entropy in histogram of color channels of video frames.
8700 It accepts the following parameters:
8704 Can be either @var{normal} or @var{diff}. Default is @var{normal}.
8706 @var{diff} mode measures entropy of histogram delta values, absolute differences
8707 between neighbour histogram values.
8712 Apply a fade-in/out effect to the input video.
8714 It accepts the following parameters:
8718 The effect type can be either "in" for a fade-in, or "out" for a fade-out
8720 Default is @code{in}.
8722 @item start_frame, s
8723 Specify the number of the frame to start applying the fade
8724 effect at. Default is 0.
8727 The number of frames that the fade effect lasts. At the end of the
8728 fade-in effect, the output video will have the same intensity as the input video.
8729 At the end of the fade-out transition, the output video will be filled with the
8730 selected @option{color}.
8734 If set to 1, fade only alpha channel, if one exists on the input.
8737 @item start_time, st
8738 Specify the timestamp (in seconds) of the frame to start to apply the fade
8739 effect. If both start_frame and start_time are specified, the fade will start at
8740 whichever comes last. Default is 0.
8743 The number of seconds for which the fade effect has to last. At the end of the
8744 fade-in effect the output video will have the same intensity as the input video,
8745 at the end of the fade-out transition the output video will be filled with the
8746 selected @option{color}.
8747 If both duration and nb_frames are specified, duration is used. Default is 0
8748 (nb_frames is used by default).
8751 Specify the color of the fade. Default is "black".
8754 @subsection Examples
8758 Fade in the first 30 frames of video:
8763 The command above is equivalent to:
8769 Fade out the last 45 frames of a 200-frame video:
8772 fade=type=out:start_frame=155:nb_frames=45
8776 Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
8778 fade=in:0:25, fade=out:975:25
8782 Make the first 5 frames yellow, then fade in from frame 5-24:
8784 fade=in:5:20:color=yellow
8788 Fade in alpha over first 25 frames of video:
8790 fade=in:0:25:alpha=1
8794 Make the first 5.5 seconds black, then fade in for 0.5 seconds:
8796 fade=t=in:st=5.5:d=0.5
8802 Apply arbitrary expressions to samples in frequency domain
8806 Adjust the dc value (gain) of the luma plane of the image. The filter
8807 accepts an integer value in range @code{0} to @code{1000}. The default
8808 value is set to @code{0}.
8811 Adjust the dc value (gain) of the 1st chroma plane of the image. The
8812 filter accepts an integer value in range @code{0} to @code{1000}. The
8813 default value is set to @code{0}.
8816 Adjust the dc value (gain) of the 2nd chroma plane of the image. The
8817 filter accepts an integer value in range @code{0} to @code{1000}. The
8818 default value is set to @code{0}.
8821 Set the frequency domain weight expression for the luma plane.
8824 Set the frequency domain weight expression for the 1st chroma plane.
8827 Set the frequency domain weight expression for the 2nd chroma plane.
8830 Set when the expressions are evaluated.
8832 It accepts the following values:
8835 Only evaluate expressions once during the filter initialization.
8838 Evaluate expressions for each incoming frame.
8841 Default value is @samp{init}.
8843 The filter accepts the following variables:
8846 The coordinates of the current sample.
8850 The width and height of the image.
8853 The number of input frame, starting from 0.
8856 @subsection Examples
8862 fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
8868 fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
8874 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
8880 fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
8886 Denoise frames using 3D FFT (frequency domain filtering).
8888 The filter accepts the following options:
8892 Set the noise sigma constant. This sets denoising strength.
8893 Default value is 1. Allowed range is from 0 to 30.
8894 Using very high sigma with low overlap may give blocking artifacts.
8897 Set amount of denoising. By default all detected noise is reduced.
8898 Default value is 1. Allowed range is from 0 to 1.
8901 Set size of block, Default is 4, can be 3, 4, 5 or 6.
8902 Actual size of block in pixels is 2 to power of @var{block}, so by default
8903 block size in pixels is 2^4 which is 16.
8906 Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8.
8909 Set number of previous frames to use for denoising. By default is set to 0.
8912 Set number of next frames to to use for denoising. By default is set to 0.
8915 Set planes which will be filtered, by default are all available filtered
8921 Extract a single field from an interlaced image using stride
8922 arithmetic to avoid wasting CPU time. The output frames are marked as
8925 The filter accepts the following options:
8929 Specify whether to extract the top (if the value is @code{0} or
8930 @code{top}) or the bottom field (if the value is @code{1} or
8936 Create new frames by copying the top and bottom fields from surrounding frames
8937 supplied as numbers by the hint file.
8941 Set file containing hints: absolute/relative frame numbers.
8943 There must be one line for each frame in a clip. Each line must contain two
8944 numbers separated by the comma, optionally followed by @code{-} or @code{+}.
8945 Numbers supplied on each line of file can not be out of [N-1,N+1] where N
8946 is current frame number for @code{absolute} mode or out of [-1, 1] range
8947 for @code{relative} mode. First number tells from which frame to pick up top
8948 field and second number tells from which frame to pick up bottom field.
8950 If optionally followed by @code{+} output frame will be marked as interlaced,
8951 else if followed by @code{-} output frame will be marked as progressive, else
8952 it will be marked same as input frame.
8953 If line starts with @code{#} or @code{;} that line is skipped.
8956 Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
8959 Example of first several lines of @code{hint} file for @code{relative} mode:
8962 1,0 - # second frame, use third's frame top field and second's frame bottom field
8963 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
8980 Field matching filter for inverse telecine. It is meant to reconstruct the
8981 progressive frames from a telecined stream. The filter does not drop duplicated
8982 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
8983 followed by a decimation filter such as @ref{decimate} in the filtergraph.
8985 The separation of the field matching and the decimation is notably motivated by
8986 the possibility of inserting a de-interlacing filter fallback between the two.
8987 If the source has mixed telecined and real interlaced content,
8988 @code{fieldmatch} will not be able to match fields for the interlaced parts.
8989 But these remaining combed frames will be marked as interlaced, and thus can be
8990 de-interlaced by a later filter such as @ref{yadif} before decimation.
8992 In addition to the various configuration options, @code{fieldmatch} can take an
8993 optional second stream, activated through the @option{ppsrc} option. If
8994 enabled, the frames reconstruction will be based on the fields and frames from
8995 this second stream. This allows the first input to be pre-processed in order to
8996 help the various algorithms of the filter, while keeping the output lossless
8997 (assuming the fields are matched properly). Typically, a field-aware denoiser,
8998 or brightness/contrast adjustments can help.
9000 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
9001 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
9002 which @code{fieldmatch} is based on. While the semantic and usage are very
9003 close, some behaviour and options names can differ.
9005 The @ref{decimate} filter currently only works for constant frame rate input.
9006 If your input has mixed telecined (30fps) and progressive content with a lower
9007 framerate like 24fps use the following filterchain to produce the necessary cfr
9008 stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
9010 The filter accepts the following options:
9014 Specify the assumed field order of the input stream. Available values are:
9018 Auto detect parity (use FFmpeg's internal parity value).
9020 Assume bottom field first.
9022 Assume top field first.
9025 Note that it is sometimes recommended not to trust the parity announced by the
9028 Default value is @var{auto}.
9031 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
9032 sense that it won't risk creating jerkiness due to duplicate frames when
9033 possible, but if there are bad edits or blended fields it will end up
9034 outputting combed frames when a good match might actually exist. On the other
9035 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
9036 but will almost always find a good frame if there is one. The other values are
9037 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
9038 jerkiness and creating duplicate frames versus finding good matches in sections
9039 with bad edits, orphaned fields, blended fields, etc.
9041 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
9043 Available values are:
9047 2-way matching (p/c)
9049 2-way matching, and trying 3rd match if still combed (p/c + n)
9051 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
9053 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
9054 still combed (p/c + n + u/b)
9056 3-way matching (p/c/n)
9058 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
9059 detected as combed (p/c/n + u/b)
9062 The parenthesis at the end indicate the matches that would be used for that
9063 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
9066 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
9069 Default value is @var{pc_n}.
9072 Mark the main input stream as a pre-processed input, and enable the secondary
9073 input stream as the clean source to pick the fields from. See the filter
9074 introduction for more details. It is similar to the @option{clip2} feature from
9077 Default value is @code{0} (disabled).
9080 Set the field to match from. It is recommended to set this to the same value as
9081 @option{order} unless you experience matching failures with that setting. In
9082 certain circumstances changing the field that is used to match from can have a
9083 large impact on matching performance. Available values are:
9087 Automatic (same value as @option{order}).
9089 Match from the bottom field.
9091 Match from the top field.
9094 Default value is @var{auto}.
9097 Set whether or not chroma is included during the match comparisons. In most
9098 cases it is recommended to leave this enabled. You should set this to @code{0}
9099 only if your clip has bad chroma problems such as heavy rainbowing or other
9100 artifacts. Setting this to @code{0} could also be used to speed things up at
9101 the cost of some accuracy.
9103 Default value is @code{1}.
9107 These define an exclusion band which excludes the lines between @option{y0} and
9108 @option{y1} from being included in the field matching decision. An exclusion
9109 band can be used to ignore subtitles, a logo, or other things that may
9110 interfere with the matching. @option{y0} sets the starting scan line and
9111 @option{y1} sets the ending line; all lines in between @option{y0} and
9112 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
9113 @option{y0} and @option{y1} to the same value will disable the feature.
9114 @option{y0} and @option{y1} defaults to @code{0}.
9117 Set the scene change detection threshold as a percentage of maximum change on
9118 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
9119 detection is only relevant in case @option{combmatch}=@var{sc}. The range for
9120 @option{scthresh} is @code{[0.0, 100.0]}.
9122 Default value is @code{12.0}.
9125 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
9126 account the combed scores of matches when deciding what match to use as the
9127 final match. Available values are:
9131 No final matching based on combed scores.
9133 Combed scores are only used when a scene change is detected.
9135 Use combed scores all the time.
9138 Default is @var{sc}.
9141 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
9142 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
9143 Available values are:
9147 No forced calculation.
9149 Force p/c/n calculations.
9151 Force p/c/n/u/b calculations.
9154 Default value is @var{none}.
9157 This is the area combing threshold used for combed frame detection. This
9158 essentially controls how "strong" or "visible" combing must be to be detected.
9159 Larger values mean combing must be more visible and smaller values mean combing
9160 can be less visible or strong and still be detected. Valid settings are from
9161 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
9162 be detected as combed). This is basically a pixel difference value. A good
9163 range is @code{[8, 12]}.
9165 Default value is @code{9}.
9168 Sets whether or not chroma is considered in the combed frame decision. Only
9169 disable this if your source has chroma problems (rainbowing, etc.) that are
9170 causing problems for the combed frame detection with chroma enabled. Actually,
9171 using @option{chroma}=@var{0} is usually more reliable, except for the case
9172 where there is chroma only combing in the source.
9174 Default value is @code{0}.
9178 Respectively set the x-axis and y-axis size of the window used during combed
9179 frame detection. This has to do with the size of the area in which
9180 @option{combpel} pixels are required to be detected as combed for a frame to be
9181 declared combed. See the @option{combpel} parameter description for more info.
9182 Possible values are any number that is a power of 2 starting at 4 and going up
9185 Default value is @code{16}.
9188 The number of combed pixels inside any of the @option{blocky} by
9189 @option{blockx} size blocks on the frame for the frame to be detected as
9190 combed. While @option{cthresh} controls how "visible" the combing must be, this
9191 setting controls "how much" combing there must be in any localized area (a
9192 window defined by the @option{blockx} and @option{blocky} settings) on the
9193 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
9194 which point no frames will ever be detected as combed). This setting is known
9195 as @option{MI} in TFM/VFM vocabulary.
9197 Default value is @code{80}.
9200 @anchor{p/c/n/u/b meaning}
9201 @subsection p/c/n/u/b meaning
9203 @subsubsection p/c/n
9205 We assume the following telecined stream:
9208 Top fields: 1 2 2 3 4
9209 Bottom fields: 1 2 3 4 4
9212 The numbers correspond to the progressive frame the fields relate to. Here, the
9213 first two frames are progressive, the 3rd and 4th are combed, and so on.
9215 When @code{fieldmatch} is configured to run a matching from bottom
9216 (@option{field}=@var{bottom}) this is how this input stream get transformed:
9221 B 1 2 3 4 4 <-- matching reference
9230 As a result of the field matching, we can see that some frames get duplicated.
9231 To perform a complete inverse telecine, you need to rely on a decimation filter
9232 after this operation. See for instance the @ref{decimate} filter.
9234 The same operation now matching from top fields (@option{field}=@var{top})
9239 T 1 2 2 3 4 <-- matching reference
9249 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
9250 basically, they refer to the frame and field of the opposite parity:
9253 @item @var{p} matches the field of the opposite parity in the previous frame
9254 @item @var{c} matches the field of the opposite parity in the current frame
9255 @item @var{n} matches the field of the opposite parity in the next frame
9260 The @var{u} and @var{b} matching are a bit special in the sense that they match
9261 from the opposite parity flag. In the following examples, we assume that we are
9262 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
9263 'x' is placed above and below each matched fields.
9265 With bottom matching (@option{field}=@var{bottom}):
9270 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
9271 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
9279 With top matching (@option{field}=@var{top}):
9284 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
9285 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
9293 @subsection Examples
9295 Simple IVTC of a top field first telecined stream:
9297 fieldmatch=order=tff:combmatch=none, decimate
9300 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
9302 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
9307 Transform the field order of the input video.
9309 It accepts the following parameters:
9314 The output field order. Valid values are @var{tff} for top field first or @var{bff}
9315 for bottom field first.
9318 The default value is @samp{tff}.
9320 The transformation is done by shifting the picture content up or down
9321 by one line, and filling the remaining line with appropriate picture content.
9322 This method is consistent with most broadcast field order converters.
9324 If the input video is not flagged as being interlaced, or it is already
9325 flagged as being of the required output field order, then this filter does
9326 not alter the incoming video.
9328 It is very useful when converting to or from PAL DV material,
9329 which is bottom field first.
9333 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
9336 @section fifo, afifo
9338 Buffer input images and send them when they are requested.
9340 It is mainly useful when auto-inserted by the libavfilter
9343 It does not take parameters.
9345 @section fillborders
9347 Fill borders of the input video, without changing video stream dimensions.
9348 Sometimes video can have garbage at the four edges and you may not want to
9349 crop video input to keep size multiple of some number.
9351 This filter accepts the following options:
9355 Number of pixels to fill from left border.
9358 Number of pixels to fill from right border.
9361 Number of pixels to fill from top border.
9364 Number of pixels to fill from bottom border.
9369 It accepts the following values:
9372 fill pixels using outermost pixels
9375 fill pixels using mirroring
9378 fill pixels with constant value
9381 Default is @var{smear}.
9384 Set color for pixels in fixed mode. Default is @var{black}.
9389 Find a rectangular object
9391 It accepts the following options:
9395 Filepath of the object image, needs to be in gray8.
9398 Detection threshold, default is 0.5.
9401 Number of mipmaps, default is 3.
9403 @item xmin, ymin, xmax, ymax
9404 Specifies the rectangle in which to search.
9407 @subsection Examples
9411 Generate a representative palette of a given video using @command{ffmpeg}:
9413 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
9419 Cover a rectangular object
9421 It accepts the following options:
9425 Filepath of the optional cover image, needs to be in yuv420.
9430 It accepts the following values:
9433 cover it by the supplied image
9435 cover it by interpolating the surrounding pixels
9438 Default value is @var{blur}.
9441 @subsection Examples
9445 Generate a representative palette of a given video using @command{ffmpeg}:
9447 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
9453 Flood area with values of same pixel components with another values.
9455 It accepts the following options:
9458 Set pixel x coordinate.
9461 Set pixel y coordinate.
9464 Set source #0 component value.
9467 Set source #1 component value.
9470 Set source #2 component value.
9473 Set source #3 component value.
9476 Set destination #0 component value.
9479 Set destination #1 component value.
9482 Set destination #2 component value.
9485 Set destination #3 component value.
9491 Convert the input video to one of the specified pixel formats.
9492 Libavfilter will try to pick one that is suitable as input to
9495 It accepts the following parameters:
9499 A '|'-separated list of pixel format names, such as
9500 "pix_fmts=yuv420p|monow|rgb24".
9504 @subsection Examples
9508 Convert the input video to the @var{yuv420p} format
9510 format=pix_fmts=yuv420p
9513 Convert the input video to any of the formats in the list
9515 format=pix_fmts=yuv420p|yuv444p|yuv410p
9522 Convert the video to specified constant frame rate by duplicating or dropping
9523 frames as necessary.
9525 It accepts the following parameters:
9529 The desired output frame rate. The default is @code{25}.
9532 Assume the first PTS should be the given value, in seconds. This allows for
9533 padding/trimming at the start of stream. By default, no assumption is made
9534 about the first frame's expected PTS, so no padding or trimming is done.
9535 For example, this could be set to 0 to pad the beginning with duplicates of
9536 the first frame if a video stream starts after the audio stream or to trim any
9537 frames with a negative PTS.
9540 Timestamp (PTS) rounding method.
9542 Possible values are:
9549 round towards -infinity
9551 round towards +infinity
9555 The default is @code{near}.
9558 Action performed when reading the last frame.
9560 Possible values are:
9563 Use same timestamp rounding method as used for other frames.
9565 Pass through last frame if input duration has not been reached yet.
9567 The default is @code{round}.
9571 Alternatively, the options can be specified as a flat string:
9572 @var{fps}[:@var{start_time}[:@var{round}]].
9574 See also the @ref{setpts} filter.
9576 @subsection Examples
9580 A typical usage in order to set the fps to 25:
9586 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
9588 fps=fps=film:round=near
9594 Pack two different video streams into a stereoscopic video, setting proper
9595 metadata on supported codecs. The two views should have the same size and
9596 framerate and processing will stop when the shorter video ends. Please note
9597 that you may conveniently adjust view properties with the @ref{scale} and
9600 It accepts the following parameters:
9604 The desired packing format. Supported values are:
9609 The views are next to each other (default).
9612 The views are on top of each other.
9615 The views are packed by line.
9618 The views are packed by column.
9621 The views are temporally interleaved.
9630 # Convert left and right views into a frame-sequential video
9631 ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
9633 # Convert views into a side-by-side video with the same output resolution as the input
9634 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
9639 Change the frame rate by interpolating new video output frames from the source
9642 This filter is not designed to function correctly with interlaced media. If
9643 you wish to change the frame rate of interlaced media then you are required
9644 to deinterlace before this filter and re-interlace after this filter.
9646 A description of the accepted options follows.
9650 Specify the output frames per second. This option can also be specified
9651 as a value alone. The default is @code{50}.
9654 Specify the start of a range where the output frame will be created as a
9655 linear interpolation of two frames. The range is [@code{0}-@code{255}],
9656 the default is @code{15}.
9659 Specify the end of a range where the output frame will be created as a
9660 linear interpolation of two frames. The range is [@code{0}-@code{255}],
9661 the default is @code{240}.
9664 Specify the level at which a scene change is detected as a value between
9665 0 and 100 to indicate a new scene; a low value reflects a low
9666 probability for the current frame to introduce a new scene, while a higher
9667 value means the current frame is more likely to be one.
9668 The default is @code{8.2}.
9671 Specify flags influencing the filter process.
9673 Available value for @var{flags} is:
9676 @item scene_change_detect, scd
9677 Enable scene change detection using the value of the option @var{scene}.
9678 This flag is enabled by default.
9684 Select one frame every N-th frame.
9686 This filter accepts the following option:
9689 Select frame after every @code{step} frames.
9690 Allowed values are positive integers higher than 0. Default value is @code{1}.
9696 Apply a frei0r effect to the input video.
9698 To enable the compilation of this filter, you need to install the frei0r
9699 header and configure FFmpeg with @code{--enable-frei0r}.
9701 It accepts the following parameters:
9706 The name of the frei0r effect to load. If the environment variable
9707 @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
9708 directories specified by the colon-separated list in @env{FREI0R_PATH}.
9709 Otherwise, the standard frei0r paths are searched, in this order:
9710 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
9711 @file{/usr/lib/frei0r-1/}.
9714 A '|'-separated list of parameters to pass to the frei0r effect.
9718 A frei0r effect parameter can be a boolean (its value is either
9719 "y" or "n"), a double, a color (specified as
9720 @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
9721 numbers between 0.0 and 1.0, inclusive) or a color description as specified in the
9722 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils},
9723 a position (specified as @var{X}/@var{Y}, where
9724 @var{X} and @var{Y} are floating point numbers) and/or a string.
9726 The number and types of parameters depend on the loaded effect. If an
9727 effect parameter is not specified, the default value is set.
9729 @subsection Examples
9733 Apply the distort0r effect, setting the first two double parameters:
9735 frei0r=filter_name=distort0r:filter_params=0.5|0.01
9739 Apply the colordistance effect, taking a color as the first parameter:
9741 frei0r=colordistance:0.2/0.3/0.4
9742 frei0r=colordistance:violet
9743 frei0r=colordistance:0x112233
9747 Apply the perspective effect, specifying the top left and top right image
9750 frei0r=perspective:0.2/0.2|0.8/0.2
9754 For more information, see
9755 @url{http://frei0r.dyne.org}
9759 Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
9761 It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
9762 processing filter, one of them is performed once per block, not per pixel.
9763 This allows for much higher speed.
9765 The filter accepts the following options:
9769 Set quality. This option defines the number of levels for averaging. It accepts
9770 an integer in the range 4-5. Default value is @code{4}.
9773 Force a constant quantization parameter. It accepts an integer in range 0-63.
9774 If not set, the filter will use the QP from the video stream (if available).
9777 Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
9778 more details but also more artifacts, while higher values make the image smoother
9779 but also blurrier. Default value is @code{0} − PSNR optimal.
9782 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
9783 option may cause flicker since the B-Frames have often larger QP. Default is
9784 @code{0} (not enabled).
9790 Apply Gaussian blur filter.
9792 The filter accepts the following options:
9796 Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
9799 Set number of steps for Gaussian approximation. Defauls is @code{1}.
9802 Set which planes to filter. By default all planes are filtered.
9805 Set vertical sigma, if negative it will be same as @code{sigma}.
9806 Default is @code{-1}.
9811 The filter accepts the following options:
9815 Set the luminance expression.
9817 Set the chrominance blue expression.
9819 Set the chrominance red expression.
9821 Set the alpha expression.
9823 Set the red expression.
9825 Set the green expression.
9827 Set the blue expression.
9830 The colorspace is selected according to the specified options. If one
9831 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
9832 options is specified, the filter will automatically select a YCbCr
9833 colorspace. If one of the @option{red_expr}, @option{green_expr}, or
9834 @option{blue_expr} options is specified, it will select an RGB
9837 If one of the chrominance expression is not defined, it falls back on the other
9838 one. If no alpha expression is specified it will evaluate to opaque value.
9839 If none of chrominance expressions are specified, they will evaluate
9840 to the luminance expression.
9842 The expressions can use the following variables and functions:
9846 The sequential number of the filtered frame, starting from @code{0}.
9850 The coordinates of the current sample.
9854 The width and height of the image.
9858 Width and height scale depending on the currently filtered plane. It is the
9859 ratio between the corresponding luma plane number of pixels and the current
9860 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
9861 @code{0.5,0.5} for chroma planes.
9864 Time of the current frame, expressed in seconds.
9867 Return the value of the pixel at location (@var{x},@var{y}) of the current
9871 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
9875 Return the value of the pixel at location (@var{x},@var{y}) of the
9876 blue-difference chroma plane. Return 0 if there is no such plane.
9879 Return the value of the pixel at location (@var{x},@var{y}) of the
9880 red-difference chroma plane. Return 0 if there is no such plane.
9885 Return the value of the pixel at location (@var{x},@var{y}) of the
9886 red/green/blue component. Return 0 if there is no such component.
9889 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
9890 plane. Return 0 if there is no such plane.
9893 For functions, if @var{x} and @var{y} are outside the area, the value will be
9894 automatically clipped to the closer edge.
9896 @subsection Examples
9900 Flip the image horizontally:
9906 Generate a bidimensional sine wave, with angle @code{PI/3} and a
9907 wavelength of 100 pixels:
9909 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
9913 Generate a fancy enigmatic moving light:
9915 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
9919 Generate a quick emboss effect:
9921 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
9925 Modify RGB components depending on pixel position:
9927 geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
9931 Create a radial gradient that is the same size as the input (also see
9932 the @ref{vignette} filter):
9934 geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
9940 Fix the banding artifacts that are sometimes introduced into nearly flat
9941 regions by truncation to 8-bit color depth.
9942 Interpolate the gradients that should go where the bands are, and
9945 It is designed for playback only. Do not use it prior to
9946 lossy compression, because compression tends to lose the dither and
9947 bring back the bands.
9949 It accepts the following parameters:
9954 The maximum amount by which the filter will change any one pixel. This is also
9955 the threshold for detecting nearly flat regions. Acceptable values range from
9956 .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
9960 The neighborhood to fit the gradient to. A larger radius makes for smoother
9961 gradients, but also prevents the filter from modifying the pixels near detailed
9962 regions. Acceptable values are 8-32; the default value is 16. Out-of-range
9963 values will be clipped to the valid range.
9967 Alternatively, the options can be specified as a flat string:
9968 @var{strength}[:@var{radius}]
9970 @subsection Examples
9974 Apply the filter with a @code{3.5} strength and radius of @code{8}:
9980 Specify radius, omitting the strength (which will fall-back to the default
9989 A color constancy variation filter which estimates scene illumination via grey edge algorithm
9990 and corrects the scene colors accordingly.
9992 See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf}
9994 The filter accepts the following options:
9998 The order of differentiation to be applied on the scene. Must be chosen in the range
9999 [0,2] and default value is 1.
10002 The Minkowski parameter to be used for calculating the Minkowski distance. Must
10003 be chosen in the range [0,20] and default value is 1. Set to 0 for getting
10004 max value instead of calculating Minkowski distance.
10007 The standard deviation of Gaussian blur to be applied on the scene. Must be
10008 chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) )
10009 can't be euqal to 0 if @var{difford} is greater than 0.
10012 @subsection Examples
10018 greyedge=difford=1:minknorm=5:sigma=2
10024 greyedge=difford=1:minknorm=0:sigma=2
10032 Apply a Hald CLUT to a video stream.
10034 First input is the video stream to process, and second one is the Hald CLUT.
10035 The Hald CLUT input can be a simple picture or a complete video stream.
10037 The filter accepts the following options:
10041 Force termination when the shortest input terminates. Default is @code{0}.
10043 Continue applying the last CLUT after the end of the stream. A value of
10044 @code{0} disable the filter after the last frame of the CLUT is reached.
10045 Default is @code{1}.
10048 @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
10049 filters share the same internals).
10051 More information about the Hald CLUT can be found on Eskil Steenberg's website
10052 (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
10054 @subsection Workflow examples
10056 @subsubsection Hald CLUT video stream
10058 Generate an identity Hald CLUT stream altered with various effects:
10060 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
10063 Note: make sure you use a lossless codec.
10065 Then use it with @code{haldclut} to apply it on some random stream:
10067 ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
10070 The Hald CLUT will be applied to the 10 first seconds (duration of
10071 @file{clut.nut}), then the latest picture of that CLUT stream will be applied
10072 to the remaining frames of the @code{mandelbrot} stream.
10074 @subsubsection Hald CLUT with preview
10076 A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
10077 @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
10078 biggest possible square starting at the top left of the picture. The remaining
10079 padding pixels (bottom or right) will be ignored. This area can be used to add
10080 a preview of the Hald CLUT.
10082 Typically, the following generated Hald CLUT will be supported by the
10083 @code{haldclut} filter:
10086 ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
10087 pad=iw+320 [padded_clut];
10088 smptebars=s=320x256, split [a][b];
10089 [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
10090 [main][b] overlay=W-320" -frames:v 1 clut.png
10093 It contains the original and a preview of the effect of the CLUT: SMPTE color
10094 bars are displayed on the right-top, and below the same color bars processed by
10097 Then, the effect of this Hald CLUT can be visualized with:
10099 ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
10104 Flip the input video horizontally.
10106 For example, to horizontally flip the input video with @command{ffmpeg}:
10108 ffmpeg -i in.avi -vf "hflip" out.avi
10112 This filter applies a global color histogram equalization on a
10115 It can be used to correct video that has a compressed range of pixel
10116 intensities. The filter redistributes the pixel intensities to
10117 equalize their distribution across the intensity range. It may be
10118 viewed as an "automatically adjusting contrast filter". This filter is
10119 useful only for correcting degraded or poorly captured source
10122 The filter accepts the following options:
10126 Determine the amount of equalization to be applied. As the strength
10127 is reduced, the distribution of pixel intensities more-and-more
10128 approaches that of the input frame. The value must be a float number
10129 in the range [0,1] and defaults to 0.200.
10132 Set the maximum intensity that can generated and scale the output
10133 values appropriately. The strength should be set as desired and then
10134 the intensity can be limited if needed to avoid washing-out. The value
10135 must be a float number in the range [0,1] and defaults to 0.210.
10138 Set the antibanding level. If enabled the filter will randomly vary
10139 the luminance of output pixels by a small amount to avoid banding of
10140 the histogram. Possible values are @code{none}, @code{weak} or
10141 @code{strong}. It defaults to @code{none}.
10146 Compute and draw a color distribution histogram for the input video.
10148 The computed histogram is a representation of the color component
10149 distribution in an image.
10151 Standard histogram displays the color components distribution in an image.
10152 Displays color graph for each color component. Shows distribution of
10153 the Y, U, V, A or R, G, B components, depending on input format, in the
10154 current frame. Below each graph a color component scale meter is shown.
10156 The filter accepts the following options:
10160 Set height of level. Default value is @code{200}.
10161 Allowed range is [50, 2048].
10164 Set height of color scale. Default value is @code{12}.
10165 Allowed range is [0, 40].
10169 It accepts the following values:
10172 Per color component graphs are placed below each other.
10175 Per color component graphs are placed side by side.
10178 Presents information identical to that in the @code{parade}, except
10179 that the graphs representing color components are superimposed directly
10182 Default is @code{stack}.
10185 Set mode. Can be either @code{linear}, or @code{logarithmic}.
10186 Default is @code{linear}.
10189 Set what color components to display.
10190 Default is @code{7}.
10193 Set foreground opacity. Default is @code{0.7}.
10196 Set background opacity. Default is @code{0.5}.
10199 @subsection Examples
10204 Calculate and draw histogram:
10206 ffplay -i input -vf histogram
10214 This is a high precision/quality 3d denoise filter. It aims to reduce
10215 image noise, producing smooth images and making still images really
10216 still. It should enhance compressibility.
10218 It accepts the following optional parameters:
10222 A non-negative floating point number which specifies spatial luma strength.
10223 It defaults to 4.0.
10225 @item chroma_spatial
10226 A non-negative floating point number which specifies spatial chroma strength.
10227 It defaults to 3.0*@var{luma_spatial}/4.0.
10230 A floating point number which specifies luma temporal strength. It defaults to
10231 6.0*@var{luma_spatial}/4.0.
10234 A floating point number which specifies chroma temporal strength. It defaults to
10235 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
10238 @section hwdownload
10240 Download hardware frames to system memory.
10242 The input must be in hardware frames, and the output a non-hardware format.
10243 Not all formats will be supported on the output - it may be necessary to insert
10244 an additional @option{format} filter immediately following in the graph to get
10245 the output in a supported format.
10249 Map hardware frames to system memory or to another device.
10251 This filter has several different modes of operation; which one is used depends
10252 on the input and output formats:
10255 Hardware frame input, normal frame output
10257 Map the input frames to system memory and pass them to the output. If the
10258 original hardware frame is later required (for example, after overlaying
10259 something else on part of it), the @option{hwmap} filter can be used again
10260 in the next mode to retrieve it.
10262 Normal frame input, hardware frame output
10264 If the input is actually a software-mapped hardware frame, then unmap it -
10265 that is, return the original hardware frame.
10267 Otherwise, a device must be provided. Create new hardware surfaces on that
10268 device for the output, then map them back to the software format at the input
10269 and give those frames to the preceding filter. This will then act like the
10270 @option{hwupload} filter, but may be able to avoid an additional copy when
10271 the input is already in a compatible format.
10273 Hardware frame input and output
10275 A device must be supplied for the output, either directly or with the
10276 @option{derive_device} option. The input and output devices must be of
10277 different types and compatible - the exact meaning of this is
10278 system-dependent, but typically it means that they must refer to the same
10279 underlying hardware context (for example, refer to the same graphics card).
10281 If the input frames were originally created on the output device, then unmap
10282 to retrieve the original frames.
10284 Otherwise, map the frames to the output device - create new hardware frames
10285 on the output corresponding to the frames on the input.
10288 The following additional parameters are accepted:
10292 Set the frame mapping mode. Some combination of:
10295 The mapped frame should be readable.
10297 The mapped frame should be writeable.
10299 The mapping will always overwrite the entire frame.
10301 This may improve performance in some cases, as the original contents of the
10302 frame need not be loaded.
10304 The mapping must not involve any copying.
10306 Indirect mappings to copies of frames are created in some cases where either
10307 direct mapping is not possible or it would have unexpected properties.
10308 Setting this flag ensures that the mapping is direct and will fail if that is
10311 Defaults to @var{read+write} if not specified.
10313 @item derive_device @var{type}
10314 Rather than using the device supplied at initialisation, instead derive a new
10315 device of type @var{type} from the device the input frames exist on.
10318 In a hardware to hardware mapping, map in reverse - create frames in the sink
10319 and map them back to the source. This may be necessary in some cases where
10320 a mapping in one direction is required but only the opposite direction is
10321 supported by the devices being used.
10323 This option is dangerous - it may break the preceding filter in undefined
10324 ways if there are any additional constraints on that filter's output.
10325 Do not use it without fully understanding the implications of its use.
10330 Upload system memory frames to hardware surfaces.
10332 The device to upload to must be supplied when the filter is initialised. If
10333 using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
10336 @anchor{hwupload_cuda}
10337 @section hwupload_cuda
10339 Upload system memory frames to a CUDA device.
10341 It accepts the following optional parameters:
10345 The number of the CUDA device to use
10350 Apply a high-quality magnification filter designed for pixel art. This filter
10351 was originally created by Maxim Stepin.
10353 It accepts the following option:
10357 Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
10358 @code{hq3x} and @code{4} for @code{hq4x}.
10359 Default is @code{3}.
10363 Stack input videos horizontally.
10365 All streams must be of same pixel format and of same height.
10367 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
10368 to create same output.
10370 The filter accept the following option:
10374 Set number of input streams. Default is 2.
10377 If set to 1, force the output to terminate when the shortest input
10378 terminates. Default value is 0.
10383 Modify the hue and/or the saturation of the input.
10385 It accepts the following parameters:
10389 Specify the hue angle as a number of degrees. It accepts an expression,
10390 and defaults to "0".
10393 Specify the saturation in the [-10,10] range. It accepts an expression and
10397 Specify the hue angle as a number of radians. It accepts an
10398 expression, and defaults to "0".
10401 Specify the brightness in the [-10,10] range. It accepts an expression and
10405 @option{h} and @option{H} are mutually exclusive, and can't be
10406 specified at the same time.
10408 The @option{b}, @option{h}, @option{H} and @option{s} option values are
10409 expressions containing the following constants:
10413 frame count of the input frame starting from 0
10416 presentation timestamp of the input frame expressed in time base units
10419 frame rate of the input video, NAN if the input frame rate is unknown
10422 timestamp expressed in seconds, NAN if the input timestamp is unknown
10425 time base of the input video
10428 @subsection Examples
10432 Set the hue to 90 degrees and the saturation to 1.0:
10438 Same command but expressing the hue in radians:
10444 Rotate hue and make the saturation swing between 0
10445 and 2 over a period of 1 second:
10447 hue="H=2*PI*t: s=sin(2*PI*t)+1"
10451 Apply a 3 seconds saturation fade-in effect starting at 0:
10453 hue="s=min(t/3\,1)"
10456 The general fade-in expression can be written as:
10458 hue="s=min(0\, max((t-START)/DURATION\, 1))"
10462 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
10464 hue="s=max(0\, min(1\, (8-t)/3))"
10467 The general fade-out expression can be written as:
10469 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
10474 @subsection Commands
10476 This filter supports the following commands:
10482 Modify the hue and/or the saturation and/or brightness of the input video.
10483 The command accepts the same syntax of the corresponding option.
10485 If the specified expression is not valid, it is kept at its current
10489 @section hysteresis
10491 Grow first stream into second stream by connecting components.
10492 This makes it possible to build more robust edge masks.
10494 This filter accepts the following options:
10498 Set which planes will be processed as bitmap, unprocessed planes will be
10499 copied from first stream.
10500 By default value 0xf, all planes will be processed.
10503 Set threshold which is used in filtering. If pixel component value is higher than
10504 this value filter algorithm for connecting components is activated.
10505 By default value is 0.
10510 Detect video interlacing type.
10512 This filter tries to detect if the input frames are interlaced, progressive,
10513 top or bottom field first. It will also try to detect fields that are
10514 repeated between adjacent frames (a sign of telecine).
10516 Single frame detection considers only immediately adjacent frames when classifying each frame.
10517 Multiple frame detection incorporates the classification history of previous frames.
10519 The filter will log these metadata values:
10522 @item single.current_frame
10523 Detected type of current frame using single-frame detection. One of:
10524 ``tff'' (top field first), ``bff'' (bottom field first),
10525 ``progressive'', or ``undetermined''
10528 Cumulative number of frames detected as top field first using single-frame detection.
10531 Cumulative number of frames detected as top field first using multiple-frame detection.
10534 Cumulative number of frames detected as bottom field first using single-frame detection.
10536 @item multiple.current_frame
10537 Detected type of current frame using multiple-frame detection. One of:
10538 ``tff'' (top field first), ``bff'' (bottom field first),
10539 ``progressive'', or ``undetermined''
10542 Cumulative number of frames detected as bottom field first using multiple-frame detection.
10544 @item single.progressive
10545 Cumulative number of frames detected as progressive using single-frame detection.
10547 @item multiple.progressive
10548 Cumulative number of frames detected as progressive using multiple-frame detection.
10550 @item single.undetermined
10551 Cumulative number of frames that could not be classified using single-frame detection.
10553 @item multiple.undetermined
10554 Cumulative number of frames that could not be classified using multiple-frame detection.
10556 @item repeated.current_frame
10557 Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
10559 @item repeated.neither
10560 Cumulative number of frames with no repeated field.
10563 Cumulative number of frames with the top field repeated from the previous frame's top field.
10565 @item repeated.bottom
10566 Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
10569 The filter accepts the following options:
10573 Set interlacing threshold.
10575 Set progressive threshold.
10577 Threshold for repeated field detection.
10579 Number of frames after which a given frame's contribution to the
10580 statistics is halved (i.e., it contributes only 0.5 to its
10581 classification). The default of 0 means that all frames seen are given
10582 full weight of 1.0 forever.
10583 @item analyze_interlaced_flag
10584 When this is not 0 then idet will use the specified number of frames to determine
10585 if the interlaced flag is accurate, it will not count undetermined frames.
10586 If the flag is found to be accurate it will be used without any further
10587 computations, if it is found to be inaccurate it will be cleared without any
10588 further computations. This allows inserting the idet filter as a low computational
10589 method to clean up the interlaced flag
10594 Deinterleave or interleave fields.
10596 This filter allows one to process interlaced images fields without
10597 deinterlacing them. Deinterleaving splits the input frame into 2
10598 fields (so called half pictures). Odd lines are moved to the top
10599 half of the output image, even lines to the bottom half.
10600 You can process (filter) them independently and then re-interleave them.
10602 The filter accepts the following options:
10606 @item chroma_mode, c
10607 @item alpha_mode, a
10608 Available values for @var{luma_mode}, @var{chroma_mode} and
10609 @var{alpha_mode} are:
10615 @item deinterleave, d
10616 Deinterleave fields, placing one above the other.
10618 @item interleave, i
10619 Interleave fields. Reverse the effect of deinterleaving.
10621 Default value is @code{none}.
10623 @item luma_swap, ls
10624 @item chroma_swap, cs
10625 @item alpha_swap, as
10626 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
10631 Apply inflate effect to the video.
10633 This filter replaces the pixel by the local(3x3) average by taking into account
10634 only values higher than the pixel.
10636 It accepts the following options:
10643 Limit the maximum change for each plane, default is 65535.
10644 If 0, plane will remain unchanged.
10649 Simple interlacing filter from progressive contents. This interleaves upper (or
10650 lower) lines from odd frames with lower (or upper) lines from even frames,
10651 halving the frame rate and preserving image height.
10654 Original Original New Frame
10655 Frame 'j' Frame 'j+1' (tff)
10656 ========== =========== ==================
10657 Line 0 --------------------> Frame 'j' Line 0
10658 Line 1 Line 1 ----> Frame 'j+1' Line 1
10659 Line 2 ---------------------> Frame 'j' Line 2
10660 Line 3 Line 3 ----> Frame 'j+1' Line 3
10662 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
10665 It accepts the following optional parameters:
10669 This determines whether the interlaced frame is taken from the even
10670 (tff - default) or odd (bff) lines of the progressive frame.
10673 Vertical lowpass filter to avoid twitter interlacing and
10674 reduce moire patterns.
10678 Disable vertical lowpass filter
10681 Enable linear filter (default)
10684 Enable complex filter. This will slightly less reduce twitter and moire
10685 but better retain detail and subjective sharpness impression.
10692 Deinterlace input video by applying Donald Graft's adaptive kernel
10693 deinterling. Work on interlaced parts of a video to produce
10694 progressive frames.
10696 The description of the accepted parameters follows.
10700 Set the threshold which affects the filter's tolerance when
10701 determining if a pixel line must be processed. It must be an integer
10702 in the range [0,255] and defaults to 10. A value of 0 will result in
10703 applying the process on every pixels.
10706 Paint pixels exceeding the threshold value to white if set to 1.
10710 Set the fields order. Swap fields if set to 1, leave fields alone if
10714 Enable additional sharpening if set to 1. Default is 0.
10717 Enable twoway sharpening if set to 1. Default is 0.
10720 @subsection Examples
10724 Apply default values:
10726 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
10730 Enable additional sharpening:
10736 Paint processed pixels in white:
10742 @section lenscorrection
10744 Correct radial lens distortion
10746 This filter can be used to correct for radial distortion as can result from the use
10747 of wide angle lenses, and thereby re-rectify the image. To find the right parameters
10748 one can use tools available for example as part of opencv or simply trial-and-error.
10749 To use opencv use the calibration sample (under samples/cpp) from the opencv sources
10750 and extract the k1 and k2 coefficients from the resulting matrix.
10752 Note that effectively the same filter is available in the open-source tools Krita and
10753 Digikam from the KDE project.
10755 In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
10756 this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
10757 brightness distribution, so you may want to use both filters together in certain
10758 cases, though you will have to take care of ordering, i.e. whether vignetting should
10759 be applied before or after lens correction.
10761 @subsection Options
10763 The filter accepts the following options:
10767 Relative x-coordinate of the focal point of the image, and thereby the center of the
10768 distortion. This value has a range [0,1] and is expressed as fractions of the image
10769 width. Default is 0.5.
10771 Relative y-coordinate of the focal point of the image, and thereby the center of the
10772 distortion. This value has a range [0,1] and is expressed as fractions of the image
10773 height. Default is 0.5.
10775 Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means
10776 no correction. Default is 0.
10778 Coefficient of the double quadratic correction term. This value has a range [-1,1].
10779 0 means no correction. Default is 0.
10782 The formula that generates the correction is:
10784 @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)
10786 where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
10787 distances from the focal point in the source and target images, respectively.
10791 Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}).
10793 The @code{lensfun} filter requires the camera make, camera model, and lens model
10794 to apply the lens correction. The filter will load the lensfun database and
10795 query it to find the corresponding camera and lens entries in the database. As
10796 long as these entries can be found with the given options, the filter can
10797 perform corrections on frames. Note that incomplete strings will result in the
10798 filter choosing the best match with the given options, and the filter will
10799 output the chosen camera and lens models (logged with level "info"). You must
10800 provide the make, camera model, and lens model as they are required.
10802 The filter accepts the following options:
10806 The make of the camera (for example, "Canon"). This option is required.
10809 The model of the camera (for example, "Canon EOS 100D"). This option is
10813 The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This
10814 option is required.
10817 The type of correction to apply. The following values are valid options:
10821 Enables fixing lens vignetting.
10824 Enables fixing lens geometry. This is the default.
10827 Enables fixing chromatic aberrations.
10830 Enables fixing lens vignetting and lens geometry.
10833 Enables fixing lens vignetting and chromatic aberrations.
10836 Enables fixing both lens geometry and chromatic aberrations.
10839 Enables all possible corrections.
10843 The focal length of the image/video (zoom; expected constant for video). For
10844 example, a 18--55mm lens has focal length range of [18--55], so a value in that
10845 range should be chosen when using that lens. Default 18.
10848 The aperture of the image/video (expected constant for video). Note that
10849 aperture is only used for vignetting correction. Default 3.5.
10851 @item focus_distance
10852 The focus distance of the image/video (expected constant for video). Note that
10853 focus distance is only used for vignetting and only slightly affects the
10854 vignetting correction process. If unknown, leave it at the default value (which
10857 @item target_geometry
10858 The target geometry of the output image/video. The following values are valid
10862 @item rectilinear (default)
10865 @item equirectangular
10866 @item fisheye_orthographic
10867 @item fisheye_stereographic
10868 @item fisheye_equisolid
10869 @item fisheye_thoby
10872 Apply the reverse of image correction (instead of correcting distortion, apply
10875 @item interpolation
10876 The type of interpolation used when correcting distortion. The following values
10881 @item linear (default)
10886 @subsection Examples
10890 Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens
10891 model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and
10895 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
10899 Apply the same as before, but only for the first 5 seconds of video.
10902 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
10909 Obtain the VMAF (Video Multi-Method Assessment Fusion)
10910 score between two input videos.
10912 The obtained VMAF score is printed through the logging system.
10914 It requires Netflix's vmaf library (libvmaf) as a pre-requisite.
10915 After installing the library it can be enabled using:
10916 @code{./configure --enable-libvmaf --enable-version3}.
10917 If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}.
10919 The filter has following options:
10923 Set the model path which is to be used for SVM.
10924 Default value: @code{"vmaf_v0.6.1.pkl"}
10927 Set the file path to be used to store logs.
10930 Set the format of the log file (xml or json).
10932 @item enable_transform
10933 Enables transform for computing vmaf.
10936 Invokes the phone model which will generate VMAF scores higher than in the
10937 regular model, which is more suitable for laptop, TV, etc. viewing conditions.
10940 Enables computing psnr along with vmaf.
10943 Enables computing ssim along with vmaf.
10946 Enables computing ms_ssim along with vmaf.
10949 Set the pool method (mean, min or harmonic mean) to be used for computing vmaf.
10952 Set number of threads to be used when computing vmaf.
10955 Set interval for frame subsampling used when computing vmaf.
10957 @item enable_conf_interval
10958 Enables confidence interval.
10961 This filter also supports the @ref{framesync} options.
10963 On the below examples the input file @file{main.mpg} being processed is
10964 compared with the reference file @file{ref.mpg}.
10967 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
10970 Example with options:
10972 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:enable-transform=1" -f null -
10977 Limits the pixel components values to the specified range [min, max].
10979 The filter accepts the following options:
10983 Lower bound. Defaults to the lowest allowed value for the input.
10986 Upper bound. Defaults to the highest allowed value for the input.
10989 Specify which planes will be processed. Defaults to all available.
10996 The filter accepts the following options:
11000 Set the number of loops. Setting this value to -1 will result in infinite loops.
11004 Set maximal size in number of frames. Default is 0.
11007 Set first frame of loop. Default is 0.
11012 Apply a 1D LUT to an input video.
11014 The filter accepts the following options:
11018 Set the 1D LUT file name.
11020 Currently supported formats:
11027 Select interpolation mode.
11029 Available values are:
11033 Use values from the nearest defined point.
11035 Interpolate values using the linear interpolation.
11037 Interpolate values using the cubic interpolation.
11044 Apply a 3D LUT to an input video.
11046 The filter accepts the following options:
11050 Set the 3D LUT file name.
11052 Currently supported formats:
11064 Select interpolation mode.
11066 Available values are:
11070 Use values from the nearest defined point.
11072 Interpolate values using the 8 points defining a cube.
11074 Interpolate values using a tetrahedron.
11078 This filter also supports the @ref{framesync} options.
11082 Turn certain luma values into transparency.
11084 The filter accepts the following options:
11088 Set the luma which will be used as base for transparency.
11089 Default value is @code{0}.
11092 Set the range of luma values to be keyed out.
11093 Default value is @code{0}.
11096 Set the range of softness. Default value is @code{0}.
11097 Use this to control gradual transition from zero to full transparency.
11100 @section lut, lutrgb, lutyuv
11102 Compute a look-up table for binding each pixel component input value
11103 to an output value, and apply it to the input video.
11105 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
11106 to an RGB input video.
11108 These filters accept the following parameters:
11111 set first pixel component expression
11113 set second pixel component expression
11115 set third pixel component expression
11117 set fourth pixel component expression, corresponds to the alpha component
11120 set red component expression
11122 set green component expression
11124 set blue component expression
11126 alpha component expression
11129 set Y/luminance component expression
11131 set U/Cb component expression
11133 set V/Cr component expression
11136 Each of them specifies the expression to use for computing the lookup table for
11137 the corresponding pixel component values.
11139 The exact component associated to each of the @var{c*} options depends on the
11142 The @var{lut} filter requires either YUV or RGB pixel formats in input,
11143 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
11145 The expressions can contain the following constants and functions:
11150 The input width and height.
11153 The input value for the pixel component.
11156 The input value, clipped to the @var{minval}-@var{maxval} range.
11159 The maximum value for the pixel component.
11162 The minimum value for the pixel component.
11165 The negated value for the pixel component value, clipped to the
11166 @var{minval}-@var{maxval} range; it corresponds to the expression
11167 "maxval-clipval+minval".
11170 The computed value in @var{val}, clipped to the
11171 @var{minval}-@var{maxval} range.
11173 @item gammaval(gamma)
11174 The computed gamma correction value of the pixel component value,
11175 clipped to the @var{minval}-@var{maxval} range. It corresponds to the
11177 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
11181 All expressions default to "val".
11183 @subsection Examples
11187 Negate input video:
11189 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
11190 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
11193 The above is the same as:
11195 lutrgb="r=negval:g=negval:b=negval"
11196 lutyuv="y=negval:u=negval:v=negval"
11206 Remove chroma components, turning the video into a graytone image:
11208 lutyuv="u=128:v=128"
11212 Apply a luma burning effect:
11218 Remove green and blue components:
11224 Set a constant alpha channel value on input:
11226 format=rgba,lutrgb=a="maxval-minval/2"
11230 Correct luminance gamma by a factor of 0.5:
11232 lutyuv=y=gammaval(0.5)
11236 Discard least significant bits of luma:
11238 lutyuv=y='bitand(val, 128+64+32)'
11242 Technicolor like effect:
11244 lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
11248 @section lut2, tlut2
11250 The @code{lut2} filter takes two input streams and outputs one
11253 The @code{tlut2} (time lut2) filter takes two consecutive frames
11254 from one single stream.
11256 This filter accepts the following parameters:
11259 set first pixel component expression
11261 set second pixel component expression
11263 set third pixel component expression
11265 set fourth pixel component expression, corresponds to the alpha component
11268 Each of them specifies the expression to use for computing the lookup table for
11269 the corresponding pixel component values.
11271 The exact component associated to each of the @var{c*} options depends on the
11274 The expressions can contain the following constants:
11279 The input width and height.
11282 The first input value for the pixel component.
11285 The second input value for the pixel component.
11288 The first input video bit depth.
11291 The second input video bit depth.
11294 All expressions default to "x".
11296 @subsection Examples
11300 Highlight differences between two RGB video streams:
11302 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)'
11306 Highlight differences between two YUV video streams:
11308 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)'
11312 Show max difference between two video streams:
11314 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)))'
11318 @section maskedclamp
11320 Clamp the first input stream with the second input and third input stream.
11322 Returns the value of first stream to be between second input
11323 stream - @code{undershoot} and third input stream + @code{overshoot}.
11325 This filter accepts the following options:
11328 Default value is @code{0}.
11331 Default value is @code{0}.
11334 Set which planes will be processed as bitmap, unprocessed planes will be
11335 copied from first stream.
11336 By default value 0xf, all planes will be processed.
11339 @section maskedmerge
11341 Merge the first input stream with the second input stream using per pixel
11342 weights in the third input stream.
11344 A value of 0 in the third stream pixel component means that pixel component
11345 from first stream is returned unchanged, while maximum value (eg. 255 for
11346 8-bit videos) means that pixel component from second stream is returned
11347 unchanged. Intermediate values define the amount of merging between both
11348 input stream's pixel components.
11350 This filter accepts the following options:
11353 Set which planes will be processed as bitmap, unprocessed planes will be
11354 copied from first stream.
11355 By default value 0xf, all planes will be processed.
11360 Apply motion-compensation deinterlacing.
11362 It needs one field per frame as input and must thus be used together
11363 with yadif=1/3 or equivalent.
11365 This filter accepts the following options:
11368 Set the deinterlacing mode.
11370 It accepts one of the following values:
11375 use iterative motion estimation
11377 like @samp{slow}, but use multiple reference frames.
11379 Default value is @samp{fast}.
11382 Set the picture field parity assumed for the input video. It must be
11383 one of the following values:
11387 assume top field first
11389 assume bottom field first
11392 Default value is @samp{bff}.
11395 Set per-block quantization parameter (QP) used by the internal
11398 Higher values should result in a smoother motion vector field but less
11399 optimal individual vectors. Default value is 1.
11402 @section mergeplanes
11404 Merge color channel components from several video streams.
11406 The filter accepts up to 4 input streams, and merge selected input
11407 planes to the output video.
11409 This filter accepts the following options:
11412 Set input to output plane mapping. Default is @code{0}.
11414 The mappings is specified as a bitmap. It should be specified as a
11415 hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
11416 mapping for the first plane of the output stream. 'A' sets the number of
11417 the input stream to use (from 0 to 3), and 'a' the plane number of the
11418 corresponding input to use (from 0 to 3). The rest of the mappings is
11419 similar, 'Bb' describes the mapping for the output stream second
11420 plane, 'Cc' describes the mapping for the output stream third plane and
11421 'Dd' describes the mapping for the output stream fourth plane.
11424 Set output pixel format. Default is @code{yuva444p}.
11427 @subsection Examples
11431 Merge three gray video streams of same width and height into single video stream:
11433 [a0][a1][a2]mergeplanes=0x001020:yuv444p
11437 Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
11439 [a0][a1]mergeplanes=0x00010210:yuva444p
11443 Swap Y and A plane in yuva444p stream:
11445 format=yuva444p,mergeplanes=0x03010200:yuva444p
11449 Swap U and V plane in yuv420p stream:
11451 format=yuv420p,mergeplanes=0x000201:yuv420p
11455 Cast a rgb24 clip to yuv444p:
11457 format=rgb24,mergeplanes=0x000102:yuv444p
11463 Estimate and export motion vectors using block matching algorithms.
11464 Motion vectors are stored in frame side data to be used by other filters.
11466 This filter accepts the following options:
11469 Specify the motion estimation method. Accepts one of the following values:
11473 Exhaustive search algorithm.
11475 Three step search algorithm.
11477 Two dimensional logarithmic search algorithm.
11479 New three step search algorithm.
11481 Four step search algorithm.
11483 Diamond search algorithm.
11485 Hexagon-based search algorithm.
11487 Enhanced predictive zonal search algorithm.
11489 Uneven multi-hexagon search algorithm.
11491 Default value is @samp{esa}.
11494 Macroblock size. Default @code{16}.
11497 Search parameter. Default @code{7}.
11500 @section midequalizer
11502 Apply Midway Image Equalization effect using two video streams.
11504 Midway Image Equalization adjusts a pair of images to have the same
11505 histogram, while maintaining their dynamics as much as possible. It's
11506 useful for e.g. matching exposures from a pair of stereo cameras.
11508 This filter has two inputs and one output, which must be of same pixel format, but
11509 may be of different sizes. The output of filter is first input adjusted with
11510 midway histogram of both inputs.
11512 This filter accepts the following option:
11516 Set which planes to process. Default is @code{15}, which is all available planes.
11519 @section minterpolate
11521 Convert the video to specified frame rate using motion interpolation.
11523 This filter accepts the following options:
11526 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}.
11529 Motion interpolation mode. Following values are accepted:
11532 Duplicate previous or next frame for interpolating new ones.
11534 Blend source frames. Interpolated frame is mean of previous and next frames.
11536 Motion compensated interpolation. Following options are effective when this mode is selected:
11540 Motion compensation mode. Following values are accepted:
11543 Overlapped block motion compensation.
11545 Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
11547 Default mode is @samp{obmc}.
11550 Motion estimation mode. Following values are accepted:
11553 Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
11555 Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
11557 Default mode is @samp{bilat}.
11560 The algorithm to be used for motion estimation. Following values are accepted:
11563 Exhaustive search algorithm.
11565 Three step search algorithm.
11567 Two dimensional logarithmic search algorithm.
11569 New three step search algorithm.
11571 Four step search algorithm.
11573 Diamond search algorithm.
11575 Hexagon-based search algorithm.
11577 Enhanced predictive zonal search algorithm.
11579 Uneven multi-hexagon search algorithm.
11581 Default algorithm is @samp{epzs}.
11584 Macroblock size. Default @code{16}.
11587 Motion estimation search parameter. Default @code{32}.
11590 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).
11595 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:
11598 Disable scene change detection.
11600 Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected.
11602 Default method is @samp{fdiff}.
11604 @item scd_threshold
11605 Scene change detection threshold. Default is @code{5.0}.
11610 Mix several video input streams into one video stream.
11612 A description of the accepted options follows.
11616 The number of inputs. If unspecified, it defaults to 2.
11619 Specify weight of each input video stream as sequence.
11620 Each weight is separated by space. If number of weights
11621 is smaller than number of @var{frames} last specified
11622 weight will be used for all remaining unset weights.
11625 Specify scale, if it is set it will be multiplied with sum
11626 of each weight multiplied with pixel values to give final destination
11627 pixel value. By default @var{scale} is auto scaled to sum of weights.
11630 Specify how end of stream is determined.
11633 The duration of the longest input. (default)
11636 The duration of the shortest input.
11639 The duration of the first input.
11643 @section mpdecimate
11645 Drop frames that do not differ greatly from the previous frame in
11646 order to reduce frame rate.
11648 The main use of this filter is for very-low-bitrate encoding
11649 (e.g. streaming over dialup modem), but it could in theory be used for
11650 fixing movies that were inverse-telecined incorrectly.
11652 A description of the accepted options follows.
11656 Set the maximum number of consecutive frames which can be dropped (if
11657 positive), or the minimum interval between dropped frames (if
11658 negative). If the value is 0, the frame is dropped disregarding the
11659 number of previous sequentially dropped frames.
11661 Default value is 0.
11666 Set the dropping threshold values.
11668 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
11669 represent actual pixel value differences, so a threshold of 64
11670 corresponds to 1 unit of difference for each pixel, or the same spread
11671 out differently over the block.
11673 A frame is a candidate for dropping if no 8x8 blocks differ by more
11674 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
11675 meaning the whole image) differ by more than a threshold of @option{lo}.
11677 Default value for @option{hi} is 64*12, default value for @option{lo} is
11678 64*5, and default value for @option{frac} is 0.33.
11684 Negate (invert) the input video.
11686 It accepts the following option:
11691 With value 1, it negates the alpha component, if present. Default value is 0.
11696 Denoise frames using Non-Local Means algorithm.
11698 Each pixel is adjusted by looking for other pixels with similar contexts. This
11699 context similarity is defined by comparing their surrounding patches of size
11700 @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
11703 Note that the research area defines centers for patches, which means some
11704 patches will be made of pixels outside that research area.
11706 The filter accepts the following options.
11710 Set denoising strength.
11716 Same as @option{p} but for chroma planes.
11718 The default value is @var{0} and means automatic.
11724 Same as @option{r} but for chroma planes.
11726 The default value is @var{0} and means automatic.
11731 Deinterlace video using neural network edge directed interpolation.
11733 This filter accepts the following options:
11737 Mandatory option, without binary file filter can not work.
11738 Currently file can be found here:
11739 https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
11742 Set which frames to deinterlace, by default it is @code{all}.
11743 Can be @code{all} or @code{interlaced}.
11746 Set mode of operation.
11748 Can be one of the following:
11752 Use frame flags, both fields.
11754 Use frame flags, single field.
11756 Use top field only.
11758 Use bottom field only.
11760 Use both fields, top first.
11762 Use both fields, bottom first.
11766 Set which planes to process, by default filter process all frames.
11769 Set size of local neighborhood around each pixel, used by the predictor neural
11772 Can be one of the following:
11785 Set the number of neurons in predictor neural network.
11786 Can be one of the following:
11797 Controls the number of different neural network predictions that are blended
11798 together to compute the final output value. Can be @code{fast}, default or
11802 Set which set of weights to use in the predictor.
11803 Can be one of the following:
11807 weights trained to minimize absolute error
11809 weights trained to minimize squared error
11813 Controls whether or not the prescreener neural network is used to decide
11814 which pixels should be processed by the predictor neural network and which
11815 can be handled by simple cubic interpolation.
11816 The prescreener is trained to know whether cubic interpolation will be
11817 sufficient for a pixel or whether it should be predicted by the predictor nn.
11818 The computational complexity of the prescreener nn is much less than that of
11819 the predictor nn. Since most pixels can be handled by cubic interpolation,
11820 using the prescreener generally results in much faster processing.
11821 The prescreener is pretty accurate, so the difference between using it and not
11822 using it is almost always unnoticeable.
11824 Can be one of the following:
11832 Default is @code{new}.
11835 Set various debugging flags.
11840 Force libavfilter not to use any of the specified pixel formats for the
11841 input to the next filter.
11843 It accepts the following parameters:
11847 A '|'-separated list of pixel format names, such as
11848 pix_fmts=yuv420p|monow|rgb24".
11852 @subsection Examples
11856 Force libavfilter to use a format different from @var{yuv420p} for the
11857 input to the vflip filter:
11859 noformat=pix_fmts=yuv420p,vflip
11863 Convert the input video to any of the formats not contained in the list:
11865 noformat=yuv420p|yuv444p|yuv410p
11871 Add noise on video input frame.
11873 The filter accepts the following options:
11881 Set noise seed for specific pixel component or all pixel components in case
11882 of @var{all_seed}. Default value is @code{123457}.
11884 @item all_strength, alls
11885 @item c0_strength, c0s
11886 @item c1_strength, c1s
11887 @item c2_strength, c2s
11888 @item c3_strength, c3s
11889 Set noise strength for specific pixel component or all pixel components in case
11890 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
11892 @item all_flags, allf
11893 @item c0_flags, c0f
11894 @item c1_flags, c1f
11895 @item c2_flags, c2f
11896 @item c3_flags, c3f
11897 Set pixel component flags or set flags for all components if @var{all_flags}.
11898 Available values for component flags are:
11901 averaged temporal noise (smoother)
11903 mix random noise with a (semi)regular pattern
11905 temporal noise (noise pattern changes between frames)
11907 uniform noise (gaussian otherwise)
11911 @subsection Examples
11913 Add temporal and uniform noise to input video:
11915 noise=alls=20:allf=t+u
11920 Normalize RGB video (aka histogram stretching, contrast stretching).
11921 See: https://en.wikipedia.org/wiki/Normalization_(image_processing)
11923 For each channel of each frame, the filter computes the input range and maps
11924 it linearly to the user-specified output range. The output range defaults
11925 to the full dynamic range from pure black to pure white.
11927 Temporal smoothing can be used on the input range to reduce flickering (rapid
11928 changes in brightness) caused when small dark or bright objects enter or leave
11929 the scene. This is similar to the auto-exposure (automatic gain control) on a
11930 video camera, and, like a video camera, it may cause a period of over- or
11931 under-exposure of the video.
11933 The R,G,B channels can be normalized independently, which may cause some
11934 color shifting, or linked together as a single channel, which prevents
11935 color shifting. Linked normalization preserves hue. Independent normalization
11936 does not, so it can be used to remove some color casts. Independent and linked
11937 normalization can be combined in any ratio.
11939 The normalize filter accepts the following options:
11944 Colors which define the output range. The minimum input value is mapped to
11945 the @var{blackpt}. The maximum input value is mapped to the @var{whitept}.
11946 The defaults are black and white respectively. Specifying white for
11947 @var{blackpt} and black for @var{whitept} will give color-inverted,
11948 normalized video. Shades of grey can be used to reduce the dynamic range
11949 (contrast). Specifying saturated colors here can create some interesting
11953 The number of previous frames to use for temporal smoothing. The input range
11954 of each channel is smoothed using a rolling average over the current frame
11955 and the @var{smoothing} previous frames. The default is 0 (no temporal
11959 Controls the ratio of independent (color shifting) channel normalization to
11960 linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully
11961 independent. Defaults to 1.0 (fully independent).
11964 Overall strength of the filter. 1.0 is full strength. 0.0 is a rather
11965 expensive no-op. Defaults to 1.0 (full strength).
11969 @subsection Examples
11971 Stretch video contrast to use the full dynamic range, with no temporal
11972 smoothing; may flicker depending on the source content:
11974 normalize=blackpt=black:whitept=white:smoothing=0
11977 As above, but with 50 frames of temporal smoothing; flicker should be
11978 reduced, depending on the source content:
11980 normalize=blackpt=black:whitept=white:smoothing=50
11983 As above, but with hue-preserving linked channel normalization:
11985 normalize=blackpt=black:whitept=white:smoothing=50:independence=0
11988 As above, but with half strength:
11990 normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
11993 Map the darkest input color to red, the brightest input color to cyan:
11995 normalize=blackpt=red:whitept=cyan
12000 Pass the video source unchanged to the output.
12003 Optical Character Recognition
12005 This filter uses Tesseract for optical character recognition. To enable
12006 compilation of this filter, you need to configure FFmpeg with
12007 @code{--enable-libtesseract}.
12009 It accepts the following options:
12013 Set datapath to tesseract data. Default is to use whatever was
12014 set at installation.
12017 Set language, default is "eng".
12020 Set character whitelist.
12023 Set character blacklist.
12026 The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
12030 Apply a video transform using libopencv.
12032 To enable this filter, install the libopencv library and headers and
12033 configure FFmpeg with @code{--enable-libopencv}.
12035 It accepts the following parameters:
12040 The name of the libopencv filter to apply.
12042 @item filter_params
12043 The parameters to pass to the libopencv filter. If not specified, the default
12044 values are assumed.
12048 Refer to the official libopencv documentation for more precise
12050 @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
12052 Several libopencv filters are supported; see the following subsections.
12057 Dilate an image by using a specific structuring element.
12058 It corresponds to the libopencv function @code{cvDilate}.
12060 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
12062 @var{struct_el} represents a structuring element, and has the syntax:
12063 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
12065 @var{cols} and @var{rows} represent the number of columns and rows of
12066 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
12067 point, and @var{shape} the shape for the structuring element. @var{shape}
12068 must be "rect", "cross", "ellipse", or "custom".
12070 If the value for @var{shape} is "custom", it must be followed by a
12071 string of the form "=@var{filename}". The file with name
12072 @var{filename} is assumed to represent a binary image, with each
12073 printable character corresponding to a bright pixel. When a custom
12074 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
12075 or columns and rows of the read file are assumed instead.
12077 The default value for @var{struct_el} is "3x3+0x0/rect".
12079 @var{nb_iterations} specifies the number of times the transform is
12080 applied to the image, and defaults to 1.
12084 # Use the default values
12087 # Dilate using a structuring element with a 5x5 cross, iterating two times
12088 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
12090 # Read the shape from the file diamond.shape, iterating two times.
12091 # The file diamond.shape may contain a pattern of characters like this
12097 # The specified columns and rows are ignored
12098 # but the anchor point coordinates are not
12099 ocv=dilate:0x0+2x2/custom=diamond.shape|2
12104 Erode an image by using a specific structuring element.
12105 It corresponds to the libopencv function @code{cvErode}.
12107 It accepts the parameters: @var{struct_el}:@var{nb_iterations},
12108 with the same syntax and semantics as the @ref{dilate} filter.
12112 Smooth the input video.
12114 The filter takes the following parameters:
12115 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
12117 @var{type} is the type of smooth filter to apply, and must be one of
12118 the following values: "blur", "blur_no_scale", "median", "gaussian",
12119 or "bilateral". The default value is "gaussian".
12121 The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
12122 depend on the smooth type. @var{param1} and
12123 @var{param2} accept integer positive values or 0. @var{param3} and
12124 @var{param4} accept floating point values.
12126 The default value for @var{param1} is 3. The default value for the
12127 other parameters is 0.
12129 These parameters correspond to the parameters assigned to the
12130 libopencv function @code{cvSmooth}.
12132 @section oscilloscope
12134 2D Video Oscilloscope.
12136 Useful to measure spatial impulse, step responses, chroma delays, etc.
12138 It accepts the following parameters:
12142 Set scope center x position.
12145 Set scope center y position.
12148 Set scope size, relative to frame diagonal.
12151 Set scope tilt/rotation.
12157 Set trace center x position.
12160 Set trace center y position.
12163 Set trace width, relative to width of frame.
12166 Set trace height, relative to height of frame.
12169 Set which components to trace. By default it traces first three components.
12172 Draw trace grid. By default is enabled.
12175 Draw some statistics. By default is enabled.
12178 Draw scope. By default is enabled.
12181 @subsection Examples
12185 Inspect full first row of video frame.
12187 oscilloscope=x=0.5:y=0:s=1
12191 Inspect full last row of video frame.
12193 oscilloscope=x=0.5:y=1:s=1
12197 Inspect full 5th line of video frame of height 1080.
12199 oscilloscope=x=0.5:y=5/1080:s=1
12203 Inspect full last column of video frame.
12205 oscilloscope=x=1:y=0.5:s=1:t=1
12213 Overlay one video on top of another.
12215 It takes two inputs and has one output. The first input is the "main"
12216 video on which the second input is overlaid.
12218 It accepts the following parameters:
12220 A description of the accepted options follows.
12225 Set the expression for the x and y coordinates of the overlaid video
12226 on the main video. Default value is "0" for both expressions. In case
12227 the expression is invalid, it is set to a huge value (meaning that the
12228 overlay will not be displayed within the output visible area).
12231 See @ref{framesync}.
12234 Set when the expressions for @option{x}, and @option{y} are evaluated.
12236 It accepts the following values:
12239 only evaluate expressions once during the filter initialization or
12240 when a command is processed
12243 evaluate expressions for each incoming frame
12246 Default value is @samp{frame}.
12249 See @ref{framesync}.
12252 Set the format for the output video.
12254 It accepts the following values:
12257 force YUV420 output
12260 force YUV422 output
12263 force YUV444 output
12266 force packed RGB output
12269 force planar RGB output
12272 automatically pick format
12275 Default value is @samp{yuv420}.
12278 See @ref{framesync}.
12281 Set format of alpha of the overlaid video, it can be @var{straight} or
12282 @var{premultiplied}. Default is @var{straight}.
12285 The @option{x}, and @option{y} expressions can contain the following
12291 The main input width and height.
12295 The overlay input width and height.
12299 The computed values for @var{x} and @var{y}. They are evaluated for
12304 horizontal and vertical chroma subsample values of the output
12305 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
12309 the number of input frame, starting from 0
12312 the position in the file of the input frame, NAN if unknown
12315 The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
12319 This filter also supports the @ref{framesync} options.
12321 Note that the @var{n}, @var{pos}, @var{t} variables are available only
12322 when evaluation is done @emph{per frame}, and will evaluate to NAN
12323 when @option{eval} is set to @samp{init}.
12325 Be aware that frames are taken from each input video in timestamp
12326 order, hence, if their initial timestamps differ, it is a good idea
12327 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
12328 have them begin in the same zero timestamp, as the example for
12329 the @var{movie} filter does.
12331 You can chain together more overlays but you should test the
12332 efficiency of such approach.
12334 @subsection Commands
12336 This filter supports the following commands:
12340 Modify the x and y of the overlay input.
12341 The command accepts the same syntax of the corresponding option.
12343 If the specified expression is not valid, it is kept at its current
12347 @subsection Examples
12351 Draw the overlay at 10 pixels from the bottom right corner of the main
12354 overlay=main_w-overlay_w-10:main_h-overlay_h-10
12357 Using named options the example above becomes:
12359 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
12363 Insert a transparent PNG logo in the bottom left corner of the input,
12364 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
12366 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
12370 Insert 2 different transparent PNG logos (second logo on bottom
12371 right corner) using the @command{ffmpeg} tool:
12373 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
12377 Add a transparent color layer on top of the main video; @code{WxH}
12378 must specify the size of the main input to the overlay filter:
12380 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
12384 Play an original video and a filtered version (here with the deshake
12385 filter) side by side using the @command{ffplay} tool:
12387 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
12390 The above command is the same as:
12392 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
12396 Make a sliding overlay appearing from the left to the right top part of the
12397 screen starting since time 2:
12399 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
12403 Compose output by putting two input videos side to side:
12405 ffmpeg -i left.avi -i right.avi -filter_complex "
12406 nullsrc=size=200x100 [background];
12407 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
12408 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
12409 [background][left] overlay=shortest=1 [background+left];
12410 [background+left][right] overlay=shortest=1:x=100 [left+right]
12415 Mask 10-20 seconds of a video by applying the delogo filter to a section
12417 ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
12418 -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]'
12423 Chain several overlays in cascade:
12425 nullsrc=s=200x200 [bg];
12426 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
12427 [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
12428 [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
12429 [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
12430 [in3] null, [mid2] overlay=100:100 [out0]
12437 Apply Overcomplete Wavelet denoiser.
12439 The filter accepts the following options:
12445 Larger depth values will denoise lower frequency components more, but
12446 slow down filtering.
12448 Must be an int in the range 8-16, default is @code{8}.
12450 @item luma_strength, ls
12453 Must be a double value in the range 0-1000, default is @code{1.0}.
12455 @item chroma_strength, cs
12456 Set chroma strength.
12458 Must be a double value in the range 0-1000, default is @code{1.0}.
12464 Add paddings to the input image, and place the original input at the
12465 provided @var{x}, @var{y} coordinates.
12467 It accepts the following parameters:
12472 Specify an expression for the size of the output image with the
12473 paddings added. If the value for @var{width} or @var{height} is 0, the
12474 corresponding input size is used for the output.
12476 The @var{width} expression can reference the value set by the
12477 @var{height} expression, and vice versa.
12479 The default value of @var{width} and @var{height} is 0.
12483 Specify the offsets to place the input image at within the padded area,
12484 with respect to the top/left border of the output image.
12486 The @var{x} expression can reference the value set by the @var{y}
12487 expression, and vice versa.
12489 The default value of @var{x} and @var{y} is 0.
12491 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
12492 so the input image is centered on the padded area.
12495 Specify the color of the padded area. For the syntax of this option,
12496 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
12497 manual,ffmpeg-utils}.
12499 The default value of @var{color} is "black".
12502 Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression.
12504 It accepts the following values:
12508 Only evaluate expressions once during the filter initialization or when
12509 a command is processed.
12512 Evaluate expressions for each incoming frame.
12516 Default value is @samp{init}.
12519 Pad to aspect instead to a resolution.
12523 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
12524 options are expressions containing the following constants:
12529 The input video width and height.
12533 These are the same as @var{in_w} and @var{in_h}.
12537 The output width and height (the size of the padded area), as
12538 specified by the @var{width} and @var{height} expressions.
12542 These are the same as @var{out_w} and @var{out_h}.
12546 The x and y offsets as specified by the @var{x} and @var{y}
12547 expressions, or NAN if not yet specified.
12550 same as @var{iw} / @var{ih}
12553 input sample aspect ratio
12556 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
12560 The horizontal and vertical chroma subsample values. For example for the
12561 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
12564 @subsection Examples
12568 Add paddings with the color "violet" to the input video. The output video
12569 size is 640x480, and the top-left corner of the input video is placed at
12572 pad=640:480:0:40:violet
12575 The example above is equivalent to the following command:
12577 pad=width=640:height=480:x=0:y=40:color=violet
12581 Pad the input to get an output with dimensions increased by 3/2,
12582 and put the input video at the center of the padded area:
12584 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
12588 Pad the input to get a squared output with size equal to the maximum
12589 value between the input width and height, and put the input video at
12590 the center of the padded area:
12592 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
12596 Pad the input to get a final w/h ratio of 16:9:
12598 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
12602 In case of anamorphic video, in order to set the output display aspect
12603 correctly, it is necessary to use @var{sar} in the expression,
12604 according to the relation:
12606 (ih * X / ih) * sar = output_dar
12607 X = output_dar / sar
12610 Thus the previous example needs to be modified to:
12612 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
12616 Double the output size and put the input video in the bottom-right
12617 corner of the output padded area:
12619 pad="2*iw:2*ih:ow-iw:oh-ih"
12623 @anchor{palettegen}
12624 @section palettegen
12626 Generate one palette for a whole video stream.
12628 It accepts the following options:
12632 Set the maximum number of colors to quantize in the palette.
12633 Note: the palette will still contain 256 colors; the unused palette entries
12636 @item reserve_transparent
12637 Create a palette of 255 colors maximum and reserve the last one for
12638 transparency. Reserving the transparency color is useful for GIF optimization.
12639 If not set, the maximum of colors in the palette will be 256. You probably want
12640 to disable this option for a standalone image.
12643 @item transparency_color
12644 Set the color that will be used as background for transparency.
12647 Set statistics mode.
12649 It accepts the following values:
12652 Compute full frame histograms.
12654 Compute histograms only for the part that differs from previous frame. This
12655 might be relevant to give more importance to the moving part of your input if
12656 the background is static.
12658 Compute new histogram for each frame.
12661 Default value is @var{full}.
12664 The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
12665 (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
12666 color quantization of the palette. This information is also visible at
12667 @var{info} logging level.
12669 @subsection Examples
12673 Generate a representative palette of a given video using @command{ffmpeg}:
12675 ffmpeg -i input.mkv -vf palettegen palette.png
12679 @section paletteuse
12681 Use a palette to downsample an input video stream.
12683 The filter takes two inputs: one video stream and a palette. The palette must
12684 be a 256 pixels image.
12686 It accepts the following options:
12690 Select dithering mode. Available algorithms are:
12693 Ordered 8x8 bayer dithering (deterministic)
12695 Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
12696 Note: this dithering is sometimes considered "wrong" and is included as a
12698 @item floyd_steinberg
12699 Floyd and Steingberg dithering (error diffusion)
12701 Frankie Sierra dithering v2 (error diffusion)
12703 Frankie Sierra dithering v2 "Lite" (error diffusion)
12706 Default is @var{sierra2_4a}.
12709 When @var{bayer} dithering is selected, this option defines the scale of the
12710 pattern (how much the crosshatch pattern is visible). A low value means more
12711 visible pattern for less banding, and higher value means less visible pattern
12712 at the cost of more banding.
12714 The option must be an integer value in the range [0,5]. Default is @var{2}.
12717 If set, define the zone to process
12721 Only the changing rectangle will be reprocessed. This is similar to GIF
12722 cropping/offsetting compression mechanism. This option can be useful for speed
12723 if only a part of the image is changing, and has use cases such as limiting the
12724 scope of the error diffusal @option{dither} to the rectangle that bounds the
12725 moving scene (it leads to more deterministic output if the scene doesn't change
12726 much, and as a result less moving noise and better GIF compression).
12729 Default is @var{none}.
12732 Take new palette for each output frame.
12734 @item alpha_threshold
12735 Sets the alpha threshold for transparency. Alpha values above this threshold
12736 will be treated as completely opaque, and values below this threshold will be
12737 treated as completely transparent.
12739 The option must be an integer value in the range [0,255]. Default is @var{128}.
12742 @subsection Examples
12746 Use a palette (generated for example with @ref{palettegen}) to encode a GIF
12747 using @command{ffmpeg}:
12749 ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
12753 @section perspective
12755 Correct perspective of video not recorded perpendicular to the screen.
12757 A description of the accepted parameters follows.
12768 Set coordinates expression for top left, top right, bottom left and bottom right corners.
12769 Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
12770 If the @code{sense} option is set to @code{source}, then the specified points will be sent
12771 to the corners of the destination. If the @code{sense} option is set to @code{destination},
12772 then the corners of the source will be sent to the specified coordinates.
12774 The expressions can use the following variables:
12779 the width and height of video frame.
12783 Output frame count.
12786 @item interpolation
12787 Set interpolation for perspective correction.
12789 It accepts the following values:
12795 Default value is @samp{linear}.
12798 Set interpretation of coordinate options.
12800 It accepts the following values:
12804 Send point in the source specified by the given coordinates to
12805 the corners of the destination.
12807 @item 1, destination
12809 Send the corners of the source to the point in the destination specified
12810 by the given coordinates.
12812 Default value is @samp{source}.
12816 Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
12818 It accepts the following values:
12821 only evaluate expressions once during the filter initialization or
12822 when a command is processed
12825 evaluate expressions for each incoming frame
12828 Default value is @samp{init}.
12833 Delay interlaced video by one field time so that the field order changes.
12835 The intended use is to fix PAL movies that have been captured with the
12836 opposite field order to the film-to-video transfer.
12838 A description of the accepted parameters follows.
12844 It accepts the following values:
12847 Capture field order top-first, transfer bottom-first.
12848 Filter will delay the bottom field.
12851 Capture field order bottom-first, transfer top-first.
12852 Filter will delay the top field.
12855 Capture and transfer with the same field order. This mode only exists
12856 for the documentation of the other options to refer to, but if you
12857 actually select it, the filter will faithfully do nothing.
12860 Capture field order determined automatically by field flags, transfer
12862 Filter selects among @samp{t} and @samp{b} modes on a frame by frame
12863 basis using field flags. If no field information is available,
12864 then this works just like @samp{u}.
12867 Capture unknown or varying, transfer opposite.
12868 Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
12869 analyzing the images and selecting the alternative that produces best
12870 match between the fields.
12873 Capture top-first, transfer unknown or varying.
12874 Filter selects among @samp{t} and @samp{p} using image analysis.
12877 Capture bottom-first, transfer unknown or varying.
12878 Filter selects among @samp{b} and @samp{p} using image analysis.
12881 Capture determined by field flags, transfer unknown or varying.
12882 Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
12883 image analysis. If no field information is available, then this works just
12884 like @samp{U}. This is the default mode.
12887 Both capture and transfer unknown or varying.
12888 Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
12892 @section pixdesctest
12894 Pixel format descriptor test filter, mainly useful for internal
12895 testing. The output video should be equal to the input video.
12899 format=monow, pixdesctest
12902 can be used to test the monowhite pixel format descriptor definition.
12906 Display sample values of color channels. Mainly useful for checking color
12907 and levels. Minimum supported resolution is 640x480.
12909 The filters accept the following options:
12913 Set scope X position, relative offset on X axis.
12916 Set scope Y position, relative offset on Y axis.
12925 Set window opacity. This window also holds statistics about pixel area.
12928 Set window X position, relative offset on X axis.
12931 Set window Y position, relative offset on Y axis.
12936 Enable the specified chain of postprocessing subfilters using libpostproc. This
12937 library should be automatically selected with a GPL build (@code{--enable-gpl}).
12938 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
12939 Each subfilter and some options have a short and a long name that can be used
12940 interchangeably, i.e. dr/dering are the same.
12942 The filters accept the following options:
12946 Set postprocessing subfilters string.
12949 All subfilters share common options to determine their scope:
12953 Honor the quality commands for this subfilter.
12956 Do chrominance filtering, too (default).
12959 Do luminance filtering only (no chrominance).
12962 Do chrominance filtering only (no luminance).
12965 These options can be appended after the subfilter name, separated by a '|'.
12967 Available subfilters are:
12970 @item hb/hdeblock[|difference[|flatness]]
12971 Horizontal deblocking filter
12974 Difference factor where higher values mean more deblocking (default: @code{32}).
12976 Flatness threshold where lower values mean more deblocking (default: @code{39}).
12979 @item vb/vdeblock[|difference[|flatness]]
12980 Vertical deblocking filter
12983 Difference factor where higher values mean more deblocking (default: @code{32}).
12985 Flatness threshold where lower values mean more deblocking (default: @code{39}).
12988 @item ha/hadeblock[|difference[|flatness]]
12989 Accurate horizontal deblocking filter
12992 Difference factor where higher values mean more deblocking (default: @code{32}).
12994 Flatness threshold where lower values mean more deblocking (default: @code{39}).
12997 @item va/vadeblock[|difference[|flatness]]
12998 Accurate vertical deblocking filter
13001 Difference factor where higher values mean more deblocking (default: @code{32}).
13003 Flatness threshold where lower values mean more deblocking (default: @code{39}).
13007 The horizontal and vertical deblocking filters share the difference and
13008 flatness values so you cannot set different horizontal and vertical
13012 @item h1/x1hdeblock
13013 Experimental horizontal deblocking filter
13015 @item v1/x1vdeblock
13016 Experimental vertical deblocking filter
13021 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
13024 larger -> stronger filtering
13026 larger -> stronger filtering
13028 larger -> stronger filtering
13031 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
13034 Stretch luminance to @code{0-255}.
13037 @item lb/linblenddeint
13038 Linear blend deinterlacing filter that deinterlaces the given block by
13039 filtering all lines with a @code{(1 2 1)} filter.
13041 @item li/linipoldeint
13042 Linear interpolating deinterlacing filter that deinterlaces the given block by
13043 linearly interpolating every second line.
13045 @item ci/cubicipoldeint
13046 Cubic interpolating deinterlacing filter deinterlaces the given block by
13047 cubically interpolating every second line.
13049 @item md/mediandeint
13050 Median deinterlacing filter that deinterlaces the given block by applying a
13051 median filter to every second line.
13053 @item fd/ffmpegdeint
13054 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
13055 second line with a @code{(-1 4 2 4 -1)} filter.
13058 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
13059 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
13061 @item fq/forceQuant[|quantizer]
13062 Overrides the quantizer table from the input with the constant quantizer you
13070 Default pp filter combination (@code{hb|a,vb|a,dr|a})
13073 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
13076 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
13079 @subsection Examples
13083 Apply horizontal and vertical deblocking, deringing and automatic
13084 brightness/contrast:
13090 Apply default filters without brightness/contrast correction:
13096 Apply default filters and temporal denoiser:
13098 pp=default/tmpnoise|1|2|3
13102 Apply deblocking on luminance only, and switch vertical deblocking on or off
13103 automatically depending on available CPU time:
13110 Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
13111 similar to spp = 6 with 7 point DCT, where only the center sample is
13114 The filter accepts the following options:
13118 Force a constant quantization parameter. It accepts an integer in range
13119 0 to 63. If not set, the filter will use the QP from the video stream
13123 Set thresholding mode. Available modes are:
13127 Set hard thresholding.
13129 Set soft thresholding (better de-ringing effect, but likely blurrier).
13131 Set medium thresholding (good results, default).
13135 @section premultiply
13136 Apply alpha premultiply effect to input video stream using first plane
13137 of second stream as alpha.
13139 Both streams must have same dimensions and same pixel format.
13141 The filter accepts the following option:
13145 Set which planes will be processed, unprocessed planes will be copied.
13146 By default value 0xf, all planes will be processed.
13149 Do not require 2nd input for processing, instead use alpha plane from input stream.
13153 Apply prewitt operator to input video stream.
13155 The filter accepts the following option:
13159 Set which planes will be processed, unprocessed planes will be copied.
13160 By default value 0xf, all planes will be processed.
13163 Set value which will be multiplied with filtered result.
13166 Set value which will be added to filtered result.
13169 @anchor{program_opencl}
13170 @section program_opencl
13172 Filter video using an OpenCL program.
13177 OpenCL program source file.
13180 Kernel name in program.
13183 Number of inputs to the filter. Defaults to 1.
13186 Size of output frames. Defaults to the same as the first input.
13190 The program source file must contain a kernel function with the given name,
13191 which will be run once for each plane of the output. Each run on a plane
13192 gets enqueued as a separate 2D global NDRange with one work-item for each
13193 pixel to be generated. The global ID offset for each work-item is therefore
13194 the coordinates of a pixel in the destination image.
13196 The kernel function needs to take the following arguments:
13199 Destination image, @var{__write_only image2d_t}.
13201 This image will become the output; the kernel should write all of it.
13203 Frame index, @var{unsigned int}.
13205 This is a counter starting from zero and increasing by one for each frame.
13207 Source images, @var{__read_only image2d_t}.
13209 These are the most recent images on each input. The kernel may read from
13210 them to generate the output, but they can't be written to.
13217 Copy the input to the output (output must be the same size as the input).
13219 __kernel void copy(__write_only image2d_t destination,
13220 unsigned int index,
13221 __read_only image2d_t source)
13223 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
13225 int2 location = (int2)(get_global_id(0), get_global_id(1));
13227 float4 value = read_imagef(source, sampler, location);
13229 write_imagef(destination, location, value);
13234 Apply a simple transformation, rotating the input by an amount increasing
13235 with the index counter. Pixel values are linearly interpolated by the
13236 sampler, and the output need not have the same dimensions as the input.
13238 __kernel void rotate_image(__write_only image2d_t dst,
13239 unsigned int index,
13240 __read_only image2d_t src)
13242 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
13243 CLK_FILTER_LINEAR);
13245 float angle = (float)index / 100.0f;
13247 float2 dst_dim = convert_float2(get_image_dim(dst));
13248 float2 src_dim = convert_float2(get_image_dim(src));
13250 float2 dst_cen = dst_dim / 2.0f;
13251 float2 src_cen = src_dim / 2.0f;
13253 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
13255 float2 dst_pos = convert_float2(dst_loc) - dst_cen;
13257 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
13258 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
13260 src_pos = src_pos * src_dim / dst_dim;
13262 float2 src_loc = src_pos + src_cen;
13264 if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
13265 src_loc.x > src_dim.x || src_loc.y > src_dim.y)
13266 write_imagef(dst, dst_loc, 0.5f);
13268 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
13273 Blend two inputs together, with the amount of each input used varying
13274 with the index counter.
13276 __kernel void blend_images(__write_only image2d_t dst,
13277 unsigned int index,
13278 __read_only image2d_t src1,
13279 __read_only image2d_t src2)
13281 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
13282 CLK_FILTER_LINEAR);
13284 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
13286 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
13287 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
13288 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
13290 float4 val1 = read_imagef(src1, sampler, src1_loc);
13291 float4 val2 = read_imagef(src2, sampler, src2_loc);
13293 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
13299 @section pseudocolor
13301 Alter frame colors in video with pseudocolors.
13303 This filter accept the following options:
13307 set pixel first component expression
13310 set pixel second component expression
13313 set pixel third component expression
13316 set pixel fourth component expression, corresponds to the alpha component
13319 set component to use as base for altering colors
13322 Each of them specifies the expression to use for computing the lookup table for
13323 the corresponding pixel component values.
13325 The expressions can contain the following constants and functions:
13330 The input width and height.
13333 The input value for the pixel component.
13335 @item ymin, umin, vmin, amin
13336 The minimum allowed component value.
13338 @item ymax, umax, vmax, amax
13339 The maximum allowed component value.
13342 All expressions default to "val".
13344 @subsection Examples
13348 Change too high luma values to gradient:
13350 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'"
13356 Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
13357 Ratio) between two input videos.
13359 This filter takes in input two input videos, the first input is
13360 considered the "main" source and is passed unchanged to the
13361 output. The second input is used as a "reference" video for computing
13364 Both video inputs must have the same resolution and pixel format for
13365 this filter to work correctly. Also it assumes that both inputs
13366 have the same number of frames, which are compared one by one.
13368 The obtained average PSNR is printed through the logging system.
13370 The filter stores the accumulated MSE (mean squared error) of each
13371 frame, and at the end of the processing it is averaged across all frames
13372 equally, and the following formula is applied to obtain the PSNR:
13375 PSNR = 10*log10(MAX^2/MSE)
13378 Where MAX is the average of the maximum values of each component of the
13381 The description of the accepted parameters follows.
13384 @item stats_file, f
13385 If specified the filter will use the named file to save the PSNR of
13386 each individual frame. When filename equals "-" the data is sent to
13389 @item stats_version
13390 Specifies which version of the stats file format to use. Details of
13391 each format are written below.
13392 Default value is 1.
13394 @item stats_add_max
13395 Determines whether the max value is output to the stats log.
13396 Default value is 0.
13397 Requires stats_version >= 2. If this is set and stats_version < 2,
13398 the filter will return an error.
13401 This filter also supports the @ref{framesync} options.
13403 The file printed if @var{stats_file} is selected, contains a sequence of
13404 key/value pairs of the form @var{key}:@var{value} for each compared
13407 If a @var{stats_version} greater than 1 is specified, a header line precedes
13408 the list of per-frame-pair stats, with key value pairs following the frame
13409 format with the following parameters:
13412 @item psnr_log_version
13413 The version of the log file format. Will match @var{stats_version}.
13416 A comma separated list of the per-frame-pair parameters included in
13420 A description of each shown per-frame-pair parameter follows:
13424 sequential number of the input frame, starting from 1
13427 Mean Square Error pixel-by-pixel average difference of the compared
13428 frames, averaged over all the image components.
13430 @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
13431 Mean Square Error pixel-by-pixel average difference of the compared
13432 frames for the component specified by the suffix.
13434 @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
13435 Peak Signal to Noise ratio of the compared frames for the component
13436 specified by the suffix.
13438 @item max_avg, max_y, max_u, max_v
13439 Maximum allowed value for each channel, and average over all
13445 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
13446 [main][ref] psnr="stats_file=stats.log" [out]
13449 On this example the input file being processed is compared with the
13450 reference file @file{ref_movie.mpg}. The PSNR of each individual frame
13451 is stored in @file{stats.log}.
13456 Pulldown reversal (inverse telecine) filter, capable of handling mixed
13457 hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
13460 The pullup filter is designed to take advantage of future context in making
13461 its decisions. This filter is stateless in the sense that it does not lock
13462 onto a pattern to follow, but it instead looks forward to the following
13463 fields in order to identify matches and rebuild progressive frames.
13465 To produce content with an even framerate, insert the fps filter after
13466 pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
13467 @code{fps=24} for 30fps and the (rare) telecined 25fps input.
13469 The filter accepts the following options:
13476 These options set the amount of "junk" to ignore at the left, right, top, and
13477 bottom of the image, respectively. Left and right are in units of 8 pixels,
13478 while top and bottom are in units of 2 lines.
13479 The default is 8 pixels on each side.
13482 Set the strict breaks. Setting this option to 1 will reduce the chances of
13483 filter generating an occasional mismatched frame, but it may also cause an
13484 excessive number of frames to be dropped during high motion sequences.
13485 Conversely, setting it to -1 will make filter match fields more easily.
13486 This may help processing of video where there is slight blurring between
13487 the fields, but may also cause there to be interlaced frames in the output.
13488 Default value is @code{0}.
13491 Set the metric plane to use. It accepts the following values:
13497 Use chroma blue plane.
13500 Use chroma red plane.
13503 This option may be set to use chroma plane instead of the default luma plane
13504 for doing filter's computations. This may improve accuracy on very clean
13505 source material, but more likely will decrease accuracy, especially if there
13506 is chroma noise (rainbow effect) or any grayscale video.
13507 The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
13508 load and make pullup usable in realtime on slow machines.
13511 For best results (without duplicated frames in the output file) it is
13512 necessary to change the output frame rate. For example, to inverse
13513 telecine NTSC input:
13515 ffmpeg -i input -vf pullup -r 24000/1001 ...
13520 Change video quantization parameters (QP).
13522 The filter accepts the following option:
13526 Set expression for quantization parameter.
13529 The expression is evaluated through the eval API and can contain, among others,
13530 the following constants:
13534 1 if index is not 129, 0 otherwise.
13537 Sequential index starting from -129 to 128.
13540 @subsection Examples
13544 Some equation like:
13552 Flush video frames from internal cache of frames into a random order.
13553 No frame is discarded.
13554 Inspired by @ref{frei0r} nervous filter.
13558 Set size in number of frames of internal cache, in range from @code{2} to
13559 @code{512}. Default is @code{30}.
13562 Set seed for random number generator, must be an integer included between
13563 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
13564 less than @code{0}, the filter will try to use a good random seed on a
13568 @section readeia608
13570 Read closed captioning (EIA-608) information from the top lines of a video frame.
13572 This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and
13573 @code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line
13574 with EIA-608 data (starting from 0). A description of each metadata value follows:
13577 @item lavfi.readeia608.X.cc
13578 The two bytes stored as EIA-608 data (printed in hexadecimal).
13580 @item lavfi.readeia608.X.line
13581 The number of the line on which the EIA-608 data was identified and read.
13584 This filter accepts the following options:
13588 Set the line to start scanning for EIA-608 data. Default is @code{0}.
13591 Set the line to end scanning for EIA-608 data. Default is @code{29}.
13594 Set minimal acceptable amplitude change for sync codes detection.
13595 Default is @code{0.2}. Allowed range is @code{[0.001 - 1]}.
13598 Set the ratio of width reserved for sync code detection.
13599 Default is @code{0.27}. Allowed range is @code{[0.01 - 0.7]}.
13602 Set the max peaks height difference for sync code detection.
13603 Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
13606 Set max peaks period difference for sync code detection.
13607 Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
13610 Set the first two max start code bits differences.
13611 Default is @code{0.02}. Allowed range is @code{[0.0 - 0.5]}.
13614 Set the minimum ratio of bits height compared to 3rd start code bit.
13615 Default is @code{0.75}. Allowed range is @code{[0.01 - 1]}.
13618 Set the white color threshold. Default is @code{0.35}. Allowed range is @code{[0.1 - 1]}.
13621 Set the black color threshold. Default is @code{0.15}. Allowed range is @code{[0.0 - 0.5]}.
13624 Enable checking the parity bit. In the event of a parity error, the filter will output
13625 @code{0x00} for that character. Default is false.
13628 @subsection Examples
13632 Output a csv with presentation time and the first two lines of identified EIA-608 captioning data.
13634 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
13640 Read vertical interval timecode (VITC) information from the top lines of a
13643 The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
13644 timecode value, if a valid timecode has been detected. Further metadata key
13645 @code{lavfi.readvitc.found} is set to 0/1 depending on whether
13646 timecode data has been found or not.
13648 This filter accepts the following options:
13652 Set the maximum number of lines to scan for VITC data. If the value is set to
13653 @code{-1} the full video frame is scanned. Default is @code{45}.
13656 Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
13657 default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
13660 Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
13661 default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
13664 @subsection Examples
13668 Detect and draw VITC data onto the video frame; if no valid VITC is detected,
13669 draw @code{--:--:--:--} as a placeholder:
13671 ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
13677 Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
13679 Destination pixel at position (X, Y) will be picked from source (x, y) position
13680 where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
13681 value for pixel will be used for destination pixel.
13683 Xmap and Ymap input video streams must be of same dimensions. Output video stream
13684 will have Xmap/Ymap video stream dimensions.
13685 Xmap and Ymap input video streams are 16bit depth, single channel.
13687 @section removegrain
13689 The removegrain filter is a spatial denoiser for progressive video.
13693 Set mode for the first plane.
13696 Set mode for the second plane.
13699 Set mode for the third plane.
13702 Set mode for the fourth plane.
13705 Range of mode is from 0 to 24. Description of each mode follows:
13709 Leave input plane unchanged. Default.
13712 Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
13715 Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
13718 Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
13721 Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
13722 This is equivalent to a median filter.
13725 Line-sensitive clipping giving the minimal change.
13728 Line-sensitive clipping, intermediate.
13731 Line-sensitive clipping, intermediate.
13734 Line-sensitive clipping, intermediate.
13737 Line-sensitive clipping on a line where the neighbours pixels are the closest.
13740 Replaces the target pixel with the closest neighbour.
13743 [1 2 1] horizontal and vertical kernel blur.
13749 Bob mode, interpolates top field from the line where the neighbours
13750 pixels are the closest.
13753 Bob mode, interpolates bottom field from the line where the neighbours
13754 pixels are the closest.
13757 Bob mode, interpolates top field. Same as 13 but with a more complicated
13758 interpolation formula.
13761 Bob mode, interpolates bottom field. Same as 14 but with a more complicated
13762 interpolation formula.
13765 Clips the pixel with the minimum and maximum of respectively the maximum and
13766 minimum of each pair of opposite neighbour pixels.
13769 Line-sensitive clipping using opposite neighbours whose greatest distance from
13770 the current pixel is minimal.
13773 Replaces the pixel with the average of its 8 neighbours.
13776 Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
13779 Clips pixels using the averages of opposite neighbour.
13782 Same as mode 21 but simpler and faster.
13785 Small edge and halo removal, but reputed useless.
13791 @section removelogo
13793 Suppress a TV station logo, using an image file to determine which
13794 pixels comprise the logo. It works by filling in the pixels that
13795 comprise the logo with neighboring pixels.
13797 The filter accepts the following options:
13801 Set the filter bitmap file, which can be any image format supported by
13802 libavformat. The width and height of the image file must match those of the
13803 video stream being processed.
13806 Pixels in the provided bitmap image with a value of zero are not
13807 considered part of the logo, non-zero pixels are considered part of
13808 the logo. If you use white (255) for the logo and black (0) for the
13809 rest, you will be safe. For making the filter bitmap, it is
13810 recommended to take a screen capture of a black frame with the logo
13811 visible, and then using a threshold filter followed by the erode
13812 filter once or twice.
13814 If needed, little splotches can be fixed manually. Remember that if
13815 logo pixels are not covered, the filter quality will be much
13816 reduced. Marking too many pixels as part of the logo does not hurt as
13817 much, but it will increase the amount of blurring needed to cover over
13818 the image and will destroy more information than necessary, and extra
13819 pixels will slow things down on a large logo.
13821 @section repeatfields
13823 This filter uses the repeat_field flag from the Video ES headers and hard repeats
13824 fields based on its value.
13828 Reverse a video clip.
13830 Warning: This filter requires memory to buffer the entire clip, so trimming
13833 @subsection Examples
13837 Take the first 5 seconds of a clip, and reverse it.
13844 Apply roberts cross operator to input video stream.
13846 The filter accepts the following option:
13850 Set which planes will be processed, unprocessed planes will be copied.
13851 By default value 0xf, all planes will be processed.
13854 Set value which will be multiplied with filtered result.
13857 Set value which will be added to filtered result.
13862 Rotate video by an arbitrary angle expressed in radians.
13864 The filter accepts the following options:
13866 A description of the optional parameters follows.
13869 Set an expression for the angle by which to rotate the input video
13870 clockwise, expressed as a number of radians. A negative value will
13871 result in a counter-clockwise rotation. By default it is set to "0".
13873 This expression is evaluated for each frame.
13876 Set the output width expression, default value is "iw".
13877 This expression is evaluated just once during configuration.
13880 Set the output height expression, default value is "ih".
13881 This expression is evaluated just once during configuration.
13884 Enable bilinear interpolation if set to 1, a value of 0 disables
13885 it. Default value is 1.
13888 Set the color used to fill the output area not covered by the rotated
13889 image. For the general syntax of this option, check the
13890 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
13891 If the special value "none" is selected then no
13892 background is printed (useful for example if the background is never shown).
13894 Default value is "black".
13897 The expressions for the angle and the output size can contain the
13898 following constants and functions:
13902 sequential number of the input frame, starting from 0. It is always NAN
13903 before the first frame is filtered.
13906 time in seconds of the input frame, it is set to 0 when the filter is
13907 configured. It is always NAN before the first frame is filtered.
13911 horizontal and vertical chroma subsample values. For example for the
13912 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
13916 the input video width and height
13920 the output width and height, that is the size of the padded area as
13921 specified by the @var{width} and @var{height} expressions
13925 the minimal width/height required for completely containing the input
13926 video rotated by @var{a} radians.
13928 These are only available when computing the @option{out_w} and
13929 @option{out_h} expressions.
13932 @subsection Examples
13936 Rotate the input by PI/6 radians clockwise:
13942 Rotate the input by PI/6 radians counter-clockwise:
13948 Rotate the input by 45 degrees clockwise:
13954 Apply a constant rotation with period T, starting from an angle of PI/3:
13956 rotate=PI/3+2*PI*t/T
13960 Make the input video rotation oscillating with a period of T
13961 seconds and an amplitude of A radians:
13963 rotate=A*sin(2*PI/T*t)
13967 Rotate the video, output size is chosen so that the whole rotating
13968 input video is always completely contained in the output:
13970 rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
13974 Rotate the video, reduce the output size so that no background is ever
13977 rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
13981 @subsection Commands
13983 The filter supports the following commands:
13987 Set the angle expression.
13988 The command accepts the same syntax of the corresponding option.
13990 If the specified expression is not valid, it is kept at its current
13996 Apply Shape Adaptive Blur.
13998 The filter accepts the following options:
14001 @item luma_radius, lr
14002 Set luma blur filter strength, must be a value in range 0.1-4.0, default
14003 value is 1.0. A greater value will result in a more blurred image, and
14004 in slower processing.
14006 @item luma_pre_filter_radius, lpfr
14007 Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
14010 @item luma_strength, ls
14011 Set luma maximum difference between pixels to still be considered, must
14012 be a value in the 0.1-100.0 range, default value is 1.0.
14014 @item chroma_radius, cr
14015 Set chroma blur filter strength, must be a value in range -0.9-4.0. A
14016 greater value will result in a more blurred image, and in slower
14019 @item chroma_pre_filter_radius, cpfr
14020 Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
14022 @item chroma_strength, cs
14023 Set chroma maximum difference between pixels to still be considered,
14024 must be a value in the -0.9-100.0 range.
14027 Each chroma option value, if not explicitly specified, is set to the
14028 corresponding luma option value.
14033 Scale (resize) the input video, using the libswscale library.
14035 The scale filter forces the output display aspect ratio to be the same
14036 of the input, by changing the output sample aspect ratio.
14038 If the input image format is different from the format requested by
14039 the next filter, the scale filter will convert the input to the
14042 @subsection Options
14043 The filter accepts the following options, or any of the options
14044 supported by the libswscale scaler.
14046 See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
14047 the complete list of scaler options.
14052 Set the output video dimension expression. Default value is the input
14055 If the @var{width} or @var{w} value is 0, the input width is used for
14056 the output. If the @var{height} or @var{h} value is 0, the input height
14057 is used for the output.
14059 If one and only one of the values is -n with n >= 1, the scale filter
14060 will use a value that maintains the aspect ratio of the input image,
14061 calculated from the other specified dimension. After that it will,
14062 however, make sure that the calculated dimension is divisible by n and
14063 adjust the value if necessary.
14065 If both values are -n with n >= 1, the behavior will be identical to
14066 both values being set to 0 as previously detailed.
14068 See below for the list of accepted constants for use in the dimension
14072 Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
14076 Only evaluate expressions once during the filter initialization or when a command is processed.
14079 Evaluate expressions for each incoming frame.
14083 Default value is @samp{init}.
14087 Set the interlacing mode. It accepts the following values:
14091 Force interlaced aware scaling.
14094 Do not apply interlaced scaling.
14097 Select interlaced aware scaling depending on whether the source frames
14098 are flagged as interlaced or not.
14101 Default value is @samp{0}.
14104 Set libswscale scaling flags. See
14105 @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
14106 complete list of values. If not explicitly specified the filter applies
14110 @item param0, param1
14111 Set libswscale input parameters for scaling algorithms that need them. See
14112 @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
14113 complete documentation. If not explicitly specified the filter applies
14119 Set the video size. For the syntax of this option, check the
14120 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
14122 @item in_color_matrix
14123 @item out_color_matrix
14124 Set in/output YCbCr color space type.
14126 This allows the autodetected value to be overridden as well as allows forcing
14127 a specific value used for the output and encoder.
14129 If not specified, the color space type depends on the pixel format.
14135 Choose automatically.
14138 Format conforming to International Telecommunication Union (ITU)
14139 Recommendation BT.709.
14142 Set color space conforming to the United States Federal Communications
14143 Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
14146 Set color space conforming to:
14150 ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
14153 ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
14156 Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
14161 Set color space conforming to SMPTE ST 240:1999.
14166 Set in/output YCbCr sample range.
14168 This allows the autodetected value to be overridden as well as allows forcing
14169 a specific value used for the output and encoder. If not specified, the
14170 range depends on the pixel format. Possible values:
14174 Choose automatically.
14177 Set full range (0-255 in case of 8-bit luma).
14179 @item mpeg/limited/tv
14180 Set "MPEG" range (16-235 in case of 8-bit luma).
14183 @item force_original_aspect_ratio
14184 Enable decreasing or increasing output video width or height if necessary to
14185 keep the original aspect ratio. Possible values:
14189 Scale the video as specified and disable this feature.
14192 The output video dimensions will automatically be decreased if needed.
14195 The output video dimensions will automatically be increased if needed.
14199 One useful instance of this option is that when you know a specific device's
14200 maximum allowed resolution, you can use this to limit the output video to
14201 that, while retaining the aspect ratio. For example, device A allows
14202 1280x720 playback, and your video is 1920x800. Using this option (set it to
14203 decrease) and specifying 1280x720 to the command line makes the output
14206 Please note that this is a different thing than specifying -1 for @option{w}
14207 or @option{h}, you still need to specify the output resolution for this option
14212 The values of the @option{w} and @option{h} options are expressions
14213 containing the following constants:
14218 The input width and height
14222 These are the same as @var{in_w} and @var{in_h}.
14226 The output (scaled) width and height
14230 These are the same as @var{out_w} and @var{out_h}
14233 The same as @var{iw} / @var{ih}
14236 input sample aspect ratio
14239 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
14243 horizontal and vertical input chroma subsample values. For example for the
14244 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14248 horizontal and vertical output chroma subsample values. For example for the
14249 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14252 @subsection Examples
14256 Scale the input video to a size of 200x100
14261 This is equivalent to:
14272 Specify a size abbreviation for the output size:
14277 which can also be written as:
14283 Scale the input to 2x:
14285 scale=w=2*iw:h=2*ih
14289 The above is the same as:
14291 scale=2*in_w:2*in_h
14295 Scale the input to 2x with forced interlaced scaling:
14297 scale=2*iw:2*ih:interl=1
14301 Scale the input to half size:
14303 scale=w=iw/2:h=ih/2
14307 Increase the width, and set the height to the same size:
14313 Seek Greek harmony:
14320 Increase the height, and set the width to 3/2 of the height:
14322 scale=w=3/2*oh:h=3/5*ih
14326 Increase the size, making the size a multiple of the chroma
14329 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
14333 Increase the width to a maximum of 500 pixels,
14334 keeping the same aspect ratio as the input:
14336 scale=w='min(500\, iw*3/2):h=-1'
14340 Make pixels square by combining scale and setsar:
14342 scale='trunc(ih*dar):ih',setsar=1/1
14346 Make pixels square by combining scale and setsar,
14347 making sure the resulting resolution is even (required by some codecs):
14349 scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1
14353 @subsection Commands
14355 This filter supports the following commands:
14359 Set the output video dimension expression.
14360 The command accepts the same syntax of the corresponding option.
14362 If the specified expression is not valid, it is kept at its current
14368 Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
14369 format conversion on CUDA video frames. Setting the output width and height
14370 works in the same way as for the @var{scale} filter.
14372 The following additional options are accepted:
14375 The pixel format of the output CUDA frames. If set to the string "same" (the
14376 default), the input format will be kept. Note that automatic format negotiation
14377 and conversion is not yet supported for hardware frames
14380 The interpolation algorithm used for resizing. One of the following:
14387 @item cubic2p_bspline
14388 2-parameter cubic (B=1, C=0)
14390 @item cubic2p_catmullrom
14391 2-parameter cubic (B=0, C=1/2)
14393 @item cubic2p_b05c03
14394 2-parameter cubic (B=1/2, C=3/10)
14406 Scale (resize) the input video, based on a reference video.
14408 See the scale filter for available options, scale2ref supports the same but
14409 uses the reference video instead of the main input as basis. scale2ref also
14410 supports the following additional constants for the @option{w} and
14411 @option{h} options:
14416 The main input video's width and height
14419 The same as @var{main_w} / @var{main_h}
14422 The main input video's sample aspect ratio
14424 @item main_dar, mdar
14425 The main input video's display aspect ratio. Calculated from
14426 @code{(main_w / main_h) * main_sar}.
14430 The main input video's horizontal and vertical chroma subsample values.
14431 For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub}
14435 @subsection Examples
14439 Scale a subtitle stream (b) to match the main video (a) in size before overlaying
14441 'scale2ref[b][a];[a][b]overlay'
14445 @anchor{selectivecolor}
14446 @section selectivecolor
14448 Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
14449 as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
14450 by the "purity" of the color (that is, how saturated it already is).
14452 This filter is similar to the Adobe Photoshop Selective Color tool.
14454 The filter accepts the following options:
14457 @item correction_method
14458 Select color correction method.
14460 Available values are:
14463 Specified adjustments are applied "as-is" (added/subtracted to original pixel
14466 Specified adjustments are relative to the original component value.
14468 Default is @code{absolute}.
14470 Adjustments for red pixels (pixels where the red component is the maximum)
14472 Adjustments for yellow pixels (pixels where the blue component is the minimum)
14474 Adjustments for green pixels (pixels where the green component is the maximum)
14476 Adjustments for cyan pixels (pixels where the red component is the minimum)
14478 Adjustments for blue pixels (pixels where the blue component is the maximum)
14480 Adjustments for magenta pixels (pixels where the green component is the minimum)
14482 Adjustments for white pixels (pixels where all components are greater than 128)
14484 Adjustments for all pixels except pure black and pure white
14486 Adjustments for black pixels (pixels where all components are lesser than 128)
14488 Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
14491 All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
14492 4 space separated floating point adjustment values in the [-1,1] range,
14493 respectively to adjust the amount of cyan, magenta, yellow and black for the
14494 pixels of its range.
14496 @subsection Examples
14500 Increase cyan by 50% and reduce yellow by 33% in every green areas, and
14501 increase magenta by 27% in blue areas:
14503 selectivecolor=greens=.5 0 -.33 0:blues=0 .27
14507 Use a Photoshop selective color preset:
14509 selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
14513 @anchor{separatefields}
14514 @section separatefields
14516 The @code{separatefields} takes a frame-based video input and splits
14517 each frame into its components fields, producing a new half height clip
14518 with twice the frame rate and twice the frame count.
14520 This filter use field-dominance information in frame to decide which
14521 of each pair of fields to place first in the output.
14522 If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
14524 @section setdar, setsar
14526 The @code{setdar} filter sets the Display Aspect Ratio for the filter
14529 This is done by changing the specified Sample (aka Pixel) Aspect
14530 Ratio, according to the following equation:
14532 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
14535 Keep in mind that the @code{setdar} filter does not modify the pixel
14536 dimensions of the video frame. Also, the display aspect ratio set by
14537 this filter may be changed by later filters in the filterchain,
14538 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
14541 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
14542 the filter output video.
14544 Note that as a consequence of the application of this filter, the
14545 output display aspect ratio will change according to the equation
14548 Keep in mind that the sample aspect ratio set by the @code{setsar}
14549 filter may be changed by later filters in the filterchain, e.g. if
14550 another "setsar" or a "setdar" filter is applied.
14552 It accepts the following parameters:
14555 @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
14556 Set the aspect ratio used by the filter.
14558 The parameter can be a floating point number string, an expression, or
14559 a string of the form @var{num}:@var{den}, where @var{num} and
14560 @var{den} are the numerator and denominator of the aspect ratio. If
14561 the parameter is not specified, it is assumed the value "0".
14562 In case the form "@var{num}:@var{den}" is used, the @code{:} character
14566 Set the maximum integer value to use for expressing numerator and
14567 denominator when reducing the expressed aspect ratio to a rational.
14568 Default value is @code{100}.
14572 The parameter @var{sar} is an expression containing
14573 the following constants:
14577 These are approximated values for the mathematical constants e
14578 (Euler's number), pi (Greek pi), and phi (the golden ratio).
14581 The input width and height.
14584 These are the same as @var{w} / @var{h}.
14587 The input sample aspect ratio.
14590 The input display aspect ratio. It is the same as
14591 (@var{w} / @var{h}) * @var{sar}.
14594 Horizontal and vertical chroma subsample values. For example, for the
14595 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14598 @subsection Examples
14603 To change the display aspect ratio to 16:9, specify one of the following:
14610 To change the sample aspect ratio to 10:11, specify:
14616 To set a display aspect ratio of 16:9, and specify a maximum integer value of
14617 1000 in the aspect ratio reduction, use the command:
14619 setdar=ratio=16/9:max=1000
14627 Force field for the output video frame.
14629 The @code{setfield} filter marks the interlace type field for the
14630 output frames. It does not change the input frame, but only sets the
14631 corresponding property, which affects how the frame is treated by
14632 following filters (e.g. @code{fieldorder} or @code{yadif}).
14634 The filter accepts the following options:
14639 Available values are:
14643 Keep the same field property.
14646 Mark the frame as bottom-field-first.
14649 Mark the frame as top-field-first.
14652 Mark the frame as progressive.
14658 Show a line containing various information for each input video frame.
14659 The input video is not modified.
14661 The shown line contains a sequence of key/value pairs of the form
14662 @var{key}:@var{value}.
14664 The following values are shown in the output:
14668 The (sequential) number of the input frame, starting from 0.
14671 The Presentation TimeStamp of the input frame, expressed as a number of
14672 time base units. The time base unit depends on the filter input pad.
14675 The Presentation TimeStamp of the input frame, expressed as a number of
14679 The position of the frame in the input stream, or -1 if this information is
14680 unavailable and/or meaningless (for example in case of synthetic video).
14683 The pixel format name.
14686 The sample aspect ratio of the input frame, expressed in the form
14687 @var{num}/@var{den}.
14690 The size of the input frame. For the syntax of this option, check the
14691 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
14694 The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
14695 for bottom field first).
14698 This is 1 if the frame is a key frame, 0 otherwise.
14701 The picture type of the input frame ("I" for an I-frame, "P" for a
14702 P-frame, "B" for a B-frame, or "?" for an unknown type).
14703 Also refer to the documentation of the @code{AVPictureType} enum and of
14704 the @code{av_get_picture_type_char} function defined in
14705 @file{libavutil/avutil.h}.
14708 The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
14710 @item plane_checksum
14711 The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
14712 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
14715 @section showpalette
14717 Displays the 256 colors palette of each frame. This filter is only relevant for
14718 @var{pal8} pixel format frames.
14720 It accepts the following option:
14724 Set the size of the box used to represent one palette color entry. Default is
14725 @code{30} (for a @code{30x30} pixel box).
14728 @section shuffleframes
14730 Reorder and/or duplicate and/or drop video frames.
14732 It accepts the following parameters:
14736 Set the destination indexes of input frames.
14737 This is space or '|' separated list of indexes that maps input frames to output
14738 frames. Number of indexes also sets maximal value that each index may have.
14739 '-1' index have special meaning and that is to drop frame.
14742 The first frame has the index 0. The default is to keep the input unchanged.
14744 @subsection Examples
14748 Swap second and third frame of every three frames of the input:
14750 ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
14754 Swap 10th and 1st frame of every ten frames of the input:
14756 ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
14760 @section shuffleplanes
14762 Reorder and/or duplicate video planes.
14764 It accepts the following parameters:
14769 The index of the input plane to be used as the first output plane.
14772 The index of the input plane to be used as the second output plane.
14775 The index of the input plane to be used as the third output plane.
14778 The index of the input plane to be used as the fourth output plane.
14782 The first plane has the index 0. The default is to keep the input unchanged.
14784 @subsection Examples
14788 Swap the second and third planes of the input:
14790 ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
14794 @anchor{signalstats}
14795 @section signalstats
14796 Evaluate various visual metrics that assist in determining issues associated
14797 with the digitization of analog video media.
14799 By default the filter will log these metadata values:
14803 Display the minimal Y value contained within the input frame. Expressed in
14807 Display the Y value at the 10% percentile within the input frame. Expressed in
14811 Display the average Y value within the input frame. Expressed in range of
14815 Display the Y value at the 90% percentile within the input frame. Expressed in
14819 Display the maximum Y value contained within the input frame. Expressed in
14823 Display the minimal U value contained within the input frame. Expressed in
14827 Display the U value at the 10% percentile within the input frame. Expressed in
14831 Display the average U value within the input frame. Expressed in range of
14835 Display the U value at the 90% percentile within the input frame. Expressed in
14839 Display the maximum U value contained within the input frame. Expressed in
14843 Display the minimal V value contained within the input frame. Expressed in
14847 Display the V value at the 10% percentile within the input frame. Expressed in
14851 Display the average V value within the input frame. Expressed in range of
14855 Display the V value at the 90% percentile within the input frame. Expressed in
14859 Display the maximum V value contained within the input frame. Expressed in
14863 Display the minimal saturation value contained within the input frame.
14864 Expressed in range of [0-~181.02].
14867 Display the saturation value at the 10% percentile within the input frame.
14868 Expressed in range of [0-~181.02].
14871 Display the average saturation value within the input frame. Expressed in range
14875 Display the saturation value at the 90% percentile within the input frame.
14876 Expressed in range of [0-~181.02].
14879 Display the maximum saturation value contained within the input frame.
14880 Expressed in range of [0-~181.02].
14883 Display the median value for hue within the input frame. Expressed in range of
14887 Display the average value for hue within the input frame. Expressed in range of
14891 Display the average of sample value difference between all values of the Y
14892 plane in the current frame and corresponding values of the previous input frame.
14893 Expressed in range of [0-255].
14896 Display the average of sample value difference between all values of the U
14897 plane in the current frame and corresponding values of the previous input frame.
14898 Expressed in range of [0-255].
14901 Display the average of sample value difference between all values of the V
14902 plane in the current frame and corresponding values of the previous input frame.
14903 Expressed in range of [0-255].
14906 Display bit depth of Y plane in current frame.
14907 Expressed in range of [0-16].
14910 Display bit depth of U plane in current frame.
14911 Expressed in range of [0-16].
14914 Display bit depth of V plane in current frame.
14915 Expressed in range of [0-16].
14918 The filter accepts the following options:
14924 @option{stat} specify an additional form of image analysis.
14925 @option{out} output video with the specified type of pixel highlighted.
14927 Both options accept the following values:
14931 Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
14932 unlike the neighboring pixels of the same field. Examples of temporal outliers
14933 include the results of video dropouts, head clogs, or tape tracking issues.
14936 Identify @var{vertical line repetition}. Vertical line repetition includes
14937 similar rows of pixels within a frame. In born-digital video vertical line
14938 repetition is common, but this pattern is uncommon in video digitized from an
14939 analog source. When it occurs in video that results from the digitization of an
14940 analog source it can indicate concealment from a dropout compensator.
14943 Identify pixels that fall outside of legal broadcast range.
14947 Set the highlight color for the @option{out} option. The default color is
14951 @subsection Examples
14955 Output data of various video metrics:
14957 ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
14961 Output specific data about the minimum and maximum values of the Y plane per frame:
14963 ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
14967 Playback video while highlighting pixels that are outside of broadcast range in red.
14969 ffplay example.mov -vf signalstats="out=brng:color=red"
14973 Playback video with signalstats metadata drawn over the frame.
14975 ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
14978 The contents of signalstat_drawtext.txt used in the command are:
14981 Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
14982 U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
14983 V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
14984 saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
14992 Calculates the MPEG-7 Video Signature. The filter can handle more than one
14993 input. In this case the matching between the inputs can be calculated additionally.
14994 The filter always passes through the first input. The signature of each stream can
14995 be written into a file.
14997 It accepts the following options:
15001 Enable or disable the matching process.
15003 Available values are:
15007 Disable the calculation of a matching (default).
15009 Calculate the matching for the whole video and output whether the whole video
15010 matches or only parts.
15012 Calculate only until a matching is found or the video ends. Should be faster in
15017 Set the number of inputs. The option value must be a non negative integer.
15018 Default value is 1.
15021 Set the path to which the output is written. If there is more than one input,
15022 the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive
15023 integer), that will be replaced with the input number. If no filename is
15024 specified, no output will be written. This is the default.
15027 Choose the output format.
15029 Available values are:
15033 Use the specified binary representation (default).
15035 Use the specified xml representation.
15039 Set threshold to detect one word as similar. The option value must be an integer
15040 greater than zero. The default value is 9000.
15043 Set threshold to detect all words as similar. The option value must be an integer
15044 greater than zero. The default value is 60000.
15047 Set threshold to detect frames as similar. The option value must be an integer
15048 greater than zero. The default value is 116.
15051 Set the minimum length of a sequence in frames to recognize it as matching
15052 sequence. The option value must be a non negative integer value.
15053 The default value is 0.
15056 Set the minimum relation, that matching frames to all frames must have.
15057 The option value must be a double value between 0 and 1. The default value is 0.5.
15060 @subsection Examples
15064 To calculate the signature of an input video and store it in signature.bin:
15066 ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
15070 To detect whether two videos match and store the signatures in XML format in
15071 signature0.xml and signature1.xml:
15073 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 -
15081 Blur the input video without impacting the outlines.
15083 It accepts the following options:
15086 @item luma_radius, lr
15087 Set the luma radius. The option value must be a float number in
15088 the range [0.1,5.0] that specifies the variance of the gaussian filter
15089 used to blur the image (slower if larger). Default value is 1.0.
15091 @item luma_strength, ls
15092 Set the luma strength. The option value must be a float number
15093 in the range [-1.0,1.0] that configures the blurring. A value included
15094 in [0.0,1.0] will blur the image whereas a value included in
15095 [-1.0,0.0] will sharpen the image. Default value is 1.0.
15097 @item luma_threshold, lt
15098 Set the luma threshold used as a coefficient to determine
15099 whether a pixel should be blurred or not. The option value must be an
15100 integer in the range [-30,30]. A value of 0 will filter all the image,
15101 a value included in [0,30] will filter flat areas and a value included
15102 in [-30,0] will filter edges. Default value is 0.
15104 @item chroma_radius, cr
15105 Set the chroma radius. The option value must be a float number in
15106 the range [0.1,5.0] that specifies the variance of the gaussian filter
15107 used to blur the image (slower if larger). Default value is @option{luma_radius}.
15109 @item chroma_strength, cs
15110 Set the chroma strength. The option value must be a float number
15111 in the range [-1.0,1.0] that configures the blurring. A value included
15112 in [0.0,1.0] will blur the image whereas a value included in
15113 [-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}.
15115 @item chroma_threshold, ct
15116 Set the chroma threshold used as a coefficient to determine
15117 whether a pixel should be blurred or not. The option value must be an
15118 integer in the range [-30,30]. A value of 0 will filter all the image,
15119 a value included in [0,30] will filter flat areas and a value included
15120 in [-30,0] will filter edges. Default value is @option{luma_threshold}.
15123 If a chroma option is not explicitly set, the corresponding luma value
15128 Obtain the SSIM (Structural SImilarity Metric) between two input videos.
15130 This filter takes in input two input videos, the first input is
15131 considered the "main" source and is passed unchanged to the
15132 output. The second input is used as a "reference" video for computing
15135 Both video inputs must have the same resolution and pixel format for
15136 this filter to work correctly. Also it assumes that both inputs
15137 have the same number of frames, which are compared one by one.
15139 The filter stores the calculated SSIM of each frame.
15141 The description of the accepted parameters follows.
15144 @item stats_file, f
15145 If specified the filter will use the named file to save the SSIM of
15146 each individual frame. When filename equals "-" the data is sent to
15150 The file printed if @var{stats_file} is selected, contains a sequence of
15151 key/value pairs of the form @var{key}:@var{value} for each compared
15154 A description of each shown parameter follows:
15158 sequential number of the input frame, starting from 1
15160 @item Y, U, V, R, G, B
15161 SSIM of the compared frames for the component specified by the suffix.
15164 SSIM of the compared frames for the whole frame.
15167 Same as above but in dB representation.
15170 This filter also supports the @ref{framesync} options.
15174 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
15175 [main][ref] ssim="stats_file=stats.log" [out]
15178 On this example the input file being processed is compared with the
15179 reference file @file{ref_movie.mpg}. The SSIM of each individual frame
15180 is stored in @file{stats.log}.
15182 Another example with both psnr and ssim at same time:
15184 ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
15189 Convert between different stereoscopic image formats.
15191 The filters accept the following options:
15195 Set stereoscopic image format of input.
15197 Available values for input image formats are:
15200 side by side parallel (left eye left, right eye right)
15203 side by side crosseye (right eye left, left eye right)
15206 side by side parallel with half width resolution
15207 (left eye left, right eye right)
15210 side by side crosseye with half width resolution
15211 (right eye left, left eye right)
15214 above-below (left eye above, right eye below)
15217 above-below (right eye above, left eye below)
15220 above-below with half height resolution
15221 (left eye above, right eye below)
15224 above-below with half height resolution
15225 (right eye above, left eye below)
15228 alternating frames (left eye first, right eye second)
15231 alternating frames (right eye first, left eye second)
15234 interleaved rows (left eye has top row, right eye starts on next row)
15237 interleaved rows (right eye has top row, left eye starts on next row)
15240 interleaved columns, left eye first
15243 interleaved columns, right eye first
15245 Default value is @samp{sbsl}.
15249 Set stereoscopic image format of output.
15253 side by side parallel (left eye left, right eye right)
15256 side by side crosseye (right eye left, left eye right)
15259 side by side parallel with half width resolution
15260 (left eye left, right eye right)
15263 side by side crosseye with half width resolution
15264 (right eye left, left eye right)
15267 above-below (left eye above, right eye below)
15270 above-below (right eye above, left eye below)
15273 above-below with half height resolution
15274 (left eye above, right eye below)
15277 above-below with half height resolution
15278 (right eye above, left eye below)
15281 alternating frames (left eye first, right eye second)
15284 alternating frames (right eye first, left eye second)
15287 interleaved rows (left eye has top row, right eye starts on next row)
15290 interleaved rows (right eye has top row, left eye starts on next row)
15293 anaglyph red/blue gray
15294 (red filter on left eye, blue filter on right eye)
15297 anaglyph red/green gray
15298 (red filter on left eye, green filter on right eye)
15301 anaglyph red/cyan gray
15302 (red filter on left eye, cyan filter on right eye)
15305 anaglyph red/cyan half colored
15306 (red filter on left eye, cyan filter on right eye)
15309 anaglyph red/cyan color
15310 (red filter on left eye, cyan filter on right eye)
15313 anaglyph red/cyan color optimized with the least squares projection of dubois
15314 (red filter on left eye, cyan filter on right eye)
15317 anaglyph green/magenta gray
15318 (green filter on left eye, magenta filter on right eye)
15321 anaglyph green/magenta half colored
15322 (green filter on left eye, magenta filter on right eye)
15325 anaglyph green/magenta colored
15326 (green filter on left eye, magenta filter on right eye)
15329 anaglyph green/magenta color optimized with the least squares projection of dubois
15330 (green filter on left eye, magenta filter on right eye)
15333 anaglyph yellow/blue gray
15334 (yellow filter on left eye, blue filter on right eye)
15337 anaglyph yellow/blue half colored
15338 (yellow filter on left eye, blue filter on right eye)
15341 anaglyph yellow/blue colored
15342 (yellow filter on left eye, blue filter on right eye)
15345 anaglyph yellow/blue color optimized with the least squares projection of dubois
15346 (yellow filter on left eye, blue filter on right eye)
15349 mono output (left eye only)
15352 mono output (right eye only)
15355 checkerboard, left eye first
15358 checkerboard, right eye first
15361 interleaved columns, left eye first
15364 interleaved columns, right eye first
15370 Default value is @samp{arcd}.
15373 @subsection Examples
15377 Convert input video from side by side parallel to anaglyph yellow/blue dubois:
15383 Convert input video from above below (left eye above, right eye below) to side by side crosseye.
15389 @section streamselect, astreamselect
15390 Select video or audio streams.
15392 The filter accepts the following options:
15396 Set number of inputs. Default is 2.
15399 Set input indexes to remap to outputs.
15402 @subsection Commands
15404 The @code{streamselect} and @code{astreamselect} filter supports the following
15409 Set input indexes to remap to outputs.
15412 @subsection Examples
15416 Select first 5 seconds 1st stream and rest of time 2nd stream:
15418 sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
15422 Same as above, but for audio:
15424 asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
15429 Apply sobel operator to input video stream.
15431 The filter accepts the following option:
15435 Set which planes will be processed, unprocessed planes will be copied.
15436 By default value 0xf, all planes will be processed.
15439 Set value which will be multiplied with filtered result.
15442 Set value which will be added to filtered result.
15448 Apply a simple postprocessing filter that compresses and decompresses the image
15449 at several (or - in the case of @option{quality} level @code{6} - all) shifts
15450 and average the results.
15452 The filter accepts the following options:
15456 Set quality. This option defines the number of levels for averaging. It accepts
15457 an integer in the range 0-6. If set to @code{0}, the filter will have no
15458 effect. A value of @code{6} means the higher quality. For each increment of
15459 that value the speed drops by a factor of approximately 2. Default value is
15463 Force a constant quantization parameter. If not set, the filter will use the QP
15464 from the video stream (if available).
15467 Set thresholding mode. Available modes are:
15471 Set hard thresholding (default).
15473 Set soft thresholding (better de-ringing effect, but likely blurrier).
15476 @item use_bframe_qp
15477 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
15478 option may cause flicker since the B-Frames have often larger QP. Default is
15479 @code{0} (not enabled).
15484 Scale the input by applying one of the super-resolution methods based on
15485 convolutional neural networks.
15487 Training scripts as well as scripts for model generation are provided in
15488 the repository at @url{https://github.com/HighVoltageRocknRoll/sr.git}.
15490 The filter accepts the following options:
15494 Specify which super-resolution model to use. This option accepts the following values:
15498 Super-Resolution Convolutional Neural Network model.
15499 See @url{https://arxiv.org/abs/1501.00092}.
15502 Efficient Sub-Pixel Convolutional Neural Network model.
15503 See @url{https://arxiv.org/abs/1609.05158}.
15507 Default value is @samp{srcnn}.
15510 Specify which DNN backend to use for model loading and execution. This option accepts
15511 the following values:
15515 Native implementation of DNN loading and execution.
15518 TensorFlow backend. To enable this backend you
15519 need to install the TensorFlow for C library (see
15520 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
15521 @code{--enable-libtensorflow}
15525 Default value is @samp{native}.
15528 Set scale factor for SRCNN model, for which custom model file was provided.
15529 Allowed values are @code{2}, @code{3} and @code{4}. Default value is @code{2}.
15530 Scale factor is necessary for SRCNN model, because it accepts input upscaled
15531 using bicubic upscaling with proper scale factor.
15533 @item model_filename
15534 Set path to model file specifying network architecture and its parameters.
15535 Note that different backends use different file formats. TensorFlow backend
15536 can load files for both formats, while native backend can load files for only
15544 Draw subtitles on top of input video using the libass library.
15546 To enable compilation of this filter you need to configure FFmpeg with
15547 @code{--enable-libass}. This filter also requires a build with libavcodec and
15548 libavformat to convert the passed subtitles file to ASS (Advanced Substation
15549 Alpha) subtitles format.
15551 The filter accepts the following options:
15555 Set the filename of the subtitle file to read. It must be specified.
15557 @item original_size
15558 Specify the size of the original video, the video for which the ASS file
15559 was composed. For the syntax of this option, check the
15560 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15561 Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
15562 correctly scale the fonts if the aspect ratio has been changed.
15565 Set a directory path containing fonts that can be used by the filter.
15566 These fonts will be used in addition to whatever the font provider uses.
15569 Process alpha channel, by default alpha channel is untouched.
15572 Set subtitles input character encoding. @code{subtitles} filter only. Only
15573 useful if not UTF-8.
15575 @item stream_index, si
15576 Set subtitles stream index. @code{subtitles} filter only.
15579 Override default style or script info parameters of the subtitles. It accepts a
15580 string containing ASS style format @code{KEY=VALUE} couples separated by ",".
15583 If the first key is not specified, it is assumed that the first value
15584 specifies the @option{filename}.
15586 For example, to render the file @file{sub.srt} on top of the input
15587 video, use the command:
15592 which is equivalent to:
15594 subtitles=filename=sub.srt
15597 To render the default subtitles stream from file @file{video.mkv}, use:
15599 subtitles=video.mkv
15602 To render the second subtitles stream from that file, use:
15604 subtitles=video.mkv:si=1
15607 To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue
15608 @code{DejaVu Serif}, use:
15610 subtitles=sub.srt:force_style='FontName=DejaVu Serif,PrimaryColour=&HCCFF0000'
15613 @section super2xsai
15615 Scale the input by 2x and smooth using the Super2xSaI (Scale and
15616 Interpolate) pixel art scaling algorithm.
15618 Useful for enlarging pixel art images without reducing sharpness.
15622 Swap two rectangular objects in video.
15624 This filter accepts the following options:
15634 Set 1st rect x coordinate.
15637 Set 1st rect y coordinate.
15640 Set 2nd rect x coordinate.
15643 Set 2nd rect y coordinate.
15645 All expressions are evaluated once for each frame.
15648 The all options are expressions containing the following constants:
15653 The input width and height.
15656 same as @var{w} / @var{h}
15659 input sample aspect ratio
15662 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
15665 The number of the input frame, starting from 0.
15668 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
15671 the position in the file of the input frame, NAN if unknown
15679 Apply telecine process to the video.
15681 This filter accepts the following options:
15690 The default value is @code{top}.
15694 A string of numbers representing the pulldown pattern you wish to apply.
15695 The default value is @code{23}.
15699 Some typical patterns:
15704 24p: 2332 (preferred)
15711 24p: 222222222223 ("Euro pulldown")
15718 Apply threshold effect to video stream.
15720 This filter needs four video streams to perform thresholding.
15721 First stream is stream we are filtering.
15722 Second stream is holding threshold values, third stream is holding min values,
15723 and last, fourth stream is holding max values.
15725 The filter accepts the following option:
15729 Set which planes will be processed, unprocessed planes will be copied.
15730 By default value 0xf, all planes will be processed.
15733 For example if first stream pixel's component value is less then threshold value
15734 of pixel component from 2nd threshold stream, third stream value will picked,
15735 otherwise fourth stream pixel component value will be picked.
15737 Using color source filter one can perform various types of thresholding:
15739 @subsection Examples
15743 Binary threshold, using gray color as threshold:
15745 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
15749 Inverted binary threshold, using gray color as threshold:
15751 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
15755 Truncate binary threshold, using gray color as threshold:
15757 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
15761 Threshold to zero, using gray color as threshold:
15763 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
15767 Inverted threshold to zero, using gray color as threshold:
15769 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
15774 Select the most representative frame in a given sequence of consecutive frames.
15776 The filter accepts the following options:
15780 Set the frames batch size to analyze; in a set of @var{n} frames, the filter
15781 will pick one of them, and then handle the next batch of @var{n} frames until
15782 the end. Default is @code{100}.
15785 Since the filter keeps track of the whole frames sequence, a bigger @var{n}
15786 value will result in a higher memory usage, so a high value is not recommended.
15788 @subsection Examples
15792 Extract one picture each 50 frames:
15798 Complete example of a thumbnail creation with @command{ffmpeg}:
15800 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
15806 Tile several successive frames together.
15808 The filter accepts the following options:
15813 Set the grid size (i.e. the number of lines and columns). For the syntax of
15814 this option, check the
15815 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15818 Set the maximum number of frames to render in the given area. It must be less
15819 than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
15820 the area will be used.
15823 Set the outer border margin in pixels.
15826 Set the inner border thickness (i.e. the number of pixels between frames). For
15827 more advanced padding options (such as having different values for the edges),
15828 refer to the pad video filter.
15831 Specify the color of the unused area. For the syntax of this option, check the
15832 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
15833 The default value of @var{color} is "black".
15836 Set the number of frames to overlap when tiling several successive frames together.
15837 The value must be between @code{0} and @var{nb_frames - 1}.
15840 Set the number of frames to initially be empty before displaying first output frame.
15841 This controls how soon will one get first output frame.
15842 The value must be between @code{0} and @var{nb_frames - 1}.
15845 @subsection Examples
15849 Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
15851 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
15853 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
15854 duplicating each output frame to accommodate the originally detected frame
15858 Display @code{5} pictures in an area of @code{3x2} frames,
15859 with @code{7} pixels between them, and @code{2} pixels of initial margin, using
15860 mixed flat and named options:
15862 tile=3x2:nb_frames=5:padding=7:margin=2
15866 @section tinterlace
15868 Perform various types of temporal field interlacing.
15870 Frames are counted starting from 1, so the first input frame is
15873 The filter accepts the following options:
15878 Specify the mode of the interlacing. This option can also be specified
15879 as a value alone. See below for a list of values for this option.
15881 Available values are:
15885 Move odd frames into the upper field, even into the lower field,
15886 generating a double height frame at half frame rate.
15890 Frame 1 Frame 2 Frame 3 Frame 4
15892 11111 22222 33333 44444
15893 11111 22222 33333 44444
15894 11111 22222 33333 44444
15895 11111 22222 33333 44444
15909 Only output odd frames, even frames are dropped, generating a frame with
15910 unchanged height at half frame rate.
15915 Frame 1 Frame 2 Frame 3 Frame 4
15917 11111 22222 33333 44444
15918 11111 22222 33333 44444
15919 11111 22222 33333 44444
15920 11111 22222 33333 44444
15930 Only output even frames, odd frames are dropped, generating a frame with
15931 unchanged height at half frame rate.
15936 Frame 1 Frame 2 Frame 3 Frame 4
15938 11111 22222 33333 44444
15939 11111 22222 33333 44444
15940 11111 22222 33333 44444
15941 11111 22222 33333 44444
15951 Expand each frame to full height, but pad alternate lines with black,
15952 generating a frame with double height at the same input frame rate.
15957 Frame 1 Frame 2 Frame 3 Frame 4
15959 11111 22222 33333 44444
15960 11111 22222 33333 44444
15961 11111 22222 33333 44444
15962 11111 22222 33333 44444
15965 11111 ..... 33333 .....
15966 ..... 22222 ..... 44444
15967 11111 ..... 33333 .....
15968 ..... 22222 ..... 44444
15969 11111 ..... 33333 .....
15970 ..... 22222 ..... 44444
15971 11111 ..... 33333 .....
15972 ..... 22222 ..... 44444
15976 @item interleave_top, 4
15977 Interleave the upper field from odd frames with the lower field from
15978 even frames, generating a frame with unchanged height at half frame rate.
15983 Frame 1 Frame 2 Frame 3 Frame 4
15985 11111<- 22222 33333<- 44444
15986 11111 22222<- 33333 44444<-
15987 11111<- 22222 33333<- 44444
15988 11111 22222<- 33333 44444<-
15998 @item interleave_bottom, 5
15999 Interleave the lower field from odd frames with the upper field from
16000 even frames, generating a frame with unchanged height at half frame rate.
16005 Frame 1 Frame 2 Frame 3 Frame 4
16007 11111 22222<- 33333 44444<-
16008 11111<- 22222 33333<- 44444
16009 11111 22222<- 33333 44444<-
16010 11111<- 22222 33333<- 44444
16020 @item interlacex2, 6
16021 Double frame rate with unchanged height. Frames are inserted each
16022 containing the second temporal field from the previous input frame and
16023 the first temporal field from the next input frame. This mode relies on
16024 the top_field_first flag. Useful for interlaced video displays with no
16025 field synchronisation.
16030 Frame 1 Frame 2 Frame 3 Frame 4
16032 11111 22222 33333 44444
16033 11111 22222 33333 44444
16034 11111 22222 33333 44444
16035 11111 22222 33333 44444
16038 11111 22222 22222 33333 33333 44444 44444
16039 11111 11111 22222 22222 33333 33333 44444
16040 11111 22222 22222 33333 33333 44444 44444
16041 11111 11111 22222 22222 33333 33333 44444
16046 Move odd frames into the upper field, even into the lower field,
16047 generating a double height frame at same frame rate.
16052 Frame 1 Frame 2 Frame 3 Frame 4
16054 11111 22222 33333 44444
16055 11111 22222 33333 44444
16056 11111 22222 33333 44444
16057 11111 22222 33333 44444
16060 11111 33333 33333 55555
16061 22222 22222 44444 44444
16062 11111 33333 33333 55555
16063 22222 22222 44444 44444
16064 11111 33333 33333 55555
16065 22222 22222 44444 44444
16066 11111 33333 33333 55555
16067 22222 22222 44444 44444
16072 Numeric values are deprecated but are accepted for backward
16073 compatibility reasons.
16075 Default mode is @code{merge}.
16078 Specify flags influencing the filter process.
16080 Available value for @var{flags} is:
16083 @item low_pass_filter, vlfp
16084 Enable linear vertical low-pass filtering in the filter.
16085 Vertical low-pass filtering is required when creating an interlaced
16086 destination from a progressive source which contains high-frequency
16087 vertical detail. Filtering will reduce interlace 'twitter' and Moire
16090 @item complex_filter, cvlfp
16091 Enable complex vertical low-pass filtering.
16092 This will slightly less reduce interlace 'twitter' and Moire
16093 patterning but better retain detail and subjective sharpness impression.
16097 Vertical low-pass filtering can only be enabled for @option{mode}
16098 @var{interleave_top} and @var{interleave_bottom}.
16104 Mix successive video frames.
16106 A description of the accepted options follows.
16110 The number of successive frames to mix. If unspecified, it defaults to 3.
16113 Specify weight of each input video frame.
16114 Each weight is separated by space. If number of weights is smaller than
16115 number of @var{frames} last specified weight will be used for all remaining
16119 Specify scale, if it is set it will be multiplied with sum
16120 of each weight multiplied with pixel values to give final destination
16121 pixel value. By default @var{scale} is auto scaled to sum of weights.
16124 @subsection Examples
16128 Average 7 successive frames:
16130 tmix=frames=7:weights="1 1 1 1 1 1 1"
16134 Apply simple temporal convolution:
16136 tmix=frames=3:weights="-1 3 -1"
16140 Similar as above but only showing temporal differences:
16142 tmix=frames=3:weights="-1 2 -1":scale=1
16147 Tone map colors from different dynamic ranges.
16149 This filter expects data in single precision floating point, as it needs to
16150 operate on (and can output) out-of-range values. Another filter, such as
16151 @ref{zscale}, is needed to convert the resulting frame to a usable format.
16153 The tonemapping algorithms implemented only work on linear light, so input
16154 data should be linearized beforehand (and possibly correctly tagged).
16157 ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
16160 @subsection Options
16161 The filter accepts the following options.
16165 Set the tone map algorithm to use.
16167 Possible values are:
16170 Do not apply any tone map, only desaturate overbright pixels.
16173 Hard-clip any out-of-range values. Use it for perfect color accuracy for
16174 in-range values, while distorting out-of-range values.
16177 Stretch the entire reference gamut to a linear multiple of the display.
16180 Fit a logarithmic transfer between the tone curves.
16183 Preserve overall image brightness with a simple curve, using nonlinear
16184 contrast, which results in flattening details and degrading color accuracy.
16187 Preserve both dark and bright details better than @var{reinhard}, at the cost
16188 of slightly darkening everything. Use it when detail preservation is more
16189 important than color and brightness accuracy.
16192 Smoothly map out-of-range values, while retaining contrast and colors for
16193 in-range material as much as possible. Use it when color accuracy is more
16194 important than detail preservation.
16200 Tune the tone mapping algorithm.
16202 This affects the following algorithms:
16208 Specifies the scale factor to use while stretching.
16212 Specifies the exponent of the function.
16216 Specify an extra linear coefficient to multiply into the signal before clipping.
16220 Specify the local contrast coefficient at the display peak.
16221 Default to 0.5, which means that in-gamut values will be about half as bright
16228 Specify the transition point from linear to mobius transform. Every value
16229 below this point is guaranteed to be mapped 1:1. The higher the value, the
16230 more accurate the result will be, at the cost of losing bright details.
16231 Default to 0.3, which due to the steep initial slope still preserves in-range
16232 colors fairly accurately.
16236 Apply desaturation for highlights that exceed this level of brightness. The
16237 higher the parameter, the more color information will be preserved. This
16238 setting helps prevent unnaturally blown-out colors for super-highlights, by
16239 (smoothly) turning into white instead. This makes images feel more natural,
16240 at the cost of reducing information about out-of-range colors.
16242 The default of 2.0 is somewhat conservative and will mostly just apply to
16243 skies or directly sunlit surfaces. A setting of 0.0 disables this option.
16245 This option works only if the input frame has a supported color tag.
16248 Override signal/nominal/reference peak with this value. Useful when the
16249 embedded peak information in display metadata is not reliable or when tone
16250 mapping from a lower range to a higher range.
16256 Transpose rows with columns in the input video and optionally flip it.
16258 It accepts the following parameters:
16263 Specify the transposition direction.
16265 Can assume the following values:
16267 @item 0, 4, cclock_flip
16268 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
16276 Rotate by 90 degrees clockwise, that is:
16284 Rotate by 90 degrees counterclockwise, that is:
16291 @item 3, 7, clock_flip
16292 Rotate by 90 degrees clockwise and vertically flip, that is:
16300 For values between 4-7, the transposition is only done if the input
16301 video geometry is portrait and not landscape. These values are
16302 deprecated, the @code{passthrough} option should be used instead.
16304 Numerical values are deprecated, and should be dropped in favor of
16305 symbolic constants.
16308 Do not apply the transposition if the input geometry matches the one
16309 specified by the specified value. It accepts the following values:
16312 Always apply transposition.
16314 Preserve portrait geometry (when @var{height} >= @var{width}).
16316 Preserve landscape geometry (when @var{width} >= @var{height}).
16319 Default value is @code{none}.
16322 For example to rotate by 90 degrees clockwise and preserve portrait
16325 transpose=dir=1:passthrough=portrait
16328 The command above can also be specified as:
16330 transpose=1:portrait
16333 @section transpose_npp
16335 Transpose rows with columns in the input video and optionally flip it.
16336 For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options.
16338 It accepts the following parameters:
16343 Specify the transposition direction.
16345 Can assume the following values:
16348 Rotate by 90 degrees counterclockwise and vertically flip. (default)
16351 Rotate by 90 degrees clockwise.
16354 Rotate by 90 degrees counterclockwise.
16357 Rotate by 90 degrees clockwise and vertically flip.
16361 Do not apply the transposition if the input geometry matches the one
16362 specified by the specified value. It accepts the following values:
16365 Always apply transposition. (default)
16367 Preserve portrait geometry (when @var{height} >= @var{width}).
16369 Preserve landscape geometry (when @var{width} >= @var{height}).
16375 Trim the input so that the output contains one continuous subpart of the input.
16377 It accepts the following parameters:
16380 Specify the time of the start of the kept section, i.e. the frame with the
16381 timestamp @var{start} will be the first frame in the output.
16384 Specify the time of the first frame that will be dropped, i.e. the frame
16385 immediately preceding the one with the timestamp @var{end} will be the last
16386 frame in the output.
16389 This is the same as @var{start}, except this option sets the start timestamp
16390 in timebase units instead of seconds.
16393 This is the same as @var{end}, except this option sets the end timestamp
16394 in timebase units instead of seconds.
16397 The maximum duration of the output in seconds.
16400 The number of the first frame that should be passed to the output.
16403 The number of the first frame that should be dropped.
16406 @option{start}, @option{end}, and @option{duration} are expressed as time
16407 duration specifications; see
16408 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
16409 for the accepted syntax.
16411 Note that the first two sets of the start/end options and the @option{duration}
16412 option look at the frame timestamp, while the _frame variants simply count the
16413 frames that pass through the filter. Also note that this filter does not modify
16414 the timestamps. If you wish for the output timestamps to start at zero, insert a
16415 setpts filter after the trim filter.
16417 If multiple start or end options are set, this filter tries to be greedy and
16418 keep all the frames that match at least one of the specified constraints. To keep
16419 only the part that matches all the constraints at once, chain multiple trim
16422 The defaults are such that all the input is kept. So it is possible to set e.g.
16423 just the end values to keep everything before the specified time.
16428 Drop everything except the second minute of input:
16430 ffmpeg -i INPUT -vf trim=60:120
16434 Keep only the first second:
16436 ffmpeg -i INPUT -vf trim=duration=1
16441 @section unpremultiply
16442 Apply alpha unpremultiply effect to input video stream using first plane
16443 of second stream as alpha.
16445 Both streams must have same dimensions and same pixel format.
16447 The filter accepts the following option:
16451 Set which planes will be processed, unprocessed planes will be copied.
16452 By default value 0xf, all planes will be processed.
16454 If the format has 1 or 2 components, then luma is bit 0.
16455 If the format has 3 or 4 components:
16456 for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red;
16457 for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V.
16458 If present, the alpha channel is always the last bit.
16461 Do not require 2nd input for processing, instead use alpha plane from input stream.
16467 Sharpen or blur the input video.
16469 It accepts the following parameters:
16472 @item luma_msize_x, lx
16473 Set the luma matrix horizontal size. It must be an odd integer between
16474 3 and 23. The default value is 5.
16476 @item luma_msize_y, ly
16477 Set the luma matrix vertical size. It must be an odd integer between 3
16478 and 23. The default value is 5.
16480 @item luma_amount, la
16481 Set the luma effect strength. It must be a floating point number, reasonable
16482 values lay between -1.5 and 1.5.
16484 Negative values will blur the input video, while positive values will
16485 sharpen it, a value of zero will disable the effect.
16487 Default value is 1.0.
16489 @item chroma_msize_x, cx
16490 Set the chroma matrix horizontal size. It must be an odd integer
16491 between 3 and 23. The default value is 5.
16493 @item chroma_msize_y, cy
16494 Set the chroma matrix vertical size. It must be an odd integer
16495 between 3 and 23. The default value is 5.
16497 @item chroma_amount, ca
16498 Set the chroma effect strength. It must be a floating point number, reasonable
16499 values lay between -1.5 and 1.5.
16501 Negative values will blur the input video, while positive values will
16502 sharpen it, a value of zero will disable the effect.
16504 Default value is 0.0.
16508 All parameters are optional and default to the equivalent of the
16509 string '5:5:1.0:5:5:0.0'.
16511 @subsection Examples
16515 Apply strong luma sharpen effect:
16517 unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
16521 Apply a strong blur of both luma and chroma parameters:
16523 unsharp=7:7:-2:7:7:-2
16529 Apply ultra slow/simple postprocessing filter that compresses and decompresses
16530 the image at several (or - in the case of @option{quality} level @code{8} - all)
16531 shifts and average the results.
16533 The way this differs from the behavior of spp is that uspp actually encodes &
16534 decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
16535 DCT similar to MJPEG.
16537 The filter accepts the following options:
16541 Set quality. This option defines the number of levels for averaging. It accepts
16542 an integer in the range 0-8. If set to @code{0}, the filter will have no
16543 effect. A value of @code{8} means the higher quality. For each increment of
16544 that value the speed drops by a factor of approximately 2. Default value is
16548 Force a constant quantization parameter. If not set, the filter will use the QP
16549 from the video stream (if available).
16552 @section vaguedenoiser
16554 Apply a wavelet based denoiser.
16556 It transforms each frame from the video input into the wavelet domain,
16557 using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
16558 the obtained coefficients. It does an inverse wavelet transform after.
16559 Due to wavelet properties, it should give a nice smoothed result, and
16560 reduced noise, without blurring picture features.
16562 This filter accepts the following options:
16566 The filtering strength. The higher, the more filtered the video will be.
16567 Hard thresholding can use a higher threshold than soft thresholding
16568 before the video looks overfiltered. Default value is 2.
16571 The filtering method the filter will use.
16573 It accepts the following values:
16576 All values under the threshold will be zeroed.
16579 All values under the threshold will be zeroed. All values above will be
16580 reduced by the threshold.
16583 Scales or nullifies coefficients - intermediary between (more) soft and
16584 (less) hard thresholding.
16587 Default is garrote.
16590 Number of times, the wavelet will decompose the picture. Picture can't
16591 be decomposed beyond a particular point (typically, 8 for a 640x480
16592 frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6.
16595 Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85.
16598 A list of the planes to process. By default all planes are processed.
16601 @section vectorscope
16603 Display 2 color component values in the two dimensional graph (which is called
16606 This filter accepts the following options:
16610 Set vectorscope mode.
16612 It accepts the following values:
16615 Gray values are displayed on graph, higher brightness means more pixels have
16616 same component color value on location in graph. This is the default mode.
16619 Gray values are displayed on graph. Surrounding pixels values which are not
16620 present in video frame are drawn in gradient of 2 color components which are
16621 set by option @code{x} and @code{y}. The 3rd color component is static.
16624 Actual color components values present in video frame are displayed on graph.
16627 Similar as color2 but higher frequency of same values @code{x} and @code{y}
16628 on graph increases value of another color component, which is luminance by
16629 default values of @code{x} and @code{y}.
16632 Actual colors present in video frame are displayed on graph. If two different
16633 colors map to same position on graph then color with higher value of component
16634 not present in graph is picked.
16637 Gray values are displayed on graph. Similar to @code{color} but with 3rd color
16638 component picked from radial gradient.
16642 Set which color component will be represented on X-axis. Default is @code{1}.
16645 Set which color component will be represented on Y-axis. Default is @code{2}.
16648 Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
16649 of color component which represents frequency of (X, Y) location in graph.
16654 No envelope, this is default.
16657 Instant envelope, even darkest single pixel will be clearly highlighted.
16660 Hold maximum and minimum values presented in graph over time. This way you
16661 can still spot out of range values without constantly looking at vectorscope.
16664 Peak and instant envelope combined together.
16668 Set what kind of graticule to draw.
16676 Set graticule opacity.
16679 Set graticule flags.
16683 Draw graticule for white point.
16686 Draw graticule for black point.
16689 Draw color points short names.
16693 Set background opacity.
16695 @item lthreshold, l
16696 Set low threshold for color component not represented on X or Y axis.
16697 Values lower than this value will be ignored. Default is 0.
16698 Note this value is multiplied with actual max possible value one pixel component
16699 can have. So for 8-bit input and low threshold value of 0.1 actual threshold
16702 @item hthreshold, h
16703 Set high threshold for color component not represented on X or Y axis.
16704 Values higher than this value will be ignored. Default is 1.
16705 Note this value is multiplied with actual max possible value one pixel component
16706 can have. So for 8-bit input and high threshold value of 0.9 actual threshold
16707 is 0.9 * 255 = 230.
16709 @item colorspace, c
16710 Set what kind of colorspace to use when drawing graticule.
16719 @anchor{vidstabdetect}
16720 @section vidstabdetect
16722 Analyze video stabilization/deshaking. Perform pass 1 of 2, see
16723 @ref{vidstabtransform} for pass 2.
16725 This filter generates a file with relative translation and rotation
16726 transform information about subsequent frames, which is then used by
16727 the @ref{vidstabtransform} filter.
16729 To enable compilation of this filter you need to configure FFmpeg with
16730 @code{--enable-libvidstab}.
16732 This filter accepts the following options:
16736 Set the path to the file used to write the transforms information.
16737 Default value is @file{transforms.trf}.
16740 Set how shaky the video is and how quick the camera is. It accepts an
16741 integer in the range 1-10, a value of 1 means little shakiness, a
16742 value of 10 means strong shakiness. Default value is 5.
16745 Set the accuracy of the detection process. It must be a value in the
16746 range 1-15. A value of 1 means low accuracy, a value of 15 means high
16747 accuracy. Default value is 15.
16750 Set stepsize of the search process. The region around minimum is
16751 scanned with 1 pixel resolution. Default value is 6.
16754 Set minimum contrast. Below this value a local measurement field is
16755 discarded. Must be a floating point value in the range 0-1. Default
16759 Set reference frame number for tripod mode.
16761 If enabled, the motion of the frames is compared to a reference frame
16762 in the filtered stream, identified by the specified number. The idea
16763 is to compensate all movements in a more-or-less static scene and keep
16764 the camera view absolutely still.
16766 If set to 0, it is disabled. The frames are counted starting from 1.
16769 Show fields and transforms in the resulting frames. It accepts an
16770 integer in the range 0-2. Default value is 0, which disables any
16774 @subsection Examples
16778 Use default values:
16784 Analyze strongly shaky movie and put the results in file
16785 @file{mytransforms.trf}:
16787 vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
16791 Visualize the result of internal transformations in the resulting
16794 vidstabdetect=show=1
16798 Analyze a video with medium shakiness using @command{ffmpeg}:
16800 ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
16804 @anchor{vidstabtransform}
16805 @section vidstabtransform
16807 Video stabilization/deshaking: pass 2 of 2,
16808 see @ref{vidstabdetect} for pass 1.
16810 Read a file with transform information for each frame and
16811 apply/compensate them. Together with the @ref{vidstabdetect}
16812 filter this can be used to deshake videos. See also
16813 @url{http://public.hronopik.de/vid.stab}. It is important to also use
16814 the @ref{unsharp} filter, see below.
16816 To enable compilation of this filter you need to configure FFmpeg with
16817 @code{--enable-libvidstab}.
16819 @subsection Options
16823 Set path to the file used to read the transforms. Default value is
16824 @file{transforms.trf}.
16827 Set the number of frames (value*2 + 1) used for lowpass filtering the
16828 camera movements. Default value is 10.
16830 For example a number of 10 means that 21 frames are used (10 in the
16831 past and 10 in the future) to smoothen the motion in the video. A
16832 larger value leads to a smoother video, but limits the acceleration of
16833 the camera (pan/tilt movements). 0 is a special case where a static
16834 camera is simulated.
16837 Set the camera path optimization algorithm.
16839 Accepted values are:
16842 gaussian kernel low-pass filter on camera motion (default)
16844 averaging on transformations
16848 Set maximal number of pixels to translate frames. Default value is -1,
16852 Set maximal angle in radians (degree*PI/180) to rotate frames. Default
16853 value is -1, meaning no limit.
16856 Specify how to deal with borders that may be visible due to movement
16859 Available values are:
16862 keep image information from previous frame (default)
16864 fill the border black
16868 Invert transforms if set to 1. Default value is 0.
16871 Consider transforms as relative to previous frame if set to 1,
16872 absolute if set to 0. Default value is 0.
16875 Set percentage to zoom. A positive value will result in a zoom-in
16876 effect, a negative value in a zoom-out effect. Default value is 0 (no
16880 Set optimal zooming to avoid borders.
16882 Accepted values are:
16887 optimal static zoom value is determined (only very strong movements
16888 will lead to visible borders) (default)
16890 optimal adaptive zoom value is determined (no borders will be
16891 visible), see @option{zoomspeed}
16894 Note that the value given at zoom is added to the one calculated here.
16897 Set percent to zoom maximally each frame (enabled when
16898 @option{optzoom} is set to 2). Range is from 0 to 5, default value is
16902 Specify type of interpolation.
16904 Available values are:
16909 linear only horizontal
16911 linear in both directions (default)
16913 cubic in both directions (slow)
16917 Enable virtual tripod mode if set to 1, which is equivalent to
16918 @code{relative=0:smoothing=0}. Default value is 0.
16920 Use also @code{tripod} option of @ref{vidstabdetect}.
16923 Increase log verbosity if set to 1. Also the detected global motions
16924 are written to the temporary file @file{global_motions.trf}. Default
16928 @subsection Examples
16932 Use @command{ffmpeg} for a typical stabilization with default values:
16934 ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
16937 Note the use of the @ref{unsharp} filter which is always recommended.
16940 Zoom in a bit more and load transform data from a given file:
16942 vidstabtransform=zoom=5:input="mytransforms.trf"
16946 Smoothen the video even more:
16948 vidstabtransform=smoothing=30
16954 Flip the input video vertically.
16956 For example, to vertically flip a video with @command{ffmpeg}:
16958 ffmpeg -i in.avi -vf "vflip" out.avi
16963 Detect variable frame rate video.
16965 This filter tries to detect if the input is variable or constant frame rate.
16967 At end it will output number of frames detected as having variable delta pts,
16968 and ones with constant delta pts.
16969 If there was frames with variable delta, than it will also show min and max delta
16975 Make or reverse a natural vignetting effect.
16977 The filter accepts the following options:
16981 Set lens angle expression as a number of radians.
16983 The value is clipped in the @code{[0,PI/2]} range.
16985 Default value: @code{"PI/5"}
16989 Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
16993 Set forward/backward mode.
16995 Available modes are:
16998 The larger the distance from the central point, the darker the image becomes.
17001 The larger the distance from the central point, the brighter the image becomes.
17002 This can be used to reverse a vignette effect, though there is no automatic
17003 detection to extract the lens @option{angle} and other settings (yet). It can
17004 also be used to create a burning effect.
17007 Default value is @samp{forward}.
17010 Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
17012 It accepts the following values:
17015 Evaluate expressions only once during the filter initialization.
17018 Evaluate expressions for each incoming frame. This is way slower than the
17019 @samp{init} mode since it requires all the scalers to be re-computed, but it
17020 allows advanced dynamic expressions.
17023 Default value is @samp{init}.
17026 Set dithering to reduce the circular banding effects. Default is @code{1}
17030 Set vignette aspect. This setting allows one to adjust the shape of the vignette.
17031 Setting this value to the SAR of the input will make a rectangular vignetting
17032 following the dimensions of the video.
17034 Default is @code{1/1}.
17037 @subsection Expressions
17039 The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
17040 following parameters.
17045 input width and height
17048 the number of input frame, starting from 0
17051 the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
17052 @var{TB} units, NAN if undefined
17055 frame rate of the input video, NAN if the input frame rate is unknown
17058 the PTS (Presentation TimeStamp) of the filtered video frame,
17059 expressed in seconds, NAN if undefined
17062 time base of the input video
17066 @subsection Examples
17070 Apply simple strong vignetting effect:
17076 Make a flickering vignetting:
17078 vignette='PI/4+random(1)*PI/50':eval=frame
17083 @section vmafmotion
17085 Obtain the average vmaf motion score of a video.
17086 It is one of the component filters of VMAF.
17088 The obtained average motion score is printed through the logging system.
17090 In the below example the input file @file{ref.mpg} is being processed and score
17094 ffmpeg -i ref.mpg -lavfi vmafmotion -f null -
17098 Stack input videos vertically.
17100 All streams must be of same pixel format and of same width.
17102 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
17103 to create same output.
17105 The filter accept the following option:
17109 Set number of input streams. Default is 2.
17112 If set to 1, force the output to terminate when the shortest input
17113 terminates. Default value is 0.
17118 Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
17119 Deinterlacing Filter").
17121 Based on the process described by Martin Weston for BBC R&D, and
17122 implemented based on the de-interlace algorithm written by Jim
17123 Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
17124 uses filter coefficients calculated by BBC R&D.
17126 There are two sets of filter coefficients, so called "simple":
17127 and "complex". Which set of filter coefficients is used can
17128 be set by passing an optional parameter:
17132 Set the interlacing filter coefficients. Accepts one of the following values:
17136 Simple filter coefficient set.
17138 More-complex filter coefficient set.
17140 Default value is @samp{complex}.
17143 Specify which frames to deinterlace. Accept one of the following values:
17147 Deinterlace all frames,
17149 Only deinterlace frames marked as interlaced.
17152 Default value is @samp{all}.
17156 Video waveform monitor.
17158 The waveform monitor plots color component intensity. By default luminance
17159 only. Each column of the waveform corresponds to a column of pixels in the
17162 It accepts the following options:
17166 Can be either @code{row}, or @code{column}. Default is @code{column}.
17167 In row mode, the graph on the left side represents color component value 0 and
17168 the right side represents value = 255. In column mode, the top side represents
17169 color component value = 0 and bottom side represents value = 255.
17172 Set intensity. Smaller values are useful to find out how many values of the same
17173 luminance are distributed across input rows/columns.
17174 Default value is @code{0.04}. Allowed range is [0, 1].
17177 Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
17178 In mirrored mode, higher values will be represented on the left
17179 side for @code{row} mode and at the top for @code{column} mode. Default is
17180 @code{1} (mirrored).
17184 It accepts the following values:
17187 Presents information identical to that in the @code{parade}, except
17188 that the graphs representing color components are superimposed directly
17191 This display mode makes it easier to spot relative differences or similarities
17192 in overlapping areas of the color components that are supposed to be identical,
17193 such as neutral whites, grays, or blacks.
17196 Display separate graph for the color components side by side in
17197 @code{row} mode or one below the other in @code{column} mode.
17200 Display separate graph for the color components side by side in
17201 @code{column} mode or one below the other in @code{row} mode.
17203 Using this display mode makes it easy to spot color casts in the highlights
17204 and shadows of an image, by comparing the contours of the top and the bottom
17205 graphs of each waveform. Since whites, grays, and blacks are characterized
17206 by exactly equal amounts of red, green, and blue, neutral areas of the picture
17207 should display three waveforms of roughly equal width/height. If not, the
17208 correction is easy to perform by making level adjustments the three waveforms.
17210 Default is @code{stack}.
17212 @item components, c
17213 Set which color components to display. Default is 1, which means only luminance
17214 or red color component if input is in RGB colorspace. If is set for example to
17215 7 it will display all 3 (if) available color components.
17220 No envelope, this is default.
17223 Instant envelope, minimum and maximum values presented in graph will be easily
17224 visible even with small @code{step} value.
17227 Hold minimum and maximum values presented in graph across time. This way you
17228 can still spot out of range values without constantly looking at waveforms.
17231 Peak and instant envelope combined together.
17237 No filtering, this is default.
17240 Luma and chroma combined together.
17243 Similar as above, but shows difference between blue and red chroma.
17246 Similar as above, but use different colors.
17249 Displays only chroma.
17252 Displays actual color value on waveform.
17255 Similar as above, but with luma showing frequency of chroma values.
17259 Set which graticule to display.
17263 Do not display graticule.
17266 Display green graticule showing legal broadcast ranges.
17269 Display orange graticule showing legal broadcast ranges.
17273 Set graticule opacity.
17276 Set graticule flags.
17280 Draw numbers above lines. By default enabled.
17283 Draw dots instead of lines.
17287 Set scale used for displaying graticule.
17294 Default is digital.
17297 Set background opacity.
17300 @section weave, doubleweave
17302 The @code{weave} takes a field-based video input and join
17303 each two sequential fields into single frame, producing a new double
17304 height clip with half the frame rate and half the frame count.
17306 The @code{doubleweave} works same as @code{weave} but without
17307 halving frame rate and frame count.
17309 It accepts the following option:
17313 Set first field. Available values are:
17317 Set the frame as top-field-first.
17320 Set the frame as bottom-field-first.
17324 @subsection Examples
17328 Interlace video using @ref{select} and @ref{separatefields} filter:
17330 separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
17335 Apply the xBR high-quality magnification filter which is designed for pixel
17336 art. It follows a set of edge-detection rules, see
17337 @url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}.
17339 It accepts the following option:
17343 Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
17344 @code{3xBR} and @code{4} for @code{4xBR}.
17345 Default is @code{3}.
17351 Deinterlace the input video ("yadif" means "yet another deinterlacing
17354 It accepts the following parameters:
17360 The interlacing mode to adopt. It accepts one of the following values:
17363 @item 0, send_frame
17364 Output one frame for each frame.
17365 @item 1, send_field
17366 Output one frame for each field.
17367 @item 2, send_frame_nospatial
17368 Like @code{send_frame}, but it skips the spatial interlacing check.
17369 @item 3, send_field_nospatial
17370 Like @code{send_field}, but it skips the spatial interlacing check.
17373 The default value is @code{send_frame}.
17376 The picture field parity assumed for the input interlaced video. It accepts one
17377 of the following values:
17381 Assume the top field is first.
17383 Assume the bottom field is first.
17385 Enable automatic detection of field parity.
17388 The default value is @code{auto}.
17389 If the interlacing is unknown or the decoder does not export this information,
17390 top field first will be assumed.
17393 Specify which frames to deinterlace. Accept one of the following
17398 Deinterlace all frames.
17399 @item 1, interlaced
17400 Only deinterlace frames marked as interlaced.
17403 The default value is @code{all}.
17408 Apply Zoom & Pan effect.
17410 This filter accepts the following options:
17414 Set the zoom expression. Default is 1.
17418 Set the x and y expression. Default is 0.
17421 Set the duration expression in number of frames.
17422 This sets for how many number of frames effect will last for
17423 single input image.
17426 Set the output image size, default is 'hd720'.
17429 Set the output frame rate, default is '25'.
17432 Each expression can contain the following constants:
17451 Output frame count.
17455 Last calculated 'x' and 'y' position from 'x' and 'y' expression
17456 for current input frame.
17460 'x' and 'y' of last output frame of previous input frame or 0 when there was
17461 not yet such frame (first input frame).
17464 Last calculated zoom from 'z' expression for current input frame.
17467 Last calculated zoom of last output frame of previous input frame.
17470 Number of output frames for current input frame. Calculated from 'd' expression
17471 for each input frame.
17474 number of output frames created for previous input frame
17477 Rational number: input width / input height
17480 sample aspect ratio
17483 display aspect ratio
17487 @subsection Examples
17491 Zoom-in up to 1.5 and pan at same time to some spot near center of picture:
17493 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
17497 Zoom-in up to 1.5 and pan always at center of picture:
17499 zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
17503 Same as above but without pausing:
17505 zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
17511 Scale (resize) the input video, using the z.lib library:
17512 @url{https://github.com/sekrit-twc/zimg}. To enable compilation of this
17513 filter, you need to configure FFmpeg with @code{--enable-libzimg}.
17515 The zscale filter forces the output display aspect ratio to be the same
17516 as the input, by changing the output sample aspect ratio.
17518 If the input image format is different from the format requested by
17519 the next filter, the zscale filter will convert the input to the
17522 @subsection Options
17523 The filter accepts the following options.
17528 Set the output video dimension expression. Default value is the input
17531 If the @var{width} or @var{w} value is 0, the input width is used for
17532 the output. If the @var{height} or @var{h} value is 0, the input height
17533 is used for the output.
17535 If one and only one of the values is -n with n >= 1, the zscale filter
17536 will use a value that maintains the aspect ratio of the input image,
17537 calculated from the other specified dimension. After that it will,
17538 however, make sure that the calculated dimension is divisible by n and
17539 adjust the value if necessary.
17541 If both values are -n with n >= 1, the behavior will be identical to
17542 both values being set to 0 as previously detailed.
17544 See below for the list of accepted constants for use in the dimension
17548 Set the video size. For the syntax of this option, check the
17549 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17552 Set the dither type.
17554 Possible values are:
17559 @item error_diffusion
17565 Set the resize filter type.
17567 Possible values are:
17577 Default is bilinear.
17580 Set the color range.
17582 Possible values are:
17589 Default is same as input.
17592 Set the color primaries.
17594 Possible values are:
17604 Default is same as input.
17607 Set the transfer characteristics.
17609 Possible values are:
17623 Default is same as input.
17626 Set the colorspace matrix.
17628 Possible value are:
17639 Default is same as input.
17642 Set the input color range.
17644 Possible values are:
17651 Default is same as input.
17653 @item primariesin, pin
17654 Set the input color primaries.
17656 Possible values are:
17666 Default is same as input.
17668 @item transferin, tin
17669 Set the input transfer characteristics.
17671 Possible values are:
17682 Default is same as input.
17684 @item matrixin, min
17685 Set the input colorspace matrix.
17687 Possible value are:
17699 Set the output chroma location.
17701 Possible values are:
17712 @item chromalin, cin
17713 Set the input chroma location.
17715 Possible values are:
17727 Set the nominal peak luminance.
17730 The values of the @option{w} and @option{h} options are expressions
17731 containing the following constants:
17736 The input width and height
17740 These are the same as @var{in_w} and @var{in_h}.
17744 The output (scaled) width and height
17748 These are the same as @var{out_w} and @var{out_h}
17751 The same as @var{iw} / @var{ih}
17754 input sample aspect ratio
17757 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
17761 horizontal and vertical input chroma subsample values. For example for the
17762 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
17766 horizontal and vertical output chroma subsample values. For example for the
17767 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
17773 @c man end VIDEO FILTERS
17775 @chapter Video Sources
17776 @c man begin VIDEO SOURCES
17778 Below is a description of the currently available video sources.
17782 Buffer video frames, and make them available to the filter chain.
17784 This source is mainly intended for a programmatic use, in particular
17785 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
17787 It accepts the following parameters:
17792 Specify the size (width and height) of the buffered video frames. For the
17793 syntax of this option, check the
17794 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17797 The input video width.
17800 The input video height.
17803 A string representing the pixel format of the buffered video frames.
17804 It may be a number corresponding to a pixel format, or a pixel format
17808 Specify the timebase assumed by the timestamps of the buffered frames.
17811 Specify the frame rate expected for the video stream.
17813 @item pixel_aspect, sar
17814 The sample (pixel) aspect ratio of the input video.
17817 Specify the optional parameters to be used for the scale filter which
17818 is automatically inserted when an input change is detected in the
17819 input size or format.
17821 @item hw_frames_ctx
17822 When using a hardware pixel format, this should be a reference to an
17823 AVHWFramesContext describing input frames.
17828 buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
17831 will instruct the source to accept video frames with size 320x240 and
17832 with format "yuv410p", assuming 1/24 as the timestamps timebase and
17833 square pixels (1:1 sample aspect ratio).
17834 Since the pixel format with name "yuv410p" corresponds to the number 6
17835 (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
17836 this example corresponds to:
17838 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
17841 Alternatively, the options can be specified as a flat string, but this
17842 syntax is deprecated:
17844 @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}]
17848 Create a pattern generated by an elementary cellular automaton.
17850 The initial state of the cellular automaton can be defined through the
17851 @option{filename} and @option{pattern} options. If such options are
17852 not specified an initial state is created randomly.
17854 At each new frame a new row in the video is filled with the result of
17855 the cellular automaton next generation. The behavior when the whole
17856 frame is filled is defined by the @option{scroll} option.
17858 This source accepts the following options:
17862 Read the initial cellular automaton state, i.e. the starting row, from
17863 the specified file.
17864 In the file, each non-whitespace character is considered an alive
17865 cell, a newline will terminate the row, and further characters in the
17866 file will be ignored.
17869 Read the initial cellular automaton state, i.e. the starting row, from
17870 the specified string.
17872 Each non-whitespace character in the string is considered an alive
17873 cell, a newline will terminate the row, and further characters in the
17874 string will be ignored.
17877 Set the video rate, that is the number of frames generated per second.
17880 @item random_fill_ratio, ratio
17881 Set the random fill ratio for the initial cellular automaton row. It
17882 is a floating point number value ranging from 0 to 1, defaults to
17885 This option is ignored when a file or a pattern is specified.
17887 @item random_seed, seed
17888 Set the seed for filling randomly the initial row, must be an integer
17889 included between 0 and UINT32_MAX. If not specified, or if explicitly
17890 set to -1, the filter will try to use a good random seed on a best
17894 Set the cellular automaton rule, it is a number ranging from 0 to 255.
17895 Default value is 110.
17898 Set the size of the output video. For the syntax of this option, check the
17899 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17901 If @option{filename} or @option{pattern} is specified, the size is set
17902 by default to the width of the specified initial state row, and the
17903 height is set to @var{width} * PHI.
17905 If @option{size} is set, it must contain the width of the specified
17906 pattern string, and the specified pattern will be centered in the
17909 If a filename or a pattern string is not specified, the size value
17910 defaults to "320x518" (used for a randomly generated initial state).
17913 If set to 1, scroll the output upward when all the rows in the output
17914 have been already filled. If set to 0, the new generated row will be
17915 written over the top row just after the bottom row is filled.
17918 @item start_full, full
17919 If set to 1, completely fill the output with generated rows before
17920 outputting the first frame.
17921 This is the default behavior, for disabling set the value to 0.
17924 If set to 1, stitch the left and right row edges together.
17925 This is the default behavior, for disabling set the value to 0.
17928 @subsection Examples
17932 Read the initial state from @file{pattern}, and specify an output of
17935 cellauto=f=pattern:s=200x400
17939 Generate a random initial row with a width of 200 cells, with a fill
17942 cellauto=ratio=2/3:s=200x200
17946 Create a pattern generated by rule 18 starting by a single alive cell
17947 centered on an initial row with width 100:
17949 cellauto=p=@@:s=100x400:full=0:rule=18
17953 Specify a more elaborated initial pattern:
17955 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
17960 @anchor{coreimagesrc}
17961 @section coreimagesrc
17962 Video source generated on GPU using Apple's CoreImage API on OSX.
17964 This video source is a specialized version of the @ref{coreimage} video filter.
17965 Use a core image generator at the beginning of the applied filterchain to
17966 generate the content.
17968 The coreimagesrc video source accepts the following options:
17970 @item list_generators
17971 List all available generators along with all their respective options as well as
17972 possible minimum and maximum values along with the default values.
17974 list_generators=true
17978 Specify the size of the sourced video. For the syntax of this option, check the
17979 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17980 The default value is @code{320x240}.
17983 Specify the frame rate of the sourced video, as the number of frames
17984 generated per second. It has to be a string in the format
17985 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
17986 number or a valid video frame rate abbreviation. The default value is
17990 Set the sample aspect ratio of the sourced video.
17993 Set the duration of the sourced video. See
17994 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
17995 for the accepted syntax.
17997 If not specified, or the expressed duration is negative, the video is
17998 supposed to be generated forever.
18001 Additionally, all options of the @ref{coreimage} video filter are accepted.
18002 A complete filterchain can be used for further processing of the
18003 generated input without CPU-HOST transfer. See @ref{coreimage} documentation
18004 and examples for details.
18006 @subsection Examples
18011 Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
18012 given as complete and escaped command-line for Apple's standard bash shell:
18014 ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
18016 This example is equivalent to the QRCode example of @ref{coreimage} without the
18017 need for a nullsrc video source.
18021 @section mandelbrot
18023 Generate a Mandelbrot set fractal, and progressively zoom towards the
18024 point specified with @var{start_x} and @var{start_y}.
18026 This source accepts the following options:
18031 Set the terminal pts value. Default value is 400.
18034 Set the terminal scale value.
18035 Must be a floating point value. Default value is 0.3.
18038 Set the inner coloring mode, that is the algorithm used to draw the
18039 Mandelbrot fractal internal region.
18041 It shall assume one of the following values:
18046 Show time until convergence.
18048 Set color based on point closest to the origin of the iterations.
18053 Default value is @var{mincol}.
18056 Set the bailout value. Default value is 10.0.
18059 Set the maximum of iterations performed by the rendering
18060 algorithm. Default value is 7189.
18063 Set outer coloring mode.
18064 It shall assume one of following values:
18066 @item iteration_count
18067 Set iteration cound mode.
18068 @item normalized_iteration_count
18069 set normalized iteration count mode.
18071 Default value is @var{normalized_iteration_count}.
18074 Set frame rate, expressed as number of frames per second. Default
18078 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
18079 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
18082 Set the initial scale value. Default value is 3.0.
18085 Set the initial x position. Must be a floating point value between
18086 -100 and 100. Default value is -0.743643887037158704752191506114774.
18089 Set the initial y position. Must be a floating point value between
18090 -100 and 100. Default value is -0.131825904205311970493132056385139.
18095 Generate various test patterns, as generated by the MPlayer test filter.
18097 The size of the generated video is fixed, and is 256x256.
18098 This source is useful in particular for testing encoding features.
18100 This source accepts the following options:
18105 Specify the frame rate of the sourced video, as the number of frames
18106 generated per second. It has to be a string in the format
18107 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
18108 number or a valid video frame rate abbreviation. The default value is
18112 Set the duration of the sourced video. See
18113 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
18114 for the accepted syntax.
18116 If not specified, or the expressed duration is negative, the video is
18117 supposed to be generated forever.
18121 Set the number or the name of the test to perform. Supported tests are:
18137 Default value is "all", which will cycle through the list of all tests.
18142 mptestsrc=t=dc_luma
18145 will generate a "dc_luma" test pattern.
18147 @section frei0r_src
18149 Provide a frei0r source.
18151 To enable compilation of this filter you need to install the frei0r
18152 header and configure FFmpeg with @code{--enable-frei0r}.
18154 This source accepts the following parameters:
18159 The size of the video to generate. For the syntax of this option, check the
18160 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18163 The framerate of the generated video. It may be a string of the form
18164 @var{num}/@var{den} or a frame rate abbreviation.
18167 The name to the frei0r source to load. For more information regarding frei0r and
18168 how to set the parameters, read the @ref{frei0r} section in the video filters
18171 @item filter_params
18172 A '|'-separated list of parameters to pass to the frei0r source.
18176 For example, to generate a frei0r partik0l source with size 200x200
18177 and frame rate 10 which is overlaid on the overlay filter main input:
18179 frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
18184 Generate a life pattern.
18186 This source is based on a generalization of John Conway's life game.
18188 The sourced input represents a life grid, each pixel represents a cell
18189 which can be in one of two possible states, alive or dead. Every cell
18190 interacts with its eight neighbours, which are the cells that are
18191 horizontally, vertically, or diagonally adjacent.
18193 At each interaction the grid evolves according to the adopted rule,
18194 which specifies the number of neighbor alive cells which will make a
18195 cell stay alive or born. The @option{rule} option allows one to specify
18198 This source accepts the following options:
18202 Set the file from which to read the initial grid state. In the file,
18203 each non-whitespace character is considered an alive cell, and newline
18204 is used to delimit the end of each row.
18206 If this option is not specified, the initial grid is generated
18210 Set the video rate, that is the number of frames generated per second.
18213 @item random_fill_ratio, ratio
18214 Set the random fill ratio for the initial random grid. It is a
18215 floating point number value ranging from 0 to 1, defaults to 1/PHI.
18216 It is ignored when a file is specified.
18218 @item random_seed, seed
18219 Set the seed for filling the initial random grid, must be an integer
18220 included between 0 and UINT32_MAX. If not specified, or if explicitly
18221 set to -1, the filter will try to use a good random seed on a best
18227 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
18228 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
18229 @var{NS} specifies the number of alive neighbor cells which make a
18230 live cell stay alive, and @var{NB} the number of alive neighbor cells
18231 which make a dead cell to become alive (i.e. to "born").
18232 "s" and "b" can be used in place of "S" and "B", respectively.
18234 Alternatively a rule can be specified by an 18-bits integer. The 9
18235 high order bits are used to encode the next cell state if it is alive
18236 for each number of neighbor alive cells, the low order bits specify
18237 the rule for "borning" new cells. Higher order bits encode for an
18238 higher number of neighbor cells.
18239 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
18240 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
18242 Default value is "S23/B3", which is the original Conway's game of life
18243 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
18244 cells, and will born a new cell if there are three alive cells around
18248 Set the size of the output video. For the syntax of this option, check the
18249 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18251 If @option{filename} is specified, the size is set by default to the
18252 same size of the input file. If @option{size} is set, it must contain
18253 the size specified in the input file, and the initial grid defined in
18254 that file is centered in the larger resulting area.
18256 If a filename is not specified, the size value defaults to "320x240"
18257 (used for a randomly generated initial grid).
18260 If set to 1, stitch the left and right grid edges together, and the
18261 top and bottom edges also. Defaults to 1.
18264 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
18265 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
18266 value from 0 to 255.
18269 Set the color of living (or new born) cells.
18272 Set the color of dead cells. If @option{mold} is set, this is the first color
18273 used to represent a dead cell.
18276 Set mold color, for definitely dead and moldy cells.
18278 For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the
18279 ffmpeg-utils manual,ffmpeg-utils}.
18282 @subsection Examples
18286 Read a grid from @file{pattern}, and center it on a grid of size
18289 life=f=pattern:s=300x300
18293 Generate a random grid of size 200x200, with a fill ratio of 2/3:
18295 life=ratio=2/3:s=200x200
18299 Specify a custom rule for evolving a randomly generated grid:
18305 Full example with slow death effect (mold) using @command{ffplay}:
18307 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
18314 @anchor{haldclutsrc}
18317 @anchor{pal100bars}
18318 @anchor{rgbtestsrc}
18320 @anchor{smptehdbars}
18323 @anchor{yuvtestsrc}
18324 @section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
18326 The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
18328 The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
18330 The @code{color} source provides an uniformly colored input.
18332 The @code{haldclutsrc} source provides an identity Hald CLUT. See also
18333 @ref{haldclut} filter.
18335 The @code{nullsrc} source returns unprocessed video frames. It is
18336 mainly useful to be employed in analysis / debugging tools, or as the
18337 source for filters which ignore the input data.
18339 The @code{pal75bars} source generates a color bars pattern, based on
18340 EBU PAL recommendations with 75% color levels.
18342 The @code{pal100bars} source generates a color bars pattern, based on
18343 EBU PAL recommendations with 100% color levels.
18345 The @code{rgbtestsrc} source generates an RGB test pattern useful for
18346 detecting RGB vs BGR issues. You should see a red, green and blue
18347 stripe from top to bottom.
18349 The @code{smptebars} source generates a color bars pattern, based on
18350 the SMPTE Engineering Guideline EG 1-1990.
18352 The @code{smptehdbars} source generates a color bars pattern, based on
18353 the SMPTE RP 219-2002.
18355 The @code{testsrc} source generates a test video pattern, showing a
18356 color pattern, a scrolling gradient and a timestamp. This is mainly
18357 intended for testing purposes.
18359 The @code{testsrc2} source is similar to testsrc, but supports more
18360 pixel formats instead of just @code{rgb24}. This allows using it as an
18361 input for other tests without requiring a format conversion.
18363 The @code{yuvtestsrc} source generates an YUV test pattern. You should
18364 see a y, cb and cr stripe from top to bottom.
18366 The sources accept the following parameters:
18371 Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
18372 source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
18373 pixels to be used as identity matrix for 3D lookup tables. Each component is
18374 coded on a @code{1/(N*N)} scale.
18377 Specify the color of the source, only available in the @code{color}
18378 source. For the syntax of this option, check the
18379 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
18382 Specify the size of the sourced video. For the syntax of this option, check the
18383 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18384 The default value is @code{320x240}.
18386 This option is not available with the @code{allrgb}, @code{allyuv}, and
18387 @code{haldclutsrc} filters.
18390 Specify the frame rate of the sourced video, as the number of frames
18391 generated per second. It has to be a string in the format
18392 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
18393 number or a valid video frame rate abbreviation. The default value is
18397 Set the duration of the sourced video. See
18398 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
18399 for the accepted syntax.
18401 If not specified, or the expressed duration is negative, the video is
18402 supposed to be generated forever.
18405 Set the sample aspect ratio of the sourced video.
18408 Specify the alpha (opacity) of the background, only available in the
18409 @code{testsrc2} source. The value must be between 0 (fully transparent) and
18410 255 (fully opaque, the default).
18413 Set the number of decimals to show in the timestamp, only available in the
18414 @code{testsrc} source.
18416 The displayed timestamp value will correspond to the original
18417 timestamp value multiplied by the power of 10 of the specified
18418 value. Default value is 0.
18421 @subsection Examples
18425 Generate a video with a duration of 5.3 seconds, with size
18426 176x144 and a frame rate of 10 frames per second:
18428 testsrc=duration=5.3:size=qcif:rate=10
18432 The following graph description will generate a red source
18433 with an opacity of 0.2, with size "qcif" and a frame rate of 10
18436 color=c=red@@0.2:s=qcif:r=10
18440 If the input content is to be ignored, @code{nullsrc} can be used. The
18441 following command generates noise in the luminance plane by employing
18442 the @code{geq} filter:
18444 nullsrc=s=256x256, geq=random(1)*255:128:128
18448 @subsection Commands
18450 The @code{color} source supports the following commands:
18454 Set the color of the created image. Accepts the same syntax of the
18455 corresponding @option{color} option.
18460 Generate video using an OpenCL program.
18465 OpenCL program source file.
18468 Kernel name in program.
18471 Size of frames to generate. This must be set.
18474 Pixel format to use for the generated frames. This must be set.
18477 Number of frames generated every second. Default value is '25'.
18481 For details of how the program loading works, see the @ref{program_opencl}
18488 Generate a colour ramp by setting pixel values from the position of the pixel
18489 in the output image. (Note that this will work with all pixel formats, but
18490 the generated output will not be the same.)
18492 __kernel void ramp(__write_only image2d_t dst,
18493 unsigned int index)
18495 int2 loc = (int2)(get_global_id(0), get_global_id(1));
18498 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
18500 write_imagef(dst, loc, val);
18505 Generate a Sierpinski carpet pattern, panning by a single pixel each frame.
18507 __kernel void sierpinski_carpet(__write_only image2d_t dst,
18508 unsigned int index)
18510 int2 loc = (int2)(get_global_id(0), get_global_id(1));
18512 float4 value = 0.0f;
18513 int x = loc.x + index;
18514 int y = loc.y + index;
18515 while (x > 0 || y > 0) {
18516 if (x % 3 == 1 && y % 3 == 1) {
18524 write_imagef(dst, loc, value);
18530 @c man end VIDEO SOURCES
18532 @chapter Video Sinks
18533 @c man begin VIDEO SINKS
18535 Below is a description of the currently available video sinks.
18537 @section buffersink
18539 Buffer video frames, and make them available to the end of the filter
18542 This sink is mainly intended for programmatic use, in particular
18543 through the interface defined in @file{libavfilter/buffersink.h}
18544 or the options system.
18546 It accepts a pointer to an AVBufferSinkContext structure, which
18547 defines the incoming buffers' formats, to be passed as the opaque
18548 parameter to @code{avfilter_init_filter} for initialization.
18552 Null video sink: do absolutely nothing with the input video. It is
18553 mainly useful as a template and for use in analysis / debugging
18556 @c man end VIDEO SINKS
18558 @chapter Multimedia Filters
18559 @c man begin MULTIMEDIA FILTERS
18561 Below is a description of the currently available multimedia filters.
18565 Convert input audio to a video output, displaying the audio bit scope.
18567 The filter accepts the following options:
18571 Set frame rate, expressed as number of frames per second. Default
18575 Specify the video size for the output. For the syntax of this option, check the
18576 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18577 Default value is @code{1024x256}.
18580 Specify list of colors separated by space or by '|' which will be used to
18581 draw channels. Unrecognized or missing colors will be replaced
18585 @section ahistogram
18587 Convert input audio to a video output, displaying the volume histogram.
18589 The filter accepts the following options:
18593 Specify how histogram is calculated.
18595 It accepts the following values:
18598 Use single histogram for all channels.
18600 Use separate histogram for each channel.
18602 Default is @code{single}.
18605 Set frame rate, expressed as number of frames per second. Default
18609 Specify the video size for the output. For the syntax of this option, check the
18610 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18611 Default value is @code{hd720}.
18616 It accepts the following values:
18627 reverse logarithmic
18629 Default is @code{log}.
18632 Set amplitude scale.
18634 It accepts the following values:
18641 Default is @code{log}.
18644 Set how much frames to accumulate in histogram.
18645 Defauls is 1. Setting this to -1 accumulates all frames.
18648 Set histogram ratio of window height.
18651 Set sonogram sliding.
18653 It accepts the following values:
18656 replace old rows with new ones.
18658 scroll from top to bottom.
18660 Default is @code{replace}.
18663 @section aphasemeter
18665 Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase},
18666 representing mean phase of current audio frame. A video output can also be produced and is
18667 enabled by default. The audio is passed through as first output.
18669 Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in
18670 range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase
18671 and @code{1} means channels are in phase.
18673 The filter accepts the following options, all related to its video output:
18677 Set the output frame rate. Default value is @code{25}.
18680 Set the video size for the output. For the syntax of this option, check the
18681 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18682 Default value is @code{800x400}.
18687 Specify the red, green, blue contrast. Default values are @code{2},
18688 @code{7} and @code{1}.
18689 Allowed range is @code{[0, 255]}.
18692 Set color which will be used for drawing median phase. If color is
18693 @code{none} which is default, no median phase value will be drawn.
18696 Enable video output. Default is enabled.
18699 @section avectorscope
18701 Convert input audio to a video output, representing the audio vector
18704 The filter is used to measure the difference between channels of stereo
18705 audio stream. A monoaural signal, consisting of identical left and right
18706 signal, results in straight vertical line. Any stereo separation is visible
18707 as a deviation from this line, creating a Lissajous figure.
18708 If the straight (or deviation from it) but horizontal line appears this
18709 indicates that the left and right channels are out of phase.
18711 The filter accepts the following options:
18715 Set the vectorscope mode.
18717 Available values are:
18720 Lissajous rotated by 45 degrees.
18723 Same as above but not rotated.
18726 Shape resembling half of circle.
18729 Default value is @samp{lissajous}.
18732 Set the video size for the output. For the syntax of this option, check the
18733 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18734 Default value is @code{400x400}.
18737 Set the output frame rate. Default value is @code{25}.
18743 Specify the red, green, blue and alpha contrast. Default values are @code{40},
18744 @code{160}, @code{80} and @code{255}.
18745 Allowed range is @code{[0, 255]}.
18751 Specify the red, green, blue and alpha fade. Default values are @code{15},
18752 @code{10}, @code{5} and @code{5}.
18753 Allowed range is @code{[0, 255]}.
18756 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}.
18757 Values lower than @var{1} will auto adjust zoom factor to maximal possible value.
18760 Set the vectorscope drawing mode.
18762 Available values are:
18765 Draw dot for each sample.
18768 Draw line between previous and current sample.
18771 Default value is @samp{dot}.
18774 Specify amplitude scale of audio samples.
18776 Available values are:
18792 Swap left channel axis with right channel axis.
18802 Mirror only x axis.
18805 Mirror only y axis.
18813 @subsection Examples
18817 Complete example using @command{ffplay}:
18819 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
18820 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
18824 @section bench, abench
18826 Benchmark part of a filtergraph.
18828 The filter accepts the following options:
18832 Start or stop a timer.
18834 Available values are:
18837 Get the current time, set it as frame metadata (using the key
18838 @code{lavfi.bench.start_time}), and forward the frame to the next filter.
18841 Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
18842 the input frame metadata to get the time difference. Time difference, average,
18843 maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
18844 @code{min}) are then printed. The timestamps are expressed in seconds.
18848 @subsection Examples
18852 Benchmark @ref{selectivecolor} filter:
18854 bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
18860 Concatenate audio and video streams, joining them together one after the
18863 The filter works on segments of synchronized video and audio streams. All
18864 segments must have the same number of streams of each type, and that will
18865 also be the number of streams at output.
18867 The filter accepts the following options:
18872 Set the number of segments. Default is 2.
18875 Set the number of output video streams, that is also the number of video
18876 streams in each segment. Default is 1.
18879 Set the number of output audio streams, that is also the number of audio
18880 streams in each segment. Default is 0.
18883 Activate unsafe mode: do not fail if segments have a different format.
18887 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
18888 @var{a} audio outputs.
18890 There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
18891 segment, in the same order as the outputs, then the inputs for the second
18894 Related streams do not always have exactly the same duration, for various
18895 reasons including codec frame size or sloppy authoring. For that reason,
18896 related synchronized streams (e.g. a video and its audio track) should be
18897 concatenated at once. The concat filter will use the duration of the longest
18898 stream in each segment (except the last one), and if necessary pad shorter
18899 audio streams with silence.
18901 For this filter to work correctly, all segments must start at timestamp 0.
18903 All corresponding streams must have the same parameters in all segments; the
18904 filtering system will automatically select a common pixel format for video
18905 streams, and a common sample format, sample rate and channel layout for
18906 audio streams, but other settings, such as resolution, must be converted
18907 explicitly by the user.
18909 Different frame rates are acceptable but will result in variable frame rate
18910 at output; be sure to configure the output file to handle it.
18912 @subsection Examples
18916 Concatenate an opening, an episode and an ending, all in bilingual version
18917 (video in stream 0, audio in streams 1 and 2):
18919 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
18920 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
18921 concat=n=3:v=1:a=2 [v] [a1] [a2]' \
18922 -map '[v]' -map '[a1]' -map '[a2]' output.mkv
18926 Concatenate two parts, handling audio and video separately, using the
18927 (a)movie sources, and adjusting the resolution:
18929 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
18930 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
18931 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
18933 Note that a desync will happen at the stitch if the audio and video streams
18934 do not have exactly the same duration in the first file.
18938 @subsection Commands
18940 This filter supports the following commands:
18943 Close the current segment and step to the next one
18946 @section drawgraph, adrawgraph
18948 Draw a graph using input video or audio metadata.
18950 It accepts the following parameters:
18954 Set 1st frame metadata key from which metadata values will be used to draw a graph.
18957 Set 1st foreground color expression.
18960 Set 2nd frame metadata key from which metadata values will be used to draw a graph.
18963 Set 2nd foreground color expression.
18966 Set 3rd frame metadata key from which metadata values will be used to draw a graph.
18969 Set 3rd foreground color expression.
18972 Set 4th frame metadata key from which metadata values will be used to draw a graph.
18975 Set 4th foreground color expression.
18978 Set minimal value of metadata value.
18981 Set maximal value of metadata value.
18984 Set graph background color. Default is white.
18989 Available values for mode is:
18996 Default is @code{line}.
19001 Available values for slide is:
19004 Draw new frame when right border is reached.
19007 Replace old columns with new ones.
19010 Scroll from right to left.
19013 Scroll from left to right.
19016 Draw single picture.
19019 Default is @code{frame}.
19022 Set size of graph video. For the syntax of this option, check the
19023 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19024 The default value is @code{900x256}.
19026 The foreground color expressions can use the following variables:
19029 Minimal value of metadata value.
19032 Maximal value of metadata value.
19035 Current metadata key value.
19038 The color is defined as 0xAABBGGRR.
19041 Example using metadata from @ref{signalstats} filter:
19043 signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
19046 Example using metadata from @ref{ebur128} filter:
19048 ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
19054 EBU R128 scanner filter. This filter takes an audio stream as input and outputs
19055 it unchanged. By default, it logs a message at a frequency of 10Hz with the
19056 Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
19057 Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
19059 The filter also has a video output (see the @var{video} option) with a real
19060 time graph to observe the loudness evolution. The graphic contains the logged
19061 message mentioned above, so it is not printed anymore when this option is set,
19062 unless the verbose logging is set. The main graphing area contains the
19063 short-term loudness (3 seconds of analysis), and the gauge on the right is for
19064 the momentary loudness (400 milliseconds).
19066 More information about the Loudness Recommendation EBU R128 on
19067 @url{http://tech.ebu.ch/loudness}.
19069 The filter accepts the following options:
19074 Activate the video output. The audio stream is passed unchanged whether this
19075 option is set or no. The video stream will be the first output stream if
19076 activated. Default is @code{0}.
19079 Set the video size. This option is for video only. For the syntax of this
19081 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19082 Default and minimum resolution is @code{640x480}.
19085 Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
19086 @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
19087 other integer value between this range is allowed.
19090 Set metadata injection. If set to @code{1}, the audio input will be segmented
19091 into 100ms output frames, each of them containing various loudness information
19092 in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
19094 Default is @code{0}.
19097 Force the frame logging level.
19099 Available values are:
19102 information logging level
19104 verbose logging level
19107 By default, the logging level is set to @var{info}. If the @option{video} or
19108 the @option{metadata} options are set, it switches to @var{verbose}.
19113 Available modes can be cumulated (the option is a @code{flag} type). Possible
19117 Disable any peak mode (default).
19119 Enable sample-peak mode.
19121 Simple peak mode looking for the higher sample value. It logs a message
19122 for sample-peak (identified by @code{SPK}).
19124 Enable true-peak mode.
19126 If enabled, the peak lookup is done on an over-sampled version of the input
19127 stream for better peak accuracy. It logs a message for true-peak.
19128 (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
19129 This mode requires a build with @code{libswresample}.
19133 Treat mono input files as "dual mono". If a mono file is intended for playback
19134 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
19135 If set to @code{true}, this option will compensate for this effect.
19136 Multi-channel input files are not affected by this option.
19139 Set a specific pan law to be used for the measurement of dual mono files.
19140 This parameter is optional, and has a default value of -3.01dB.
19143 @subsection Examples
19147 Real-time graph using @command{ffplay}, with a EBU scale meter +18:
19149 ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
19153 Run an analysis with @command{ffmpeg}:
19155 ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
19159 @section interleave, ainterleave
19161 Temporally interleave frames from several inputs.
19163 @code{interleave} works with video inputs, @code{ainterleave} with audio.
19165 These filters read frames from several inputs and send the oldest
19166 queued frame to the output.
19168 Input streams must have well defined, monotonically increasing frame
19171 In order to submit one frame to output, these filters need to enqueue
19172 at least one frame for each input, so they cannot work in case one
19173 input is not yet terminated and will not receive incoming frames.
19175 For example consider the case when one input is a @code{select} filter
19176 which always drops input frames. The @code{interleave} filter will keep
19177 reading from that input, but it will never be able to send new frames
19178 to output until the input sends an end-of-stream signal.
19180 Also, depending on inputs synchronization, the filters will drop
19181 frames in case one input receives more frames than the other ones, and
19182 the queue is already filled.
19184 These filters accept the following options:
19188 Set the number of different inputs, it is 2 by default.
19191 @subsection Examples
19195 Interleave frames belonging to different streams using @command{ffmpeg}:
19197 ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
19201 Add flickering blur effect:
19203 select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
19207 @section metadata, ametadata
19209 Manipulate frame metadata.
19211 This filter accepts the following options:
19215 Set mode of operation of the filter.
19217 Can be one of the following:
19221 If both @code{value} and @code{key} is set, select frames
19222 which have such metadata. If only @code{key} is set, select
19223 every frame that has such key in metadata.
19226 Add new metadata @code{key} and @code{value}. If key is already available
19230 Modify value of already present key.
19233 If @code{value} is set, delete only keys that have such value.
19234 Otherwise, delete key. If @code{key} is not set, delete all metadata values in
19238 Print key and its value if metadata was found. If @code{key} is not set print all
19239 metadata values available in frame.
19243 Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}.
19246 Set metadata value which will be used. This option is mandatory for
19247 @code{modify} and @code{add} mode.
19250 Which function to use when comparing metadata value and @code{value}.
19252 Can be one of following:
19256 Values are interpreted as strings, returns true if metadata value is same as @code{value}.
19259 Values are interpreted as strings, returns true if metadata value starts with
19260 the @code{value} option string.
19263 Values are interpreted as floats, returns true if metadata value is less than @code{value}.
19266 Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
19269 Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
19272 Values are interpreted as floats, returns true if expression from option @code{expr}
19277 Set expression which is used when @code{function} is set to @code{expr}.
19278 The expression is evaluated through the eval API and can contain the following
19283 Float representation of @code{value} from metadata key.
19286 Float representation of @code{value} as supplied by user in @code{value} option.
19290 If specified in @code{print} mode, output is written to the named file. Instead of
19291 plain filename any writable url can be specified. Filename ``-'' is a shorthand
19292 for standard output. If @code{file} option is not set, output is written to the log
19293 with AV_LOG_INFO loglevel.
19297 @subsection Examples
19301 Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values
19304 signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
19307 Print silencedetect output to file @file{metadata.txt}.
19309 silencedetect,ametadata=mode=print:file=metadata.txt
19312 Direct all metadata to a pipe with file descriptor 4.
19314 metadata=mode=print:file='pipe\:4'
19318 @section perms, aperms
19320 Set read/write permissions for the output frames.
19322 These filters are mainly aimed at developers to test direct path in the
19323 following filter in the filtergraph.
19325 The filters accept the following options:
19329 Select the permissions mode.
19331 It accepts the following values:
19334 Do nothing. This is the default.
19336 Set all the output frames read-only.
19338 Set all the output frames directly writable.
19340 Make the frame read-only if writable, and writable if read-only.
19342 Set each output frame read-only or writable randomly.
19346 Set the seed for the @var{random} mode, must be an integer included between
19347 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
19348 @code{-1}, the filter will try to use a good random seed on a best effort
19352 Note: in case of auto-inserted filter between the permission filter and the
19353 following one, the permission might not be received as expected in that
19354 following filter. Inserting a @ref{format} or @ref{aformat} filter before the
19355 perms/aperms filter can avoid this problem.
19357 @section realtime, arealtime
19359 Slow down filtering to match real time approximately.
19361 These filters will pause the filtering for a variable amount of time to
19362 match the output rate with the input timestamps.
19363 They are similar to the @option{re} option to @code{ffmpeg}.
19365 They accept the following options:
19369 Time limit for the pauses. Any pause longer than that will be considered
19370 a timestamp discontinuity and reset the timer. Default is 2 seconds.
19374 @section select, aselect
19376 Select frames to pass in output.
19378 This filter accepts the following options:
19383 Set expression, which is evaluated for each input frame.
19385 If the expression is evaluated to zero, the frame is discarded.
19387 If the evaluation result is negative or NaN, the frame is sent to the
19388 first output; otherwise it is sent to the output with index
19389 @code{ceil(val)-1}, assuming that the input index starts from 0.
19391 For example a value of @code{1.2} corresponds to the output with index
19392 @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
19395 Set the number of outputs. The output to which to send the selected
19396 frame is based on the result of the evaluation. Default value is 1.
19399 The expression can contain the following constants:
19403 The (sequential) number of the filtered frame, starting from 0.
19406 The (sequential) number of the selected frame, starting from 0.
19408 @item prev_selected_n
19409 The sequential number of the last selected frame. It's NAN if undefined.
19412 The timebase of the input timestamps.
19415 The PTS (Presentation TimeStamp) of the filtered video frame,
19416 expressed in @var{TB} units. It's NAN if undefined.
19419 The PTS of the filtered video frame,
19420 expressed in seconds. It's NAN if undefined.
19423 The PTS of the previously filtered video frame. It's NAN if undefined.
19425 @item prev_selected_pts
19426 The PTS of the last previously filtered video frame. It's NAN if undefined.
19428 @item prev_selected_t
19429 The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined.
19432 The PTS of the first video frame in the video. It's NAN if undefined.
19435 The time of the first video frame in the video. It's NAN if undefined.
19437 @item pict_type @emph{(video only)}
19438 The type of the filtered frame. It can assume one of the following
19450 @item interlace_type @emph{(video only)}
19451 The frame interlace type. It can assume one of the following values:
19454 The frame is progressive (not interlaced).
19456 The frame is top-field-first.
19458 The frame is bottom-field-first.
19461 @item consumed_sample_n @emph{(audio only)}
19462 the number of selected samples before the current frame
19464 @item samples_n @emph{(audio only)}
19465 the number of samples in the current frame
19467 @item sample_rate @emph{(audio only)}
19468 the input sample rate
19471 This is 1 if the filtered frame is a key-frame, 0 otherwise.
19474 the position in the file of the filtered frame, -1 if the information
19475 is not available (e.g. for synthetic video)
19477 @item scene @emph{(video only)}
19478 value between 0 and 1 to indicate a new scene; a low value reflects a low
19479 probability for the current frame to introduce a new scene, while a higher
19480 value means the current frame is more likely to be one (see the example below)
19482 @item concatdec_select
19483 The concat demuxer can select only part of a concat input file by setting an
19484 inpoint and an outpoint, but the output packets may not be entirely contained
19485 in the selected interval. By using this variable, it is possible to skip frames
19486 generated by the concat demuxer which are not exactly contained in the selected
19489 This works by comparing the frame pts against the @var{lavf.concat.start_time}
19490 and the @var{lavf.concat.duration} packet metadata values which are also
19491 present in the decoded frames.
19493 The @var{concatdec_select} variable is -1 if the frame pts is at least
19494 start_time and either the duration metadata is missing or the frame pts is less
19495 than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
19498 That basically means that an input frame is selected if its pts is within the
19499 interval set by the concat demuxer.
19503 The default value of the select expression is "1".
19505 @subsection Examples
19509 Select all frames in input:
19514 The example above is the same as:
19526 Select only I-frames:
19528 select='eq(pict_type\,I)'
19532 Select one frame every 100:
19534 select='not(mod(n\,100))'
19538 Select only frames contained in the 10-20 time interval:
19540 select=between(t\,10\,20)
19544 Select only I-frames contained in the 10-20 time interval:
19546 select=between(t\,10\,20)*eq(pict_type\,I)
19550 Select frames with a minimum distance of 10 seconds:
19552 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
19556 Use aselect to select only audio frames with samples number > 100:
19558 aselect='gt(samples_n\,100)'
19562 Create a mosaic of the first scenes:
19564 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
19567 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
19571 Send even and odd frames to separate outputs, and compose them:
19573 select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
19577 Select useful frames from an ffconcat file which is using inpoints and
19578 outpoints but where the source files are not intra frame only.
19580 ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
19584 @section sendcmd, asendcmd
19586 Send commands to filters in the filtergraph.
19588 These filters read commands to be sent to other filters in the
19591 @code{sendcmd} must be inserted between two video filters,
19592 @code{asendcmd} must be inserted between two audio filters, but apart
19593 from that they act the same way.
19595 The specification of commands can be provided in the filter arguments
19596 with the @var{commands} option, or in a file specified by the
19597 @var{filename} option.
19599 These filters accept the following options:
19602 Set the commands to be read and sent to the other filters.
19604 Set the filename of the commands to be read and sent to the other
19608 @subsection Commands syntax
19610 A commands description consists of a sequence of interval
19611 specifications, comprising a list of commands to be executed when a
19612 particular event related to that interval occurs. The occurring event
19613 is typically the current frame time entering or leaving a given time
19616 An interval is specified by the following syntax:
19618 @var{START}[-@var{END}] @var{COMMANDS};
19621 The time interval is specified by the @var{START} and @var{END} times.
19622 @var{END} is optional and defaults to the maximum time.
19624 The current frame time is considered within the specified interval if
19625 it is included in the interval [@var{START}, @var{END}), that is when
19626 the time is greater or equal to @var{START} and is lesser than
19629 @var{COMMANDS} consists of a sequence of one or more command
19630 specifications, separated by ",", relating to that interval. The
19631 syntax of a command specification is given by:
19633 [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
19636 @var{FLAGS} is optional and specifies the type of events relating to
19637 the time interval which enable sending the specified command, and must
19638 be a non-null sequence of identifier flags separated by "+" or "|" and
19639 enclosed between "[" and "]".
19641 The following flags are recognized:
19644 The command is sent when the current frame timestamp enters the
19645 specified interval. In other words, the command is sent when the
19646 previous frame timestamp was not in the given interval, and the
19650 The command is sent when the current frame timestamp leaves the
19651 specified interval. In other words, the command is sent when the
19652 previous frame timestamp was in the given interval, and the
19656 If @var{FLAGS} is not specified, a default value of @code{[enter]} is
19659 @var{TARGET} specifies the target of the command, usually the name of
19660 the filter class or a specific filter instance name.
19662 @var{COMMAND} specifies the name of the command for the target filter.
19664 @var{ARG} is optional and specifies the optional list of argument for
19665 the given @var{COMMAND}.
19667 Between one interval specification and another, whitespaces, or
19668 sequences of characters starting with @code{#} until the end of line,
19669 are ignored and can be used to annotate comments.
19671 A simplified BNF description of the commands specification syntax
19674 @var{COMMAND_FLAG} ::= "enter" | "leave"
19675 @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
19676 @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
19677 @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
19678 @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
19679 @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
19682 @subsection Examples
19686 Specify audio tempo change at second 4:
19688 asendcmd=c='4.0 atempo tempo 1.5',atempo
19692 Target a specific filter instance:
19694 asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my
19698 Specify a list of drawtext and hue commands in a file.
19700 # show text in the interval 5-10
19701 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
19702 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
19704 # desaturate the image in the interval 15-20
19705 15.0-20.0 [enter] hue s 0,
19706 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
19708 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
19710 # apply an exponential saturation fade-out effect, starting from time 25
19711 25 [enter] hue s exp(25-t)
19714 A filtergraph allowing to read and process the above command list
19715 stored in a file @file{test.cmd}, can be specified with:
19717 sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
19722 @section setpts, asetpts
19724 Change the PTS (presentation timestamp) of the input frames.
19726 @code{setpts} works on video frames, @code{asetpts} on audio frames.
19728 This filter accepts the following options:
19733 The expression which is evaluated for each frame to construct its timestamp.
19737 The expression is evaluated through the eval API and can contain the following
19741 @item FRAME_RATE, FR
19742 frame rate, only defined for constant frame-rate video
19745 The presentation timestamp in input
19748 The count of the input frame for video or the number of consumed samples,
19749 not including the current frame for audio, starting from 0.
19751 @item NB_CONSUMED_SAMPLES
19752 The number of consumed samples, not including the current frame (only
19755 @item NB_SAMPLES, S
19756 The number of samples in the current frame (only audio)
19758 @item SAMPLE_RATE, SR
19759 The audio sample rate.
19762 The PTS of the first frame.
19765 the time in seconds of the first frame
19768 State whether the current frame is interlaced.
19771 the time in seconds of the current frame
19774 original position in the file of the frame, or undefined if undefined
19775 for the current frame
19778 The previous input PTS.
19781 previous input time in seconds
19784 The previous output PTS.
19787 previous output time in seconds
19790 The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
19794 The wallclock (RTC) time at the start of the movie in microseconds.
19797 The timebase of the input timestamps.
19801 @subsection Examples
19805 Start counting PTS from zero
19807 setpts=PTS-STARTPTS
19811 Apply fast motion effect:
19817 Apply slow motion effect:
19823 Set fixed rate of 25 frames per second:
19829 Set fixed rate 25 fps with some jitter:
19831 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
19835 Apply an offset of 10 seconds to the input PTS:
19841 Generate timestamps from a "live source" and rebase onto the current timebase:
19843 setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
19847 Generate timestamps by counting samples:
19856 Force color range for the output video frame.
19858 The @code{setrange} filter marks the color range property for the
19859 output frames. It does not change the input frame, but only sets the
19860 corresponding property, which affects how the frame is treated by
19863 The filter accepts the following options:
19868 Available values are:
19872 Keep the same color range property.
19874 @item unspecified, unknown
19875 Set the color range as unspecified.
19877 @item limited, tv, mpeg
19878 Set the color range as limited.
19880 @item full, pc, jpeg
19881 Set the color range as full.
19885 @section settb, asettb
19887 Set the timebase to use for the output frames timestamps.
19888 It is mainly useful for testing timebase configuration.
19890 It accepts the following parameters:
19895 The expression which is evaluated into the output timebase.
19899 The value for @option{tb} is an arithmetic expression representing a
19900 rational. The expression can contain the constants "AVTB" (the default
19901 timebase), "intb" (the input timebase) and "sr" (the sample rate,
19902 audio only). Default value is "intb".
19904 @subsection Examples
19908 Set the timebase to 1/25:
19914 Set the timebase to 1/10:
19920 Set the timebase to 1001/1000:
19926 Set the timebase to 2*intb:
19932 Set the default timebase value:
19939 Convert input audio to a video output representing frequency spectrum
19940 logarithmically using Brown-Puckette constant Q transform algorithm with
19941 direct frequency domain coefficient calculation (but the transform itself
19942 is not really constant Q, instead the Q factor is actually variable/clamped),
19943 with musical tone scale, from E0 to D#10.
19945 The filter accepts the following options:
19949 Specify the video size for the output. It must be even. For the syntax of this option,
19950 check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19951 Default value is @code{1920x1080}.
19954 Set the output frame rate. Default value is @code{25}.
19957 Set the bargraph height. It must be even. Default value is @code{-1} which
19958 computes the bargraph height automatically.
19961 Set the axis height. It must be even. Default value is @code{-1} which computes
19962 the axis height automatically.
19965 Set the sonogram height. It must be even. Default value is @code{-1} which
19966 computes the sonogram height automatically.
19969 Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
19970 instead. Default value is @code{1}.
19972 @item sono_v, volume
19973 Specify the sonogram volume expression. It can contain variables:
19976 the @var{bar_v} evaluated expression
19977 @item frequency, freq, f
19978 the frequency where it is evaluated
19979 @item timeclamp, tc
19980 the value of @var{timeclamp} option
19984 @item a_weighting(f)
19985 A-weighting of equal loudness
19986 @item b_weighting(f)
19987 B-weighting of equal loudness
19988 @item c_weighting(f)
19989 C-weighting of equal loudness.
19991 Default value is @code{16}.
19993 @item bar_v, volume2
19994 Specify the bargraph volume expression. It can contain variables:
19997 the @var{sono_v} evaluated expression
19998 @item frequency, freq, f
19999 the frequency where it is evaluated
20000 @item timeclamp, tc
20001 the value of @var{timeclamp} option
20005 @item a_weighting(f)
20006 A-weighting of equal loudness
20007 @item b_weighting(f)
20008 B-weighting of equal loudness
20009 @item c_weighting(f)
20010 C-weighting of equal loudness.
20012 Default value is @code{sono_v}.
20014 @item sono_g, gamma
20015 Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
20016 higher gamma makes the spectrum having more range. Default value is @code{3}.
20017 Acceptable range is @code{[1, 7]}.
20019 @item bar_g, gamma2
20020 Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
20024 Specify the bargraph transparency level. Lower value makes the bargraph sharper.
20025 Default value is @code{1}. Acceptable range is @code{[0, 1]}.
20027 @item timeclamp, tc
20028 Specify the transform timeclamp. At low frequency, there is trade-off between
20029 accuracy in time domain and frequency domain. If timeclamp is lower,
20030 event in time domain is represented more accurately (such as fast bass drum),
20031 otherwise event in frequency domain is represented more accurately
20032 (such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}.
20035 Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it
20036 limits future samples by applying asymmetric windowing in time domain, useful
20037 when low latency is required. Accepted range is @code{[0, 1]}.
20040 Specify the transform base frequency. Default value is @code{20.01523126408007475},
20041 which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
20044 Specify the transform end frequency. Default value is @code{20495.59681441799654},
20045 which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
20048 This option is deprecated and ignored.
20051 Specify the transform length in time domain. Use this option to control accuracy
20052 trade-off between time domain and frequency domain at every frequency sample.
20053 It can contain variables:
20055 @item frequency, freq, f
20056 the frequency where it is evaluated
20057 @item timeclamp, tc
20058 the value of @var{timeclamp} option.
20060 Default value is @code{384*tc/(384+tc*f)}.
20063 Specify the transform count for every video frame. Default value is @code{6}.
20064 Acceptable range is @code{[1, 30]}.
20067 Specify the transform count for every single pixel. Default value is @code{0},
20068 which makes it computed automatically. Acceptable range is @code{[0, 10]}.
20071 Specify font file for use with freetype to draw the axis. If not specified,
20072 use embedded font. Note that drawing with font file or embedded font is not
20073 implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
20077 Specify fontconfig pattern. This has lower priority than @var{fontfile}.
20078 The : in the pattern may be replaced by | to avoid unnecessary escaping.
20081 Specify font color expression. This is arithmetic expression that should return
20082 integer value 0xRRGGBB. It can contain variables:
20084 @item frequency, freq, f
20085 the frequency where it is evaluated
20086 @item timeclamp, tc
20087 the value of @var{timeclamp} option
20092 midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
20093 @item r(x), g(x), b(x)
20094 red, green, and blue value of intensity x.
20096 Default value is @code{st(0, (midi(f)-59.5)/12);
20097 st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
20098 r(1-ld(1)) + b(ld(1))}.
20101 Specify image file to draw the axis. This option override @var{fontfile} and
20102 @var{fontcolor} option.
20105 Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
20106 the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
20107 Default value is @code{1}.
20110 Set colorspace. The accepted values are:
20113 Unspecified (default)
20122 BT.470BG or BT.601-6 625
20125 SMPTE-170M or BT.601-6 525
20131 BT.2020 with non-constant luminance
20136 Set spectrogram color scheme. This is list of floating point values with format
20137 @code{left_r|left_g|left_b|right_r|right_g|right_b}.
20138 The default is @code{1|0.5|0|0|0.5|1}.
20142 @subsection Examples
20146 Playing audio while showing the spectrum:
20148 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
20152 Same as above, but with frame rate 30 fps:
20154 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
20158 Playing at 1280x720:
20160 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
20164 Disable sonogram display:
20170 A1 and its harmonics: A1, A2, (near)E3, A3:
20172 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),
20173 asplit[a][out1]; [a] showcqt [out0]'
20177 Same as above, but with more accuracy in frequency domain:
20179 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),
20180 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
20186 bar_v=10:sono_v=bar_v*a_weighting(f)
20190 Custom gamma, now spectrum is linear to the amplitude.
20196 Custom tlength equation:
20198 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)))'
20202 Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
20204 fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
20208 Custom font using fontconfig:
20210 font='Courier New,Monospace,mono|bold'
20214 Custom frequency range with custom axis using image file:
20216 axisfile=myaxis.png:basefreq=40:endfreq=10000
20222 Convert input audio to video output representing the audio power spectrum.
20223 Audio amplitude is on Y-axis while frequency is on X-axis.
20225 The filter accepts the following options:
20229 Specify size of video. For the syntax of this option, check the
20230 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20231 Default is @code{1024x512}.
20235 This set how each frequency bin will be represented.
20237 It accepts the following values:
20243 Default is @code{bar}.
20246 Set amplitude scale.
20248 It accepts the following values:
20262 Default is @code{log}.
20265 Set frequency scale.
20267 It accepts the following values:
20276 Reverse logarithmic scale.
20278 Default is @code{lin}.
20283 It accepts the following values:
20299 Default is @code{w2048}
20302 Set windowing function.
20304 It accepts the following values:
20326 Default is @code{hanning}.
20329 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
20330 which means optimal overlap for selected window function will be picked.
20333 Set time averaging. Setting this to 0 will display current maximal peaks.
20334 Default is @code{1}, which means time averaging is disabled.
20337 Specify list of colors separated by space or by '|' which will be used to
20338 draw channel frequencies. Unrecognized or missing colors will be replaced
20342 Set channel display mode.
20344 It accepts the following values:
20349 Default is @code{combined}.
20352 Set minimum amplitude used in @code{log} amplitude scaler.
20356 @anchor{showspectrum}
20357 @section showspectrum
20359 Convert input audio to a video output, representing the audio frequency
20362 The filter accepts the following options:
20366 Specify the video size for the output. For the syntax of this option, check the
20367 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20368 Default value is @code{640x512}.
20371 Specify how the spectrum should slide along the window.
20373 It accepts the following values:
20376 the samples start again on the left when they reach the right
20378 the samples scroll from right to left
20380 frames are only produced when the samples reach the right
20382 the samples scroll from left to right
20385 Default value is @code{replace}.
20388 Specify display mode.
20390 It accepts the following values:
20393 all channels are displayed in the same row
20395 all channels are displayed in separate rows
20398 Default value is @samp{combined}.
20401 Specify display color mode.
20403 It accepts the following values:
20406 each channel is displayed in a separate color
20408 each channel is displayed using the same color scheme
20410 each channel is displayed using the rainbow color scheme
20412 each channel is displayed using the moreland color scheme
20414 each channel is displayed using the nebulae color scheme
20416 each channel is displayed using the fire color scheme
20418 each channel is displayed using the fiery color scheme
20420 each channel is displayed using the fruit color scheme
20422 each channel is displayed using the cool color scheme
20425 Default value is @samp{channel}.
20428 Specify scale used for calculating intensity color values.
20430 It accepts the following values:
20435 square root, default
20446 Default value is @samp{sqrt}.
20449 Set saturation modifier for displayed colors. Negative values provide
20450 alternative color scheme. @code{0} is no saturation at all.
20451 Saturation must be in [-10.0, 10.0] range.
20452 Default value is @code{1}.
20455 Set window function.
20457 It accepts the following values:
20481 Default value is @code{hann}.
20484 Set orientation of time vs frequency axis. Can be @code{vertical} or
20485 @code{horizontal}. Default is @code{vertical}.
20488 Set ratio of overlap window. Default value is @code{0}.
20489 When value is @code{1} overlap is set to recommended size for specific
20490 window function currently used.
20493 Set scale gain for calculating intensity color values.
20494 Default value is @code{1}.
20497 Set which data to display. Can be @code{magnitude}, default or @code{phase}.
20500 Set color rotation, must be in [-1.0, 1.0] range.
20501 Default value is @code{0}.
20504 The usage is very similar to the showwaves filter; see the examples in that
20507 @subsection Examples
20511 Large window with logarithmic color scaling:
20513 showspectrum=s=1280x480:scale=log
20517 Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
20519 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
20520 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
20524 @section showspectrumpic
20526 Convert input audio to a single video frame, representing the audio frequency
20529 The filter accepts the following options:
20533 Specify the video size for the output. For the syntax of this option, check the
20534 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20535 Default value is @code{4096x2048}.
20538 Specify display mode.
20540 It accepts the following values:
20543 all channels are displayed in the same row
20545 all channels are displayed in separate rows
20547 Default value is @samp{combined}.
20550 Specify display color mode.
20552 It accepts the following values:
20555 each channel is displayed in a separate color
20557 each channel is displayed using the same color scheme
20559 each channel is displayed using the rainbow color scheme
20561 each channel is displayed using the moreland color scheme
20563 each channel is displayed using the nebulae color scheme
20565 each channel is displayed using the fire color scheme
20567 each channel is displayed using the fiery color scheme
20569 each channel is displayed using the fruit color scheme
20571 each channel is displayed using the cool color scheme
20573 Default value is @samp{intensity}.
20576 Specify scale used for calculating intensity color values.
20578 It accepts the following values:
20583 square root, default
20593 Default value is @samp{log}.
20596 Set saturation modifier for displayed colors. Negative values provide
20597 alternative color scheme. @code{0} is no saturation at all.
20598 Saturation must be in [-10.0, 10.0] range.
20599 Default value is @code{1}.
20602 Set window function.
20604 It accepts the following values:
20627 Default value is @code{hann}.
20630 Set orientation of time vs frequency axis. Can be @code{vertical} or
20631 @code{horizontal}. Default is @code{vertical}.
20634 Set scale gain for calculating intensity color values.
20635 Default value is @code{1}.
20638 Draw time and frequency axes and legends. Default is enabled.
20641 Set color rotation, must be in [-1.0, 1.0] range.
20642 Default value is @code{0}.
20645 @subsection Examples
20649 Extract an audio spectrogram of a whole audio track
20650 in a 1024x1024 picture using @command{ffmpeg}:
20652 ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
20656 @section showvolume
20658 Convert input audio volume to a video output.
20660 The filter accepts the following options:
20667 Set border width, allowed range is [0, 5]. Default is 1.
20670 Set channel width, allowed range is [80, 8192]. Default is 400.
20673 Set channel height, allowed range is [1, 900]. Default is 20.
20676 Set fade, allowed range is [0, 1]. Default is 0.95.
20679 Set volume color expression.
20681 The expression can use the following variables:
20685 Current max volume of channel in dB.
20691 Current channel number, starting from 0.
20695 If set, displays channel names. Default is enabled.
20698 If set, displays volume values. Default is enabled.
20701 Set orientation, can be horizontal: @code{h} or vertical: @code{v},
20702 default is @code{h}.
20705 Set step size, allowed range is [0, 5]. Default is 0, which means
20709 Set background opacity, allowed range is [0, 1]. Default is 0.
20712 Set metering mode, can be peak: @code{p} or rms: @code{r},
20713 default is @code{p}.
20716 Set display scale, can be linear: @code{lin} or log: @code{log},
20717 default is @code{lin}.
20721 If set to > 0., display a line for the max level
20722 in the previous seconds.
20723 default is disabled: @code{0.}
20726 The color of the max line. Use when @code{dm} option is set to > 0.
20727 default is: @code{orange}
20732 Convert input audio to a video output, representing the samples waves.
20734 The filter accepts the following options:
20738 Specify the video size for the output. For the syntax of this option, check the
20739 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20740 Default value is @code{600x240}.
20745 Available values are:
20748 Draw a point for each sample.
20751 Draw a vertical line for each sample.
20754 Draw a point for each sample and a line between them.
20757 Draw a centered vertical line for each sample.
20760 Default value is @code{point}.
20763 Set the number of samples which are printed on the same column. A
20764 larger value will decrease the frame rate. Must be a positive
20765 integer. This option can be set only if the value for @var{rate}
20766 is not explicitly specified.
20769 Set the (approximate) output frame rate. This is done by setting the
20770 option @var{n}. Default value is "25".
20772 @item split_channels
20773 Set if channels should be drawn separately or overlap. Default value is 0.
20776 Set colors separated by '|' which are going to be used for drawing of each channel.
20779 Set amplitude scale.
20781 Available values are:
20799 Set the draw mode. This is mostly useful to set for high @var{n}.
20801 Available values are:
20804 Scale pixel values for each drawn sample.
20807 Draw every sample directly.
20810 Default value is @code{scale}.
20813 @subsection Examples
20817 Output the input file audio and the corresponding video representation
20820 amovie=a.mp3,asplit[out0],showwaves[out1]
20824 Create a synthetic signal and show it with showwaves, forcing a
20825 frame rate of 30 frames per second:
20827 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
20831 @section showwavespic
20833 Convert input audio to a single video frame, representing the samples waves.
20835 The filter accepts the following options:
20839 Specify the video size for the output. For the syntax of this option, check the
20840 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20841 Default value is @code{600x240}.
20843 @item split_channels
20844 Set if channels should be drawn separately or overlap. Default value is 0.
20847 Set colors separated by '|' which are going to be used for drawing of each channel.
20850 Set amplitude scale.
20852 Available values are:
20870 @subsection Examples
20874 Extract a channel split representation of the wave form of a whole audio track
20875 in a 1024x800 picture using @command{ffmpeg}:
20877 ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
20881 @section sidedata, asidedata
20883 Delete frame side data, or select frames based on it.
20885 This filter accepts the following options:
20889 Set mode of operation of the filter.
20891 Can be one of the following:
20895 Select every frame with side data of @code{type}.
20898 Delete side data of @code{type}. If @code{type} is not set, delete all side
20904 Set side data type used with all modes. Must be set for @code{select} mode. For
20905 the list of frame side data types, refer to the @code{AVFrameSideDataType} enum
20906 in @file{libavutil/frame.h}. For example, to choose
20907 @code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}.
20911 @section spectrumsynth
20913 Sythesize audio from 2 input video spectrums, first input stream represents
20914 magnitude across time and second represents phase across time.
20915 The filter will transform from frequency domain as displayed in videos back
20916 to time domain as presented in audio output.
20918 This filter is primarily created for reversing processed @ref{showspectrum}
20919 filter outputs, but can synthesize sound from other spectrograms too.
20920 But in such case results are going to be poor if the phase data is not
20921 available, because in such cases phase data need to be recreated, usually
20922 its just recreated from random noise.
20923 For best results use gray only output (@code{channel} color mode in
20924 @ref{showspectrum} filter) and @code{log} scale for magnitude video and
20925 @code{lin} scale for phase video. To produce phase, for 2nd video, use
20926 @code{data} option. Inputs videos should generally use @code{fullframe}
20927 slide mode as that saves resources needed for decoding video.
20929 The filter accepts the following options:
20933 Specify sample rate of output audio, the sample rate of audio from which
20934 spectrum was generated may differ.
20937 Set number of channels represented in input video spectrums.
20940 Set scale which was used when generating magnitude input spectrum.
20941 Can be @code{lin} or @code{log}. Default is @code{log}.
20944 Set slide which was used when generating inputs spectrums.
20945 Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
20946 Default is @code{fullframe}.
20949 Set window function used for resynthesis.
20952 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
20953 which means optimal overlap for selected window function will be picked.
20956 Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
20957 Default is @code{vertical}.
20960 @subsection Examples
20964 First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
20965 then resynthesize videos back to audio with spectrumsynth:
20967 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
20968 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
20969 ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
20973 @section split, asplit
20975 Split input into several identical outputs.
20977 @code{asplit} works with audio input, @code{split} with video.
20979 The filter accepts a single parameter which specifies the number of outputs. If
20980 unspecified, it defaults to 2.
20982 @subsection Examples
20986 Create two separate outputs from the same input:
20988 [in] split [out0][out1]
20992 To create 3 or more outputs, you need to specify the number of
20995 [in] asplit=3 [out0][out1][out2]
20999 Create two separate outputs from the same input, one cropped and
21002 [in] split [splitout1][splitout2];
21003 [splitout1] crop=100:100:0:0 [cropout];
21004 [splitout2] pad=200:200:100:100 [padout];
21008 Create 5 copies of the input audio with @command{ffmpeg}:
21010 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
21016 Receive commands sent through a libzmq client, and forward them to
21017 filters in the filtergraph.
21019 @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
21020 must be inserted between two video filters, @code{azmq} between two
21021 audio filters. Both are capable to send messages to any filter type.
21023 To enable these filters you need to install the libzmq library and
21024 headers and configure FFmpeg with @code{--enable-libzmq}.
21026 For more information about libzmq see:
21027 @url{http://www.zeromq.org/}
21029 The @code{zmq} and @code{azmq} filters work as a libzmq server, which
21030 receives messages sent through a network interface defined by the
21031 @option{bind_address} (or the abbreviation "@option{b}") option.
21032 Default value of this option is @file{tcp://localhost:5555}. You may
21033 want to alter this value to your needs, but do not forget to escape any
21034 ':' signs (see @ref{filtergraph escaping}).
21036 The received message must be in the form:
21038 @var{TARGET} @var{COMMAND} [@var{ARG}]
21041 @var{TARGET} specifies the target of the command, usually the name of
21042 the filter class or a specific filter instance name. The default
21043 filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>},
21044 but you can override this by using the @samp{filter_name@@id} syntax
21045 (see @ref{Filtergraph syntax}).
21047 @var{COMMAND} specifies the name of the command for the target filter.
21049 @var{ARG} is optional and specifies the optional argument list for the
21050 given @var{COMMAND}.
21052 Upon reception, the message is processed and the corresponding command
21053 is injected into the filtergraph. Depending on the result, the filter
21054 will send a reply to the client, adopting the format:
21056 @var{ERROR_CODE} @var{ERROR_REASON}
21060 @var{MESSAGE} is optional.
21062 @subsection Examples
21064 Look at @file{tools/zmqsend} for an example of a zmq client which can
21065 be used to send commands processed by these filters.
21067 Consider the following filtergraph generated by @command{ffplay}.
21068 In this example the last overlay filter has an instance name. All other
21069 filters will have default instance names.
21072 ffplay -dumpgraph 1 -f lavfi "
21073 color=s=100x100:c=red [l];
21074 color=s=100x100:c=blue [r];
21075 nullsrc=s=200x100, zmq [bg];
21076 [bg][l] overlay [bg+l];
21077 [bg+l][r] overlay@@my=x=100 "
21080 To change the color of the left side of the video, the following
21081 command can be used:
21083 echo Parsed_color_0 c yellow | tools/zmqsend
21086 To change the right side:
21088 echo Parsed_color_1 c pink | tools/zmqsend
21091 To change the position of the right side:
21093 echo overlay@@my x 150 | tools/zmqsend
21097 @c man end MULTIMEDIA FILTERS
21099 @chapter Multimedia Sources
21100 @c man begin MULTIMEDIA SOURCES
21102 Below is a description of the currently available multimedia sources.
21106 This is the same as @ref{movie} source, except it selects an audio
21112 Read audio and/or video stream(s) from a movie container.
21114 It accepts the following parameters:
21118 The name of the resource to read (not necessarily a file; it can also be a
21119 device or a stream accessed through some protocol).
21121 @item format_name, f
21122 Specifies the format assumed for the movie to read, and can be either
21123 the name of a container or an input device. If not specified, the
21124 format is guessed from @var{movie_name} or by probing.
21126 @item seek_point, sp
21127 Specifies the seek point in seconds. The frames will be output
21128 starting from this seek point. The parameter is evaluated with
21129 @code{av_strtod}, so the numerical value may be suffixed by an IS
21130 postfix. The default value is "0".
21133 Specifies the streams to read. Several streams can be specified,
21134 separated by "+". The source will then have as many outputs, in the
21135 same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers"
21136 section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify
21137 respectively the default (best suited) video and audio stream. Default
21138 is "dv", or "da" if the filter is called as "amovie".
21140 @item stream_index, si
21141 Specifies the index of the video stream to read. If the value is -1,
21142 the most suitable video stream will be automatically selected. The default
21143 value is "-1". Deprecated. If the filter is called "amovie", it will select
21144 audio instead of video.
21147 Specifies how many times to read the stream in sequence.
21148 If the value is 0, the stream will be looped infinitely.
21149 Default value is "1".
21151 Note that when the movie is looped the source timestamps are not
21152 changed, so it will generate non monotonically increasing timestamps.
21154 @item discontinuity
21155 Specifies the time difference between frames above which the point is
21156 considered a timestamp discontinuity which is removed by adjusting the later
21160 It allows overlaying a second video on top of the main input of
21161 a filtergraph, as shown in this graph:
21163 input -----------> deltapts0 --> overlay --> output
21166 movie --> scale--> deltapts1 -------+
21168 @subsection Examples
21172 Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
21173 on top of the input labelled "in":
21175 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
21176 [in] setpts=PTS-STARTPTS [main];
21177 [main][over] overlay=16:16 [out]
21181 Read from a video4linux2 device, and overlay it on top of the input
21184 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
21185 [in] setpts=PTS-STARTPTS [main];
21186 [main][over] overlay=16:16 [out]
21190 Read the first video stream and the audio stream with id 0x81 from
21191 dvd.vob; the video is connected to the pad named "video" and the audio is
21192 connected to the pad named "audio":
21194 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
21198 @subsection Commands
21200 Both movie and amovie support the following commands:
21203 Perform seek using "av_seek_frame".
21204 The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
21207 @var{stream_index}: If stream_index is -1, a default
21208 stream is selected, and @var{timestamp} is automatically converted
21209 from AV_TIME_BASE units to the stream specific time_base.
21211 @var{timestamp}: Timestamp in AVStream.time_base units
21212 or, if no stream is specified, in AV_TIME_BASE units.
21214 @var{flags}: Flags which select direction and seeking mode.
21218 Get movie duration in AV_TIME_BASE units.
21222 @c man end MULTIMEDIA SOURCES