1 @chapter Filtering Introduction
2 @c man begin FILTERING INTRODUCTION
4 Filtering in FFmpeg is enabled through the libavfilter library.
6 In libavfilter, a filter can have multiple inputs and multiple
8 To illustrate the sorts of things that are possible, we consider the
13 input --> split ---------------------> overlay --> output
16 +-----> crop --> vflip -------+
19 This filtergraph splits the input stream in two streams, then sends one
20 stream through the crop filter and the vflip filter, before merging it
21 back with the other stream by overlaying it on top. You can use the
22 following command to achieve this:
25 ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT
28 The result will be that the top half of the video is mirrored
29 onto the bottom half of the output video.
31 Filters in the same linear chain are separated by commas, and distinct
32 linear chains of filters are separated by semicolons. In our example,
33 @var{crop,vflip} are in one linear chain, @var{split} and
34 @var{overlay} are separately in another. The points where the linear
35 chains join are labelled by names enclosed in square brackets. In the
36 example, the split filter generates two outputs that are associated to
37 the labels @var{[main]} and @var{[tmp]}.
39 The stream sent to the second output of @var{split}, labelled as
40 @var{[tmp]}, is processed through the @var{crop} filter, which crops
41 away the lower half part of the video, and then vertically flipped. The
42 @var{overlay} filter takes in input the first unchanged output of the
43 split filter (which was labelled as @var{[main]}), and overlay on its
44 lower half the output generated by the @var{crop,vflip} filterchain.
46 Some filters take in input a list of parameters: they are specified
47 after the filter name and an equal sign, and are separated from each other
50 There exist so-called @var{source filters} that do not have an
51 audio/video input, and @var{sink filters} that will not have audio/video
54 @c man end FILTERING INTRODUCTION
57 @c man begin GRAPH2DOT
59 The @file{graph2dot} program included in the FFmpeg @file{tools}
60 directory can be used to parse a filtergraph description and issue a
61 corresponding textual representation in the dot language.
68 to see how to use @file{graph2dot}.
70 You can then pass the dot description to the @file{dot} program (from
71 the graphviz suite of programs) and obtain a graphical representation
74 For example the sequence of commands:
76 echo @var{GRAPH_DESCRIPTION} | \
77 tools/graph2dot -o graph.tmp && \
78 dot -Tpng graph.tmp -o graph.png && \
82 can be used to create and display an image representing the graph
83 described by the @var{GRAPH_DESCRIPTION} string. Note that this string must be
84 a complete self-contained graph, with its inputs and outputs explicitly defined.
85 For example if your command line is of the form:
87 ffmpeg -i infile -vf scale=640:360 outfile
89 your @var{GRAPH_DESCRIPTION} string will need to be of the form:
91 nullsrc,scale=640:360,nullsink
93 you may also need to set the @var{nullsrc} parameters and add a @var{format}
94 filter in order to simulate a specific input file.
98 @chapter Filtergraph description
99 @c man begin FILTERGRAPH DESCRIPTION
101 A filtergraph is a directed graph of connected filters. It can contain
102 cycles, and there can be multiple links between a pair of
103 filters. Each link has one input pad on one side connecting it to one
104 filter from which it takes its input, and one output pad on the other
105 side connecting it to one filter accepting its output.
107 Each filter in a filtergraph is an instance of a filter class
108 registered in the application, which defines the features and the
109 number of input and output pads of the filter.
111 A filter with no input pads is called a "source", and a filter with no
112 output pads is called a "sink".
114 @anchor{Filtergraph syntax}
115 @section Filtergraph syntax
117 A filtergraph has a textual representation, which is recognized by the
118 @option{-filter}/@option{-vf}/@option{-af} and
119 @option{-filter_complex} options in @command{ffmpeg} and
120 @option{-vf}/@option{-af} in @command{ffplay}, and by the
121 @code{avfilter_graph_parse_ptr()} function defined in
122 @file{libavfilter/avfilter.h}.
124 A filterchain consists of a sequence of connected filters, each one
125 connected to the previous one in the sequence. A filterchain is
126 represented by a list of ","-separated filter descriptions.
128 A filtergraph consists of a sequence of filterchains. A sequence of
129 filterchains is represented by a list of ";"-separated filterchain
132 A filter is represented by a string of the form:
133 [@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}@@@var{id}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}]
135 @var{filter_name} is the name of the filter class of which the
136 described filter is an instance of, and has to be the name of one of
137 the filter classes registered in the program optionally followed by "@@@var{id}".
138 The name of the filter class is optionally followed by a string
141 @var{arguments} is a string which contains the parameters used to
142 initialize the filter instance. It may have one of two forms:
146 A ':'-separated list of @var{key=value} pairs.
149 A ':'-separated list of @var{value}. In this case, the keys are assumed to be
150 the option names in the order they are declared. E.g. the @code{fade} filter
151 declares three options in this order -- @option{type}, @option{start_frame} and
152 @option{nb_frames}. Then the parameter list @var{in:0:30} means that the value
153 @var{in} is assigned to the option @option{type}, @var{0} to
154 @option{start_frame} and @var{30} to @option{nb_frames}.
157 A ':'-separated list of mixed direct @var{value} and long @var{key=value}
158 pairs. The direct @var{value} must precede the @var{key=value} pairs, and
159 follow the same constraints order of the previous point. The following
160 @var{key=value} pairs can be set in any preferred order.
164 If the option value itself is a list of items (e.g. the @code{format} filter
165 takes a list of pixel formats), the items in the list are usually separated by
168 The list of arguments can be quoted using the character @samp{'} as initial
169 and ending mark, and the character @samp{\} for escaping the characters
170 within the quoted text; otherwise the argument string is considered
171 terminated when the next special character (belonging to the set
172 @samp{[]=;,}) is encountered.
174 The name and arguments of the filter are optionally preceded and
175 followed by a list of link labels.
176 A link label allows one to name a link and associate it to a filter output
177 or input pad. The preceding labels @var{in_link_1}
178 ... @var{in_link_N}, are associated to the filter input pads,
179 the following labels @var{out_link_1} ... @var{out_link_M}, are
180 associated to the output pads.
182 When two link labels with the same name are found in the
183 filtergraph, a link between the corresponding input and output pad is
186 If an output pad is not labelled, it is linked by default to the first
187 unlabelled input pad of the next filter in the filterchain.
188 For example in the filterchain
190 nullsrc, split[L1], [L2]overlay, nullsink
192 the split filter instance has two output pads, and the overlay filter
193 instance two input pads. The first output pad of split is labelled
194 "L1", the first input pad of overlay is labelled "L2", and the second
195 output pad of split is linked to the second input pad of overlay,
196 which are both unlabelled.
198 In a filter description, if the input label of the first filter is not
199 specified, "in" is assumed; if the output label of the last filter is not
200 specified, "out" is assumed.
202 In a complete filterchain all the unlabelled filter input and output
203 pads must be connected. A filtergraph is considered valid if all the
204 filter input and output pads of all the filterchains are connected.
206 Libavfilter will automatically insert @ref{scale} filters where format
207 conversion is required. It is possible to specify swscale flags
208 for those automatically inserted scalers by prepending
209 @code{sws_flags=@var{flags};}
210 to the filtergraph description.
212 Here is a BNF description of the filtergraph syntax:
214 @var{NAME} ::= sequence of alphanumeric characters and '_'
215 @var{FILTER_NAME} ::= @var{NAME}["@@"@var{NAME}]
216 @var{LINKLABEL} ::= "[" @var{NAME} "]"
217 @var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
218 @var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted)
219 @var{FILTER} ::= [@var{LINKLABELS}] @var{FILTER_NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]
220 @var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]
221 @var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
224 @anchor{filtergraph escaping}
225 @section Notes on filtergraph escaping
227 Filtergraph description composition entails several levels of
228 escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping"
229 section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more
230 information about the employed escaping procedure.
232 A first level escaping affects the content of each filter option
233 value, which may contain the special character @code{:} used to
234 separate values, or one of the escaping characters @code{\'}.
236 A second level escaping affects the whole filter description, which
237 may contain the escaping characters @code{\'} or the special
238 characters @code{[],;} used by the filtergraph description.
240 Finally, when you specify a filtergraph on a shell commandline, you
241 need to perform a third level escaping for the shell special
242 characters contained within it.
244 For example, consider the following string to be embedded in
245 the @ref{drawtext} filter description @option{text} value:
247 this is a 'string': may contain one, or more, special characters
250 This string contains the @code{'} special escaping character, and the
251 @code{:} special character, so it needs to be escaped in this way:
253 text=this is a \'string\'\: may contain one, or more, special characters
256 A second level of escaping is required when embedding the filter
257 description in a filtergraph description, in order to escape all the
258 filtergraph special characters. Thus the example above becomes:
260 drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
262 (note that in addition to the @code{\'} escaping special characters,
263 also @code{,} needs to be escaped).
265 Finally an additional level of escaping is needed when writing the
266 filtergraph description in a shell command, which depends on the
267 escaping rules of the adopted shell. For example, assuming that
268 @code{\} is special and needs to be escaped with another @code{\}, the
269 previous string will finally result in:
271 -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
274 @chapter Timeline editing
276 Some filters support a generic @option{enable} option. For the filters
277 supporting timeline editing, this option can be set to an expression which is
278 evaluated before sending a frame to the filter. If the evaluation is non-zero,
279 the filter will be enabled, otherwise the frame will be sent unchanged to the
280 next filter in the filtergraph.
282 The expression accepts the following values:
285 timestamp expressed in seconds, NAN if the input timestamp is unknown
288 sequential number of the input frame, starting from 0
291 the position in the file of the input frame, NAN if unknown
295 width and height of the input frame if video
298 Additionally, these filters support an @option{enable} command that can be used
299 to re-define the expression.
301 Like any other filtering option, the @option{enable} option follows the same
304 For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3
305 minutes, and a @ref{curves} filter starting at 3 seconds:
307 smartblur = enable='between(t,10,3*60)',
308 curves = enable='gte(t,3)' : preset=cross_process
311 See @code{ffmpeg -filters} to view which filters have timeline support.
313 @c man end FILTERGRAPH DESCRIPTION
316 @chapter Options for filters with several inputs (framesync)
317 @c man begin OPTIONS FOR FILTERS WITH SEVERAL INPUTS
319 Some filters with several inputs support a common set of options.
320 These options can only be set by name, not with the short notation.
324 The action to take when EOF is encountered on the secondary input; it accepts
325 one of the following values:
329 Repeat the last frame (the default).
333 Pass the main input through.
337 If set to 1, force the output to terminate when the shortest input
338 terminates. Default value is 0.
341 If set to 1, force the filter to extend the last frame of secondary streams
342 until the end of the primary stream. A value of 0 disables this behavior.
346 @c man end OPTIONS FOR FILTERS WITH SEVERAL INPUTS
348 @chapter Audio Filters
349 @c man begin AUDIO FILTERS
351 When you configure your FFmpeg build, you can disable any of the
352 existing filters using @code{--disable-filters}.
353 The configure output will show the audio filters included in your
356 Below is a description of the currently available audio filters.
360 A compressor is mainly used to reduce the dynamic range of a signal.
361 Especially modern music is mostly compressed at a high ratio to
362 improve the overall loudness. It's done to get the highest attention
363 of a listener, "fatten" the sound and bring more "power" to the track.
364 If a signal is compressed too much it may sound dull or "dead"
365 afterwards or it may start to "pump" (which could be a powerful effect
366 but can also destroy a track completely).
367 The right compression is the key to reach a professional sound and is
368 the high art of mixing and mastering. Because of its complex settings
369 it may take a long time to get the right feeling for this kind of effect.
371 Compression is done by detecting the volume above a chosen level
372 @code{threshold} and dividing it by the factor set with @code{ratio}.
373 So if you set the threshold to -12dB and your signal reaches -6dB a ratio
374 of 2:1 will result in a signal at -9dB. Because an exact manipulation of
375 the signal would cause distortion of the waveform the reduction can be
376 levelled over the time. This is done by setting "Attack" and "Release".
377 @code{attack} determines how long the signal has to rise above the threshold
378 before any reduction will occur and @code{release} sets the time the signal
379 has to fall below the threshold to reduce the reduction again. Shorter signals
380 than the chosen attack time will be left untouched.
381 The overall reduction of the signal can be made up afterwards with the
382 @code{makeup} setting. So compressing the peaks of a signal about 6dB and
383 raising the makeup to this level results in a signal twice as loud than the
384 source. To gain a softer entry in the compression the @code{knee} flattens the
385 hard edge at the threshold in the range of the chosen decibels.
387 The filter accepts the following options:
391 Set input gain. Default is 1. Range is between 0.015625 and 64.
394 If a signal of stream rises above this level it will affect the gain
396 By default it is 0.125. Range is between 0.00097563 and 1.
399 Set a ratio by which the signal is reduced. 1:2 means that if the level
400 rose 4dB above the threshold, it will be only 2dB above after the reduction.
401 Default is 2. Range is between 1 and 20.
404 Amount of milliseconds the signal has to rise above the threshold before gain
405 reduction starts. Default is 20. Range is between 0.01 and 2000.
408 Amount of milliseconds the signal has to fall below the threshold before
409 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
412 Set the amount by how much signal will be amplified after processing.
413 Default is 1. Range is from 1 to 64.
416 Curve the sharp knee around the threshold to enter gain reduction more softly.
417 Default is 2.82843. Range is between 1 and 8.
420 Choose if the @code{average} level between all channels of input stream
421 or the louder(@code{maximum}) channel of input stream affects the
422 reduction. Default is @code{average}.
425 Should the exact signal be taken in case of @code{peak} or an RMS one in case
426 of @code{rms}. Default is @code{rms} which is mostly smoother.
429 How much to use compressed signal in output. Default is 1.
430 Range is between 0 and 1.
434 Simple audio dynamic range commpression/expansion filter.
436 The filter accepts the following options:
440 Set contrast. Default is 33. Allowed range is between 0 and 100.
445 Copy the input audio source unchanged to the output. This is mainly useful for
450 Apply cross fade from one input audio stream to another input audio stream.
451 The cross fade is applied for specified duration near the end of first stream.
453 The filter accepts the following options:
457 Specify the number of samples for which the cross fade effect has to last.
458 At the end of the cross fade effect the first input audio will be completely
459 silent. Default is 44100.
462 Specify the duration of the cross fade effect. See
463 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
464 for the accepted syntax.
465 By default the duration is determined by @var{nb_samples}.
466 If set this option is used instead of @var{nb_samples}.
469 Should first stream end overlap with second stream start. Default is enabled.
472 Set curve for cross fade transition for first stream.
475 Set curve for cross fade transition for second stream.
477 For description of available curve types see @ref{afade} filter description.
484 Cross fade from one input to another:
486 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
490 Cross fade from one input to another but without overlapping:
492 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
497 Split audio stream into several bands.
499 This filter splits audio stream into two or more frequency ranges.
500 Summing all streams back will give flat output.
502 The filter accepts the following options:
506 Set split frequencies. Those must be positive and increasing.
509 Set filter order, can be @var{2nd}, @var{4th} or @var{8th}.
510 Default is @var{4th}.
515 Reduce audio bit resolution.
517 This filter is bit crusher with enhanced functionality. A bit crusher
518 is used to audibly reduce number of bits an audio signal is sampled
519 with. This doesn't change the bit depth at all, it just produces the
520 effect. Material reduced in bit depth sounds more harsh and "digital".
521 This filter is able to even round to continuous values instead of discrete
523 Additionally it has a D/C offset which results in different crushing of
524 the lower and the upper half of the signal.
525 An Anti-Aliasing setting is able to produce "softer" crushing sounds.
527 Another feature of this filter is the logarithmic mode.
528 This setting switches from linear distances between bits to logarithmic ones.
529 The result is a much more "natural" sounding crusher which doesn't gate low
530 signals for example. The human ear has a logarithmic perception,
531 so this kind of crushing is much more pleasant.
532 Logarithmic crushing is also able to get anti-aliased.
534 The filter accepts the following options:
550 Can be linear: @code{lin} or logarithmic: @code{log}.
559 Set sample reduction.
562 Enable LFO. By default disabled.
573 Delay audio filtering until a given wallclock timestamp. See the @ref{cue}
577 Remove impulsive noise from input audio.
579 Samples detected as impulsive noise are replaced by interpolated samples using
580 autoregressive modelling.
584 Set window size, in milliseconds. Allowed range is from @code{10} to
585 @code{100}. Default value is @code{55} milliseconds.
586 This sets size of window which will be processed at once.
589 Set window overlap, in percentage of window size. Allowed range is from
590 @code{50} to @code{95}. Default value is @code{75} percent.
591 Setting this to a very high value increases impulsive noise removal but makes
592 whole process much slower.
595 Set autoregression order, in percentage of window size. Allowed range is from
596 @code{0} to @code{25}. Default value is @code{2} percent. This option also
597 controls quality of interpolated samples using neighbour good samples.
600 Set threshold value. Allowed range is from @code{1} to @code{100}.
601 Default value is @code{2}.
602 This controls the strength of impulsive noise which is going to be removed.
603 The lower value, the more samples will be detected as impulsive noise.
606 Set burst fusion, in percentage of window size. Allowed range is @code{0} to
607 @code{10}. Default value is @code{2}.
608 If any two samples deteced as noise are spaced less than this value then any
609 sample inbetween those two samples will be also detected as noise.
614 It accepts the following values:
617 Select overlap-add method. Even not interpolated samples are slightly
618 changed with this method.
621 Select overlap-save method. Not interpolated samples remain unchanged.
624 Default value is @code{a}.
628 Remove clipped samples from input audio.
630 Samples detected as clipped are replaced by interpolated samples using
631 autoregressive modelling.
635 Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}.
636 Default value is @code{55} milliseconds.
637 This sets size of window which will be processed at once.
640 Set window overlap, in percentage of window size. Allowed range is from @code{50}
641 to @code{95}. Default value is @code{75} percent.
644 Set autoregression order, in percentage of window size. Allowed range is from
645 @code{0} to @code{25}. Default value is @code{8} percent. This option also controls
646 quality of interpolated samples using neighbour good samples.
649 Set threshold value. Allowed range is from @code{1} to @code{100}.
650 Default value is @code{10}. Higher values make clip detection less aggressive.
653 Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}.
654 Default value is @code{1000}. Higher values make clip detection less aggressive.
659 It accepts the following values:
662 Select overlap-add method. Even not interpolated samples are slightly changed
666 Select overlap-save method. Not interpolated samples remain unchanged.
669 Default value is @code{a}.
674 Delay one or more audio channels.
676 Samples in delayed channel are filled with silence.
678 The filter accepts the following option:
682 Set list of delays in milliseconds for each channel separated by '|'.
683 Unused delays will be silently ignored. If number of given delays is
684 smaller than number of channels all remaining channels will not be delayed.
685 If you want to delay exact number of samples, append 'S' to number.
692 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
693 the second channel (and any other channels that may be present) unchanged.
699 Delay second channel by 500 samples, the third channel by 700 samples and leave
700 the first channel (and any other channels that may be present) unchanged.
706 @section aderivative, aintegral
708 Compute derivative/integral of audio stream.
710 Applying both filters one after another produces original audio.
714 Apply echoing to the input audio.
716 Echoes are reflected sound and can occur naturally amongst mountains
717 (and sometimes large buildings) when talking or shouting; digital echo
718 effects emulate this behaviour and are often used to help fill out the
719 sound of a single instrument or vocal. The time difference between the
720 original signal and the reflection is the @code{delay}, and the
721 loudness of the reflected signal is the @code{decay}.
722 Multiple echoes can have different delays and decays.
724 A description of the accepted parameters follows.
728 Set input gain of reflected signal. Default is @code{0.6}.
731 Set output gain of reflected signal. Default is @code{0.3}.
734 Set list of time intervals in milliseconds between original signal and reflections
735 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
736 Default is @code{1000}.
739 Set list of loudness of reflected signals separated by '|'.
740 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
741 Default is @code{0.5}.
748 Make it sound as if there are twice as many instruments as are actually playing:
750 aecho=0.8:0.88:60:0.4
754 If delay is very short, then it sound like a (metallic) robot playing music:
760 A longer delay will sound like an open air concert in the mountains:
762 aecho=0.8:0.9:1000:0.3
766 Same as above but with one more mountain:
768 aecho=0.8:0.9:1000|1800:0.3|0.25
773 Audio emphasis filter creates or restores material directly taken from LPs or
774 emphased CDs with different filter curves. E.g. to store music on vinyl the
775 signal has to be altered by a filter first to even out the disadvantages of
776 this recording medium.
777 Once the material is played back the inverse filter has to be applied to
778 restore the distortion of the frequency response.
780 The filter accepts the following options:
790 Set filter mode. For restoring material use @code{reproduction} mode, otherwise
791 use @code{production} mode. Default is @code{reproduction} mode.
794 Set filter type. Selects medium. Can be one of the following:
806 select Compact Disc (CD).
812 select 50µs (FM-KF).
814 select 75µs (FM-KF).
820 Modify an audio signal according to the specified expressions.
822 This filter accepts one or more expressions (one for each channel),
823 which are evaluated and used to modify a corresponding audio signal.
825 It accepts the following parameters:
829 Set the '|'-separated expressions list for each separate channel. If
830 the number of input channels is greater than the number of
831 expressions, the last specified expression is used for the remaining
834 @item channel_layout, c
835 Set output channel layout. If not specified, the channel layout is
836 specified by the number of expressions. If set to @samp{same}, it will
837 use by default the same input channel layout.
840 Each expression in @var{exprs} can contain the following constants and functions:
844 channel number of the current expression
847 number of the evaluated sample, starting from 0
853 time of the evaluated sample expressed in seconds
856 @item nb_out_channels
857 input and output number of channels
860 the value of input channel with number @var{CH}
863 Note: this filter is slow. For faster processing you should use a
872 aeval=val(ch)/2:c=same
876 Invert phase of the second channel:
885 Apply fade-in/out effect to input audio.
887 A description of the accepted parameters follows.
891 Specify the effect type, can be either @code{in} for fade-in, or
892 @code{out} for a fade-out effect. Default is @code{in}.
894 @item start_sample, ss
895 Specify the number of the start sample for starting to apply the fade
896 effect. Default is 0.
899 Specify the number of samples for which the fade effect has to last. At
900 the end of the fade-in effect the output audio will have the same
901 volume as the input audio, at the end of the fade-out transition
902 the output audio will be silence. Default is 44100.
905 Specify the start time of the fade effect. Default is 0.
906 The value must be specified as a time duration; see
907 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
908 for the accepted syntax.
909 If set this option is used instead of @var{start_sample}.
912 Specify the duration of the fade effect. See
913 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
914 for the accepted syntax.
915 At the end of the fade-in effect the output audio will have the same
916 volume as the input audio, at the end of the fade-out transition
917 the output audio will be silence.
918 By default the duration is determined by @var{nb_samples}.
919 If set this option is used instead of @var{nb_samples}.
922 Set curve for fade transition.
924 It accepts the following values:
927 select triangular, linear slope (default)
929 select quarter of sine wave
931 select half of sine wave
933 select exponential sine wave
937 select inverted parabola
951 select inverted quarter of sine wave
953 select inverted half of sine wave
955 select double-exponential seat
957 select double-exponential sigmoid
959 select logistic sigmoid
967 Fade in first 15 seconds of audio:
973 Fade out last 25 seconds of a 900 seconds audio:
975 afade=t=out:st=875:d=25
980 Denoise audio samples with FFT.
982 A description of the accepted parameters follows.
986 Set the noise reduction in dB, allowed range is 0.01 to 97.
987 Default value is 12 dB.
990 Set the noise floor in dB, allowed range is -80 to -20.
991 Default value is -50 dB.
996 It accepts the following values:
1005 Select shellac noise.
1008 Select custom noise, defined in @code{bn} option.
1010 Default value is white noise.
1014 Set custom band noise for every one of 15 bands.
1015 Bands are separated by ' ' or '|'.
1018 Set the residual floor in dB, allowed range is -80 to -20.
1019 Default value is -38 dB.
1022 Enable noise tracking. By default is disabled.
1023 With this enabled, noise floor is automatically adjusted.
1026 Enable residual tracking. By default is disabled.
1029 Set the output mode.
1031 It accepts the following values:
1034 Pass input unchanged.
1037 Pass noise filtered out.
1042 Default value is @var{o}.
1046 @subsection Commands
1048 This filter supports the following commands:
1050 @item sample_noise, sn
1051 Start or stop measuring noise profile.
1052 Syntax for the command is : "start" or "stop" string.
1053 After measuring noise profile is stopped it will be
1054 automatically applied in filtering.
1056 @item noise_reduction, nr
1057 Change noise reduction. Argument is single float number.
1058 Syntax for the command is : "@var{noise_reduction}"
1060 @item noise_floor, nf
1061 Change noise floor. Argument is single float number.
1062 Syntax for the command is : "@var{noise_floor}"
1064 @item output_mode, om
1065 Change output mode operation.
1066 Syntax for the command is : "i", "o" or "n" string.
1070 Apply arbitrary expressions to samples in frequency domain.
1074 Set frequency domain real expression for each separate channel separated
1075 by '|'. Default is "1".
1076 If the number of input channels is greater than the number of
1077 expressions, the last specified expression is used for the remaining
1081 Set frequency domain imaginary expression for each separate channel
1082 separated by '|'. If not set, @var{real} option is used.
1084 Each expression in @var{real} and @var{imag} can contain the following
1092 current frequency bin number
1095 number of available bins
1098 channel number of the current expression
1110 It accepts the following values:
1126 Default is @code{w4096}
1129 Set window function. Default is @code{hann}.
1132 Set window overlap. If set to 1, the recommended overlap for selected
1133 window function will be picked. Default is @code{0.75}.
1136 @subsection Examples
1140 Leave almost only low frequencies in audio:
1142 afftfilt="1-clip((b/nb)*b,0,1)"
1149 Apply an arbitrary Frequency Impulse Response filter.
1151 This filter is designed for applying long FIR filters,
1152 up to 60 seconds long.
1154 It can be used as component for digital crossover filters,
1155 room equalization, cross talk cancellation, wavefield synthesis,
1156 auralization, ambiophonics and ambisonics.
1158 This filter uses second stream as FIR coefficients.
1159 If second stream holds single channel, it will be used
1160 for all input channels in first stream, otherwise
1161 number of channels in second stream must be same as
1162 number of channels in first stream.
1164 It accepts the following parameters:
1168 Set dry gain. This sets input gain.
1171 Set wet gain. This sets final output gain.
1174 Set Impulse Response filter length. Default is 1, which means whole IR is processed.
1177 Enable applying gain measured from power of IR.
1179 Set which approach to use for auto gain measurement.
1183 Do not apply any gain.
1186 select peak gain, very conservative approach. This is default value.
1189 select DC gain, limited application.
1192 select gain to noise approach, this is most popular one.
1196 Set gain to be applied to IR coefficients before filtering.
1197 Allowed range is 0 to 1. This gain is applied after any gain applied with @var{gtype} option.
1200 Set format of IR stream. Can be @code{mono} or @code{input}.
1201 Default is @code{input}.
1204 Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds.
1205 Allowed range is 0.1 to 60 seconds.
1208 Show IR frequency reponse, magnitude(magenta) and phase(green) and group delay(yellow) in additional video stream.
1209 By default it is disabled.
1212 Set for which IR channel to display frequency response. By default is first channel
1213 displayed. This option is used only when @var{response} is enabled.
1216 Set video stream size. This option is used only when @var{response} is enabled.
1219 Set video stream frame rate. This option is used only when @var{response} is enabled.
1222 @subsection Examples
1226 Apply reverb to stream using mono IR file as second input, complete command using ffmpeg:
1228 ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
1235 Set output format constraints for the input audio. The framework will
1236 negotiate the most appropriate format to minimize conversions.
1238 It accepts the following parameters:
1242 A '|'-separated list of requested sample formats.
1245 A '|'-separated list of requested sample rates.
1247 @item channel_layouts
1248 A '|'-separated list of requested channel layouts.
1250 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1251 for the required syntax.
1254 If a parameter is omitted, all values are allowed.
1256 Force the output to either unsigned 8-bit or signed 16-bit stereo
1258 aformat=sample_fmts=u8|s16:channel_layouts=stereo
1263 A gate is mainly used to reduce lower parts of a signal. This kind of signal
1264 processing reduces disturbing noise between useful signals.
1266 Gating is done by detecting the volume below a chosen level @var{threshold}
1267 and dividing it by the factor set with @var{ratio}. The bottom of the noise
1268 floor is set via @var{range}. Because an exact manipulation of the signal
1269 would cause distortion of the waveform the reduction can be levelled over
1270 time. This is done by setting @var{attack} and @var{release}.
1272 @var{attack} determines how long the signal has to fall below the threshold
1273 before any reduction will occur and @var{release} sets the time the signal
1274 has to rise above the threshold to reduce the reduction again.
1275 Shorter signals than the chosen attack time will be left untouched.
1279 Set input level before filtering.
1280 Default is 1. Allowed range is from 0.015625 to 64.
1283 Set the level of gain reduction when the signal is below the threshold.
1284 Default is 0.06125. Allowed range is from 0 to 1.
1287 If a signal rises above this level the gain reduction is released.
1288 Default is 0.125. Allowed range is from 0 to 1.
1291 Set a ratio by which the signal is reduced.
1292 Default is 2. Allowed range is from 1 to 9000.
1295 Amount of milliseconds the signal has to rise above the threshold before gain
1297 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
1300 Amount of milliseconds the signal has to fall below the threshold before the
1301 reduction is increased again. Default is 250 milliseconds.
1302 Allowed range is from 0.01 to 9000.
1305 Set amount of amplification of signal after processing.
1306 Default is 1. Allowed range is from 1 to 64.
1309 Curve the sharp knee around the threshold to enter gain reduction more softly.
1310 Default is 2.828427125. Allowed range is from 1 to 8.
1313 Choose if exact signal should be taken for detection or an RMS like one.
1314 Default is @code{rms}. Can be @code{peak} or @code{rms}.
1317 Choose if the average level between all channels or the louder channel affects
1319 Default is @code{average}. Can be @code{average} or @code{maximum}.
1324 Apply an arbitrary Infinite Impulse Response filter.
1326 It accepts the following parameters:
1330 Set numerator/zeros coefficients.
1333 Set denominator/poles coefficients.
1345 Set coefficients format.
1351 Z-plane zeros/poles, cartesian (default)
1353 Z-plane zeros/poles, polar radians
1355 Z-plane zeros/poles, polar degrees
1359 Set kind of processing.
1360 Can be @code{d} - direct or @code{s} - serial cascading. Defauls is @code{s}.
1363 Set filtering precision.
1367 double-precision floating-point (default)
1369 single-precision floating-point
1377 Show IR frequency reponse, magnitude and phase in additional video stream.
1378 By default it is disabled.
1381 Set for which IR channel to display frequency response. By default is first channel
1382 displayed. This option is used only when @var{response} is enabled.
1385 Set video stream size. This option is used only when @var{response} is enabled.
1388 Coefficients in @code{tf} format are separated by spaces and are in ascending
1391 Coefficients in @code{zp} format are separated by spaces and order of coefficients
1392 doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i}
1395 Different coefficients and gains can be provided for every channel, in such case
1396 use '|' to separate coefficients or gains. Last provided coefficients will be
1397 used for all remaining channels.
1399 @subsection Examples
1403 Apply 2 pole elliptic notch at arround 5000Hz for 48000 Hz sample rate:
1405 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
1409 Same as above but in @code{zp} format:
1411 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
1417 The limiter prevents an input signal from rising over a desired threshold.
1418 This limiter uses lookahead technology to prevent your signal from distorting.
1419 It means that there is a small delay after the signal is processed. Keep in mind
1420 that the delay it produces is the attack time you set.
1422 The filter accepts the following options:
1426 Set input gain. Default is 1.
1429 Set output gain. Default is 1.
1432 Don't let signals above this level pass the limiter. Default is 1.
1435 The limiter will reach its attenuation level in this amount of time in
1436 milliseconds. Default is 5 milliseconds.
1439 Come back from limiting to attenuation 1.0 in this amount of milliseconds.
1440 Default is 50 milliseconds.
1443 When gain reduction is always needed ASC takes care of releasing to an
1444 average reduction level rather than reaching a reduction of 0 in the release
1448 Select how much the release time is affected by ASC, 0 means nearly no changes
1449 in release time while 1 produces higher release times.
1452 Auto level output signal. Default is enabled.
1453 This normalizes audio back to 0dB if enabled.
1456 Depending on picked setting it is recommended to upsample input 2x or 4x times
1457 with @ref{aresample} before applying this filter.
1461 Apply a two-pole all-pass filter with central frequency (in Hz)
1462 @var{frequency}, and filter-width @var{width}.
1463 An all-pass filter changes the audio's frequency to phase relationship
1464 without changing its frequency to amplitude relationship.
1466 The filter accepts the following options:
1470 Set frequency in Hz.
1473 Set method to specify band-width of filter.
1488 Specify the band-width of a filter in width_type units.
1491 Specify which channels to filter, by default all available are filtered.
1494 @subsection Commands
1496 This filter supports the following commands:
1499 Change allpass frequency.
1500 Syntax for the command is : "@var{frequency}"
1503 Change allpass width_type.
1504 Syntax for the command is : "@var{width_type}"
1507 Change allpass width.
1508 Syntax for the command is : "@var{width}"
1515 The filter accepts the following options:
1519 Set the number of loops. Setting this value to -1 will result in infinite loops.
1523 Set maximal number of samples. Default is 0.
1526 Set first sample of loop. Default is 0.
1532 Merge two or more audio streams into a single multi-channel stream.
1534 The filter accepts the following options:
1539 Set the number of inputs. Default is 2.
1543 If the channel layouts of the inputs are disjoint, and therefore compatible,
1544 the channel layout of the output will be set accordingly and the channels
1545 will be reordered as necessary. If the channel layouts of the inputs are not
1546 disjoint, the output will have all the channels of the first input then all
1547 the channels of the second input, in that order, and the channel layout of
1548 the output will be the default value corresponding to the total number of
1551 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
1552 is FC+BL+BR, then the output will be in 5.1, with the channels in the
1553 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
1554 first input, b1 is the first channel of the second input).
1556 On the other hand, if both input are in stereo, the output channels will be
1557 in the default order: a1, a2, b1, b2, and the channel layout will be
1558 arbitrarily set to 4.0, which may or may not be the expected value.
1560 All inputs must have the same sample rate, and format.
1562 If inputs do not have the same duration, the output will stop with the
1565 @subsection Examples
1569 Merge two mono files into a stereo stream:
1571 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
1575 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
1577 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
1583 Mixes multiple audio inputs into a single output.
1585 Note that this filter only supports float samples (the @var{amerge}
1586 and @var{pan} audio filters support many formats). If the @var{amix}
1587 input has integer samples then @ref{aresample} will be automatically
1588 inserted to perform the conversion to float samples.
1592 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
1594 will mix 3 input audio streams to a single output with the same duration as the
1595 first input and a dropout transition time of 3 seconds.
1597 It accepts the following parameters:
1601 The number of inputs. If unspecified, it defaults to 2.
1604 How to determine the end-of-stream.
1608 The duration of the longest input. (default)
1611 The duration of the shortest input.
1614 The duration of the first input.
1618 @item dropout_transition
1619 The transition time, in seconds, for volume renormalization when an input
1620 stream ends. The default value is 2 seconds.
1623 Specify weight of each input audio stream as sequence.
1624 Each weight is separated by space. By default all inputs have same weight.
1629 Multiply first audio stream with second audio stream and store result
1630 in output audio stream. Multiplication is done by multiplying each
1631 sample from first stream with sample at same position from second stream.
1633 With this element-wise multiplication one can create amplitude fades and
1634 amplitude modulations.
1636 @section anequalizer
1638 High-order parametric multiband equalizer for each channel.
1640 It accepts the following parameters:
1644 This option string is in format:
1645 "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
1646 Each equalizer band is separated by '|'.
1650 Set channel number to which equalization will be applied.
1651 If input doesn't have that channel the entry is ignored.
1654 Set central frequency for band.
1655 If input doesn't have that frequency the entry is ignored.
1658 Set band width in hertz.
1661 Set band gain in dB.
1664 Set filter type for band, optional, can be:
1668 Butterworth, this is default.
1679 With this option activated frequency response of anequalizer is displayed
1683 Set video stream size. Only useful if curves option is activated.
1686 Set max gain that will be displayed. Only useful if curves option is activated.
1687 Setting this to a reasonable value makes it possible to display gain which is derived from
1688 neighbour bands which are too close to each other and thus produce higher gain
1689 when both are activated.
1692 Set frequency scale used to draw frequency response in video output.
1693 Can be linear or logarithmic. Default is logarithmic.
1696 Set color for each channel curve which is going to be displayed in video stream.
1697 This is list of color names separated by space or by '|'.
1698 Unrecognised or missing colors will be replaced by white color.
1701 @subsection Examples
1705 Lower gain by 10 of central frequency 200Hz and width 100 Hz
1706 for first 2 channels using Chebyshev type 1 filter:
1708 anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
1712 @subsection Commands
1714 This filter supports the following commands:
1717 Alter existing filter parameters.
1718 Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
1720 @var{fN} is existing filter number, starting from 0, if no such filter is available
1722 @var{freq} set new frequency parameter.
1723 @var{width} set new width parameter in herz.
1724 @var{gain} set new gain parameter in dB.
1726 Full filter invocation with asendcmd may look like this:
1727 asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
1732 Pass the audio source unchanged to the output.
1736 Pad the end of an audio stream with silence.
1738 This can be used together with @command{ffmpeg} @option{-shortest} to
1739 extend audio streams to the same length as the video stream.
1741 A description of the accepted options follows.
1745 Set silence packet size. Default value is 4096.
1748 Set the number of samples of silence to add to the end. After the
1749 value is reached, the stream is terminated. This option is mutually
1750 exclusive with @option{whole_len}.
1753 Set the minimum total number of samples in the output audio stream. If
1754 the value is longer than the input audio length, silence is added to
1755 the end, until the value is reached. This option is mutually exclusive
1756 with @option{pad_len}.
1759 If neither the @option{pad_len} nor the @option{whole_len} option is
1760 set, the filter will add silence to the end of the input stream
1763 @subsection Examples
1767 Add 1024 samples of silence to the end of the input:
1773 Make sure the audio output will contain at least 10000 samples, pad
1774 the input with silence if required:
1776 apad=whole_len=10000
1780 Use @command{ffmpeg} to pad the audio input with silence, so that the
1781 video stream will always result the shortest and will be converted
1782 until the end in the output file when using the @option{shortest}
1785 ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
1790 Add a phasing effect to the input audio.
1792 A phaser filter creates series of peaks and troughs in the frequency spectrum.
1793 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
1795 A description of the accepted parameters follows.
1799 Set input gain. Default is 0.4.
1802 Set output gain. Default is 0.74
1805 Set delay in milliseconds. Default is 3.0.
1808 Set decay. Default is 0.4.
1811 Set modulation speed in Hz. Default is 0.5.
1814 Set modulation type. Default is triangular.
1816 It accepts the following values:
1825 Audio pulsator is something between an autopanner and a tremolo.
1826 But it can produce funny stereo effects as well. Pulsator changes the volume
1827 of the left and right channel based on a LFO (low frequency oscillator) with
1828 different waveforms and shifted phases.
1829 This filter have the ability to define an offset between left and right
1830 channel. An offset of 0 means that both LFO shapes match each other.
1831 The left and right channel are altered equally - a conventional tremolo.
1832 An offset of 50% means that the shape of the right channel is exactly shifted
1833 in phase (or moved backwards about half of the frequency) - pulsator acts as
1834 an autopanner. At 1 both curves match again. Every setting in between moves the
1835 phase shift gapless between all stages and produces some "bypassing" sounds with
1836 sine and triangle waveforms. The more you set the offset near 1 (starting from
1837 the 0.5) the faster the signal passes from the left to the right speaker.
1839 The filter accepts the following options:
1843 Set input gain. By default it is 1. Range is [0.015625 - 64].
1846 Set output gain. By default it is 1. Range is [0.015625 - 64].
1849 Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
1850 sawup or sawdown. Default is sine.
1853 Set modulation. Define how much of original signal is affected by the LFO.
1856 Set left channel offset. Default is 0. Allowed range is [0 - 1].
1859 Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
1862 Set pulse width. Default is 1. Allowed range is [0 - 2].
1865 Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
1868 Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
1872 Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
1876 Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
1877 if timing is set to hz.
1883 Resample the input audio to the specified parameters, using the
1884 libswresample library. If none are specified then the filter will
1885 automatically convert between its input and output.
1887 This filter is also able to stretch/squeeze the audio data to make it match
1888 the timestamps or to inject silence / cut out audio to make it match the
1889 timestamps, do a combination of both or do neither.
1891 The filter accepts the syntax
1892 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
1893 expresses a sample rate and @var{resampler_options} is a list of
1894 @var{key}=@var{value} pairs, separated by ":". See the
1895 @ref{Resampler Options,,"Resampler Options" section in the
1896 ffmpeg-resampler(1) manual,ffmpeg-resampler}
1897 for the complete list of supported options.
1899 @subsection Examples
1903 Resample the input audio to 44100Hz:
1909 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
1910 samples per second compensation:
1912 aresample=async=1000
1918 Reverse an audio clip.
1920 Warning: This filter requires memory to buffer the entire clip, so trimming
1923 @subsection Examples
1927 Take the first 5 seconds of a clip, and reverse it.
1929 atrim=end=5,areverse
1933 @section asetnsamples
1935 Set the number of samples per each output audio frame.
1937 The last output packet may contain a different number of samples, as
1938 the filter will flush all the remaining samples when the input audio
1941 The filter accepts the following options:
1945 @item nb_out_samples, n
1946 Set the number of frames per each output audio frame. The number is
1947 intended as the number of samples @emph{per each channel}.
1948 Default value is 1024.
1951 If set to 1, the filter will pad the last audio frame with zeroes, so
1952 that the last frame will contain the same number of samples as the
1953 previous ones. Default value is 1.
1956 For example, to set the number of per-frame samples to 1234 and
1957 disable padding for the last frame, use:
1959 asetnsamples=n=1234:p=0
1964 Set the sample rate without altering the PCM data.
1965 This will result in a change of speed and pitch.
1967 The filter accepts the following options:
1970 @item sample_rate, r
1971 Set the output sample rate. Default is 44100 Hz.
1976 Show a line containing various information for each input audio frame.
1977 The input audio is not modified.
1979 The shown line contains a sequence of key/value pairs of the form
1980 @var{key}:@var{value}.
1982 The following values are shown in the output:
1986 The (sequential) number of the input frame, starting from 0.
1989 The presentation timestamp of the input frame, in time base units; the time base
1990 depends on the filter input pad, and is usually 1/@var{sample_rate}.
1993 The presentation timestamp of the input frame in seconds.
1996 position of the frame in the input stream, -1 if this information in
1997 unavailable and/or meaningless (for example in case of synthetic audio)
2006 The sample rate for the audio frame.
2009 The number of samples (per channel) in the frame.
2012 The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
2013 audio, the data is treated as if all the planes were concatenated.
2015 @item plane_checksums
2016 A list of Adler-32 checksums for each data plane.
2022 Display time domain statistical information about the audio channels.
2023 Statistics are calculated and displayed for each audio channel and,
2024 where applicable, an overall figure is also given.
2026 It accepts the following option:
2029 Short window length in seconds, used for peak and trough RMS measurement.
2030 Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}.
2034 Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
2035 where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
2038 Available keys for each channel are:
2074 For example full key look like this @code{lavfi.astats.1.DC_offset} or
2075 this @code{lavfi.astats.Overall.Peak_count}.
2077 For description what each key means read below.
2080 Set number of frame after which stats are going to be recalculated.
2081 Default is disabled.
2084 A description of each shown parameter follows:
2088 Mean amplitude displacement from zero.
2091 Minimal sample level.
2094 Maximal sample level.
2096 @item Min difference
2097 Minimal difference between two consecutive samples.
2099 @item Max difference
2100 Maximal difference between two consecutive samples.
2102 @item Mean difference
2103 Mean difference between two consecutive samples.
2104 The average of each difference between two consecutive samples.
2106 @item RMS difference
2107 Root Mean Square difference between two consecutive samples.
2111 Standard peak and RMS level measured in dBFS.
2115 Peak and trough values for RMS level measured over a short window.
2118 Standard ratio of peak to RMS level (note: not in dB).
2121 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
2122 (i.e. either @var{Min level} or @var{Max level}).
2125 Number of occasions (not the number of samples) that the signal attained either
2126 @var{Min level} or @var{Max level}.
2129 Overall bit depth of audio. Number of bits used for each sample.
2132 Measured dynamic range of audio in dB.
2134 @item Zero crossings
2135 Number of points where the waveform crosses the zero level axis.
2137 @item Zero crossings rate
2138 Rate of Zero crossings and number of audio samples.
2145 The filter accepts exactly one parameter, the audio tempo. If not
2146 specified then the filter will assume nominal 1.0 tempo. Tempo must
2147 be in the [0.5, 100.0] range.
2149 Note that tempo greater than 2 will skip some samples rather than
2150 blend them in. If for any reason this is a concern it is always
2151 possible to daisy-chain several instances of atempo to achieve the
2152 desired product tempo.
2154 @subsection Examples
2158 Slow down audio to 80% tempo:
2164 To speed up audio to 300% tempo:
2170 To speed up audio to 300% tempo by daisy-chaining two atempo instances:
2172 atempo=sqrt(3),atempo=sqrt(3)
2178 Trim the input so that the output contains one continuous subpart of the input.
2180 It accepts the following parameters:
2183 Timestamp (in seconds) of the start of the section to keep. I.e. the audio
2184 sample with the timestamp @var{start} will be the first sample in the output.
2187 Specify time of the first audio sample that will be dropped, i.e. the
2188 audio sample immediately preceding the one with the timestamp @var{end} will be
2189 the last sample in the output.
2192 Same as @var{start}, except this option sets the start timestamp in samples
2196 Same as @var{end}, except this option sets the end timestamp in samples instead
2200 The maximum duration of the output in seconds.
2203 The number of the first sample that should be output.
2206 The number of the first sample that should be dropped.
2209 @option{start}, @option{end}, and @option{duration} are expressed as time
2210 duration specifications; see
2211 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
2213 Note that the first two sets of the start/end options and the @option{duration}
2214 option look at the frame timestamp, while the _sample options simply count the
2215 samples that pass through the filter. So start/end_pts and start/end_sample will
2216 give different results when the timestamps are wrong, inexact or do not start at
2217 zero. Also note that this filter does not modify the timestamps. If you wish
2218 to have the output timestamps start at zero, insert the asetpts filter after the
2221 If multiple start or end options are set, this filter tries to be greedy and
2222 keep all samples that match at least one of the specified constraints. To keep
2223 only the part that matches all the constraints at once, chain multiple atrim
2226 The defaults are such that all the input is kept. So it is possible to set e.g.
2227 just the end values to keep everything before the specified time.
2232 Drop everything except the second minute of input:
2234 ffmpeg -i INPUT -af atrim=60:120
2238 Keep only the first 1000 samples:
2240 ffmpeg -i INPUT -af atrim=end_sample=1000
2247 Apply a two-pole Butterworth band-pass filter with central
2248 frequency @var{frequency}, and (3dB-point) band-width width.
2249 The @var{csg} option selects a constant skirt gain (peak gain = Q)
2250 instead of the default: constant 0dB peak gain.
2251 The filter roll off at 6dB per octave (20dB per decade).
2253 The filter accepts the following options:
2257 Set the filter's central frequency. Default is @code{3000}.
2260 Constant skirt gain if set to 1. Defaults to 0.
2263 Set method to specify band-width of filter.
2278 Specify the band-width of a filter in width_type units.
2281 Specify which channels to filter, by default all available are filtered.
2284 @subsection Commands
2286 This filter supports the following commands:
2289 Change bandpass frequency.
2290 Syntax for the command is : "@var{frequency}"
2293 Change bandpass width_type.
2294 Syntax for the command is : "@var{width_type}"
2297 Change bandpass width.
2298 Syntax for the command is : "@var{width}"
2303 Apply a two-pole Butterworth band-reject filter with central
2304 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
2305 The filter roll off at 6dB per octave (20dB per decade).
2307 The filter accepts the following options:
2311 Set the filter's central frequency. Default is @code{3000}.
2314 Set method to specify band-width of filter.
2329 Specify the band-width of a filter in width_type units.
2332 Specify which channels to filter, by default all available are filtered.
2335 @subsection Commands
2337 This filter supports the following commands:
2340 Change bandreject frequency.
2341 Syntax for the command is : "@var{frequency}"
2344 Change bandreject width_type.
2345 Syntax for the command is : "@var{width_type}"
2348 Change bandreject width.
2349 Syntax for the command is : "@var{width}"
2352 @section bass, lowshelf
2354 Boost or cut the bass (lower) frequencies of the audio using a two-pole
2355 shelving filter with a response similar to that of a standard
2356 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
2358 The filter accepts the following options:
2362 Give the gain at 0 Hz. Its useful range is about -20
2363 (for a large cut) to +20 (for a large boost).
2364 Beware of clipping when using a positive gain.
2367 Set the filter's central frequency and so can be used
2368 to extend or reduce the frequency range to be boosted or cut.
2369 The default value is @code{100} Hz.
2372 Set method to specify band-width of filter.
2387 Determine how steep is the filter's shelf transition.
2390 Specify which channels to filter, by default all available are filtered.
2393 @subsection Commands
2395 This filter supports the following commands:
2398 Change bass frequency.
2399 Syntax for the command is : "@var{frequency}"
2402 Change bass width_type.
2403 Syntax for the command is : "@var{width_type}"
2407 Syntax for the command is : "@var{width}"
2411 Syntax for the command is : "@var{gain}"
2416 Apply a biquad IIR filter with the given coefficients.
2417 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
2418 are the numerator and denominator coefficients respectively.
2419 and @var{channels}, @var{c} specify which channels to filter, by default all
2420 available are filtered.
2422 @subsection Commands
2424 This filter supports the following commands:
2432 Change biquad parameter.
2433 Syntax for the command is : "@var{value}"
2437 Bauer stereo to binaural transformation, which improves headphone listening of
2438 stereo audio records.
2440 To enable compilation of this filter you need to configure FFmpeg with
2441 @code{--enable-libbs2b}.
2443 It accepts the following parameters:
2447 Pre-defined crossfeed level.
2451 Default level (fcut=700, feed=50).
2454 Chu Moy circuit (fcut=700, feed=60).
2457 Jan Meier circuit (fcut=650, feed=95).
2462 Cut frequency (in Hz).
2471 Remap input channels to new locations.
2473 It accepts the following parameters:
2476 Map channels from input to output. The argument is a '|'-separated list of
2477 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
2478 @var{in_channel} form. @var{in_channel} can be either the name of the input
2479 channel (e.g. FL for front left) or its index in the input channel layout.
2480 @var{out_channel} is the name of the output channel or its index in the output
2481 channel layout. If @var{out_channel} is not given then it is implicitly an
2482 index, starting with zero and increasing by one for each mapping.
2484 @item channel_layout
2485 The channel layout of the output stream.
2488 If no mapping is present, the filter will implicitly map input channels to
2489 output channels, preserving indices.
2491 @subsection Examples
2495 For example, assuming a 5.1+downmix input MOV file,
2497 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
2499 will create an output WAV file tagged as stereo from the downmix channels of
2503 To fix a 5.1 WAV improperly encoded in AAC's native channel order
2505 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
2509 @section channelsplit
2511 Split each channel from an input audio stream into a separate output stream.
2513 It accepts the following parameters:
2515 @item channel_layout
2516 The channel layout of the input stream. The default is "stereo".
2518 A channel layout describing the channels to be extracted as separate output streams
2519 or "all" to extract each input channel as a separate stream. The default is "all".
2521 Choosing channels not present in channel layout in the input will result in an error.
2524 @subsection Examples
2528 For example, assuming a stereo input MP3 file,
2530 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
2532 will create an output Matroska file with two audio streams, one containing only
2533 the left channel and the other the right channel.
2536 Split a 5.1 WAV file into per-channel files:
2538 ffmpeg -i in.wav -filter_complex
2539 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
2540 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
2541 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
2546 Extract only LFE from a 5.1 WAV file:
2548 ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
2549 -map '[LFE]' lfe.wav
2554 Add a chorus effect to the audio.
2556 Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
2558 Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
2559 constant, with chorus, it is varied using using sinusoidal or triangular modulation.
2560 The modulation depth defines the range the modulated delay is played before or after
2561 the delay. Hence the delayed sound will sound slower or faster, that is the delayed
2562 sound tuned around the original one, like in a chorus where some vocals are slightly
2565 It accepts the following parameters:
2568 Set input gain. Default is 0.4.
2571 Set output gain. Default is 0.4.
2574 Set delays. A typical delay is around 40ms to 60ms.
2586 @subsection Examples
2592 chorus=0.7:0.9:55:0.4:0.25:2
2598 chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
2602 Fuller sounding chorus with three delays:
2604 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
2609 Compress or expand the audio's dynamic range.
2611 It accepts the following parameters:
2617 A list of times in seconds for each channel over which the instantaneous level
2618 of the input signal is averaged to determine its volume. @var{attacks} refers to
2619 increase of volume and @var{decays} refers to decrease of volume. For most
2620 situations, the attack time (response to the audio getting louder) should be
2621 shorter than the decay time, because the human ear is more sensitive to sudden
2622 loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
2623 a typical value for decay is 0.8 seconds.
2624 If specified number of attacks & decays is lower than number of channels, the last
2625 set attack/decay will be used for all remaining channels.
2628 A list of points for the transfer function, specified in dB relative to the
2629 maximum possible signal amplitude. Each key points list must be defined using
2630 the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
2631 @code{x0/y0 x1/y1 x2/y2 ....}
2633 The input values must be in strictly increasing order but the transfer function
2634 does not have to be monotonically rising. The point @code{0/0} is assumed but
2635 may be overridden (by @code{0/out-dBn}). Typical values for the transfer
2636 function are @code{-70/-70|-60/-20|1/0}.
2639 Set the curve radius in dB for all joints. It defaults to 0.01.
2642 Set the additional gain in dB to be applied at all points on the transfer
2643 function. This allows for easy adjustment of the overall gain.
2647 Set an initial volume, in dB, to be assumed for each channel when filtering
2648 starts. This permits the user to supply a nominal level initially, so that, for
2649 example, a very large gain is not applied to initial signal levels before the
2650 companding has begun to operate. A typical value for audio which is initially
2651 quiet is -90 dB. It defaults to 0.
2654 Set a delay, in seconds. The input audio is analyzed immediately, but audio is
2655 delayed before being fed to the volume adjuster. Specifying a delay
2656 approximately equal to the attack/decay times allows the filter to effectively
2657 operate in predictive rather than reactive mode. It defaults to 0.
2661 @subsection Examples
2665 Make music with both quiet and loud passages suitable for listening to in a
2668 compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
2671 Another example for audio with whisper and explosion parts:
2673 compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
2677 A noise gate for when the noise is at a lower level than the signal:
2679 compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
2683 Here is another noise gate, this time for when the noise is at a higher level
2684 than the signal (making it, in some ways, similar to squelch):
2686 compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
2690 2:1 compression starting at -6dB:
2692 compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
2696 2:1 compression starting at -9dB:
2698 compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
2702 2:1 compression starting at -12dB:
2704 compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
2708 2:1 compression starting at -18dB:
2710 compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
2714 3:1 compression starting at -15dB:
2716 compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
2722 compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
2728 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
2732 Hard limiter at -6dB:
2734 compand=attacks=0:points=-80/-80|-6/-6|20/-6
2738 Hard limiter at -12dB:
2740 compand=attacks=0:points=-80/-80|-12/-12|20/-12
2744 Hard noise gate at -35 dB:
2746 compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
2752 compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
2756 @section compensationdelay
2758 Compensation Delay Line is a metric based delay to compensate differing
2759 positions of microphones or speakers.
2761 For example, you have recorded guitar with two microphones placed in
2762 different location. Because the front of sound wave has fixed speed in
2763 normal conditions, the phasing of microphones can vary and depends on
2764 their location and interposition. The best sound mix can be achieved when
2765 these microphones are in phase (synchronized). Note that distance of
2766 ~30 cm between microphones makes one microphone to capture signal in
2767 antiphase to another microphone. That makes the final mix sounding moody.
2768 This filter helps to solve phasing problems by adding different delays
2769 to each microphone track and make them synchronized.
2771 The best result can be reached when you take one track as base and
2772 synchronize other tracks one by one with it.
2773 Remember that synchronization/delay tolerance depends on sample rate, too.
2774 Higher sample rates will give more tolerance.
2776 It accepts the following parameters:
2780 Set millimeters distance. This is compensation distance for fine tuning.
2784 Set cm distance. This is compensation distance for tightening distance setup.
2788 Set meters distance. This is compensation distance for hard distance setup.
2792 Set dry amount. Amount of unprocessed (dry) signal.
2796 Set wet amount. Amount of processed (wet) signal.
2800 Set temperature degree in Celsius. This is the temperature of the environment.
2805 Apply headphone crossfeed filter.
2807 Crossfeed is the process of blending the left and right channels of stereo
2809 It is mainly used to reduce extreme stereo separation of low frequencies.
2811 The intent is to produce more speaker like sound to the listener.
2813 The filter accepts the following options:
2817 Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1.
2818 This sets gain of low shelf filter for side part of stereo image.
2819 Default is -6dB. Max allowed is -30db when strength is set to 1.
2822 Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1.
2823 This sets cut off frequency of low shelf filter. Default is cut off near
2824 1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz.
2827 Set input gain. Default is 0.9.
2830 Set output gain. Default is 1.
2833 @section crystalizer
2834 Simple algorithm to expand audio dynamic range.
2836 The filter accepts the following options:
2840 Sets the intensity of effect (default: 2.0). Must be in range between 0.0
2841 (unchanged sound) to 10.0 (maximum effect).
2844 Enable clipping. By default is enabled.
2848 Apply a DC shift to the audio.
2850 This can be useful to remove a DC offset (caused perhaps by a hardware problem
2851 in the recording chain) from the audio. The effect of a DC offset is reduced
2852 headroom and hence volume. The @ref{astats} filter can be used to determine if
2853 a signal has a DC offset.
2857 Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
2861 Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
2862 used to prevent clipping.
2866 Measure audio dynamic range.
2868 DR values of 14 and higher is found in very dynamic material. DR of 8 to 13
2869 is found in transition material. And anything less that 8 have very poor dynamics
2870 and is very compressed.
2872 The filter accepts the following options:
2876 Set window length in seconds used to split audio into segments of equal length.
2877 Default is 3 seconds.
2881 Dynamic Audio Normalizer.
2883 This filter applies a certain amount of gain to the input audio in order
2884 to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
2885 contrast to more "simple" normalization algorithms, the Dynamic Audio
2886 Normalizer *dynamically* re-adjusts the gain factor to the input audio.
2887 This allows for applying extra gain to the "quiet" sections of the audio
2888 while avoiding distortions or clipping the "loud" sections. In other words:
2889 The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
2890 sections, in the sense that the volume of each section is brought to the
2891 same target level. Note, however, that the Dynamic Audio Normalizer achieves
2892 this goal *without* applying "dynamic range compressing". It will retain 100%
2893 of the dynamic range *within* each section of the audio file.
2897 Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
2898 Default is 500 milliseconds.
2899 The Dynamic Audio Normalizer processes the input audio in small chunks,
2900 referred to as frames. This is required, because a peak magnitude has no
2901 meaning for just a single sample value. Instead, we need to determine the
2902 peak magnitude for a contiguous sequence of sample values. While a "standard"
2903 normalizer would simply use the peak magnitude of the complete file, the
2904 Dynamic Audio Normalizer determines the peak magnitude individually for each
2905 frame. The length of a frame is specified in milliseconds. By default, the
2906 Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
2907 been found to give good results with most files.
2908 Note that the exact frame length, in number of samples, will be determined
2909 automatically, based on the sampling rate of the individual input audio file.
2912 Set the Gaussian filter window size. In range from 3 to 301, must be odd
2913 number. Default is 31.
2914 Probably the most important parameter of the Dynamic Audio Normalizer is the
2915 @code{window size} of the Gaussian smoothing filter. The filter's window size
2916 is specified in frames, centered around the current frame. For the sake of
2917 simplicity, this must be an odd number. Consequently, the default value of 31
2918 takes into account the current frame, as well as the 15 preceding frames and
2919 the 15 subsequent frames. Using a larger window results in a stronger
2920 smoothing effect and thus in less gain variation, i.e. slower gain
2921 adaptation. Conversely, using a smaller window results in a weaker smoothing
2922 effect and thus in more gain variation, i.e. faster gain adaptation.
2923 In other words, the more you increase this value, the more the Dynamic Audio
2924 Normalizer will behave like a "traditional" normalization filter. On the
2925 contrary, the more you decrease this value, the more the Dynamic Audio
2926 Normalizer will behave like a dynamic range compressor.
2929 Set the target peak value. This specifies the highest permissible magnitude
2930 level for the normalized audio input. This filter will try to approach the
2931 target peak magnitude as closely as possible, but at the same time it also
2932 makes sure that the normalized signal will never exceed the peak magnitude.
2933 A frame's maximum local gain factor is imposed directly by the target peak
2934 magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
2935 It is not recommended to go above this value.
2938 Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
2939 The Dynamic Audio Normalizer determines the maximum possible (local) gain
2940 factor for each input frame, i.e. the maximum gain factor that does not
2941 result in clipping or distortion. The maximum gain factor is determined by
2942 the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
2943 additionally bounds the frame's maximum gain factor by a predetermined
2944 (global) maximum gain factor. This is done in order to avoid excessive gain
2945 factors in "silent" or almost silent frames. By default, the maximum gain
2946 factor is 10.0, For most inputs the default value should be sufficient and
2947 it usually is not recommended to increase this value. Though, for input
2948 with an extremely low overall volume level, it may be necessary to allow even
2949 higher gain factors. Note, however, that the Dynamic Audio Normalizer does
2950 not simply apply a "hard" threshold (i.e. cut off values above the threshold).
2951 Instead, a "sigmoid" threshold function will be applied. This way, the
2952 gain factors will smoothly approach the threshold value, but never exceed that
2956 Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
2957 By default, the Dynamic Audio Normalizer performs "peak" normalization.
2958 This means that the maximum local gain factor for each frame is defined
2959 (only) by the frame's highest magnitude sample. This way, the samples can
2960 be amplified as much as possible without exceeding the maximum signal
2961 level, i.e. without clipping. Optionally, however, the Dynamic Audio
2962 Normalizer can also take into account the frame's root mean square,
2963 abbreviated RMS. In electrical engineering, the RMS is commonly used to
2964 determine the power of a time-varying signal. It is therefore considered
2965 that the RMS is a better approximation of the "perceived loudness" than
2966 just looking at the signal's peak magnitude. Consequently, by adjusting all
2967 frames to a constant RMS value, a uniform "perceived loudness" can be
2968 established. If a target RMS value has been specified, a frame's local gain
2969 factor is defined as the factor that would result in exactly that RMS value.
2970 Note, however, that the maximum local gain factor is still restricted by the
2971 frame's highest magnitude sample, in order to prevent clipping.
2974 Enable channels coupling. By default is enabled.
2975 By default, the Dynamic Audio Normalizer will amplify all channels by the same
2976 amount. This means the same gain factor will be applied to all channels, i.e.
2977 the maximum possible gain factor is determined by the "loudest" channel.
2978 However, in some recordings, it may happen that the volume of the different
2979 channels is uneven, e.g. one channel may be "quieter" than the other one(s).
2980 In this case, this option can be used to disable the channel coupling. This way,
2981 the gain factor will be determined independently for each channel, depending
2982 only on the individual channel's highest magnitude sample. This allows for
2983 harmonizing the volume of the different channels.
2986 Enable DC bias correction. By default is disabled.
2987 An audio signal (in the time domain) is a sequence of sample values.
2988 In the Dynamic Audio Normalizer these sample values are represented in the
2989 -1.0 to 1.0 range, regardless of the original input format. Normally, the
2990 audio signal, or "waveform", should be centered around the zero point.
2991 That means if we calculate the mean value of all samples in a file, or in a
2992 single frame, then the result should be 0.0 or at least very close to that
2993 value. If, however, there is a significant deviation of the mean value from
2994 0.0, in either positive or negative direction, this is referred to as a
2995 DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
2996 Audio Normalizer provides optional DC bias correction.
2997 With DC bias correction enabled, the Dynamic Audio Normalizer will determine
2998 the mean value, or "DC correction" offset, of each input frame and subtract
2999 that value from all of the frame's sample values which ensures those samples
3000 are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
3001 boundaries, the DC correction offset values will be interpolated smoothly
3002 between neighbouring frames.
3005 Enable alternative boundary mode. By default is disabled.
3006 The Dynamic Audio Normalizer takes into account a certain neighbourhood
3007 around each frame. This includes the preceding frames as well as the
3008 subsequent frames. However, for the "boundary" frames, located at the very
3009 beginning and at the very end of the audio file, not all neighbouring
3010 frames are available. In particular, for the first few frames in the audio
3011 file, the preceding frames are not known. And, similarly, for the last few
3012 frames in the audio file, the subsequent frames are not known. Thus, the
3013 question arises which gain factors should be assumed for the missing frames
3014 in the "boundary" region. The Dynamic Audio Normalizer implements two modes
3015 to deal with this situation. The default boundary mode assumes a gain factor
3016 of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
3017 "fade out" at the beginning and at the end of the input, respectively.
3020 Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
3021 By default, the Dynamic Audio Normalizer does not apply "traditional"
3022 compression. This means that signal peaks will not be pruned and thus the
3023 full dynamic range will be retained within each local neighbourhood. However,
3024 in some cases it may be desirable to combine the Dynamic Audio Normalizer's
3025 normalization algorithm with a more "traditional" compression.
3026 For this purpose, the Dynamic Audio Normalizer provides an optional compression
3027 (thresholding) function. If (and only if) the compression feature is enabled,
3028 all input frames will be processed by a soft knee thresholding function prior
3029 to the actual normalization process. Put simply, the thresholding function is
3030 going to prune all samples whose magnitude exceeds a certain threshold value.
3031 However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
3032 value. Instead, the threshold value will be adjusted for each individual
3034 In general, smaller parameters result in stronger compression, and vice versa.
3035 Values below 3.0 are not recommended, because audible distortion may appear.
3040 Make audio easier to listen to on headphones.
3042 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
3043 so that when listened to on headphones the stereo image is moved from
3044 inside your head (standard for headphones) to outside and in front of
3045 the listener (standard for speakers).
3051 Apply a two-pole peaking equalisation (EQ) filter. With this
3052 filter, the signal-level at and around a selected frequency can
3053 be increased or decreased, whilst (unlike bandpass and bandreject
3054 filters) that at all other frequencies is unchanged.
3056 In order to produce complex equalisation curves, this filter can
3057 be given several times, each with a different central frequency.
3059 The filter accepts the following options:
3063 Set the filter's central frequency in Hz.
3066 Set method to specify band-width of filter.
3081 Specify the band-width of a filter in width_type units.
3084 Set the required gain or attenuation in dB.
3085 Beware of clipping when using a positive gain.
3088 Specify which channels to filter, by default all available are filtered.
3091 @subsection Examples
3094 Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
3096 equalizer=f=1000:t=h:width=200:g=-10
3100 Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
3102 equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
3106 @subsection Commands
3108 This filter supports the following commands:
3111 Change equalizer frequency.
3112 Syntax for the command is : "@var{frequency}"
3115 Change equalizer width_type.
3116 Syntax for the command is : "@var{width_type}"
3119 Change equalizer width.
3120 Syntax for the command is : "@var{width}"
3123 Change equalizer gain.
3124 Syntax for the command is : "@var{gain}"
3127 @section extrastereo
3129 Linearly increases the difference between left and right channels which
3130 adds some sort of "live" effect to playback.
3132 The filter accepts the following options:
3136 Sets the difference coefficient (default: 2.5). 0.0 means mono sound
3137 (average of both channels), with 1.0 sound will be unchanged, with
3138 -1.0 left and right channels will be swapped.
3141 Enable clipping. By default is enabled.
3144 @section firequalizer
3145 Apply FIR Equalization using arbitrary frequency response.
3147 The filter accepts the following option:
3151 Set gain curve equation (in dB). The expression can contain variables:
3154 the evaluated frequency
3158 channel number, set to 0 when multichannels evaluation is disabled
3160 channel id, see libavutil/channel_layout.h, set to the first channel id when
3161 multichannels evaluation is disabled
3165 channel_layout, see libavutil/channel_layout.h
3170 @item gain_interpolate(f)
3171 interpolate gain on frequency f based on gain_entry
3172 @item cubic_interpolate(f)
3173 same as gain_interpolate, but smoother
3175 This option is also available as command. Default is @code{gain_interpolate(f)}.
3178 Set gain entry for gain_interpolate function. The expression can
3182 store gain entry at frequency f with value g
3184 This option is also available as command.
3187 Set filter delay in seconds. Higher value means more accurate.
3188 Default is @code{0.01}.
3191 Set filter accuracy in Hz. Lower value means more accurate.
3192 Default is @code{5}.
3195 Set window function. Acceptable values are:
3198 rectangular window, useful when gain curve is already smooth
3200 hann window (default)
3206 3-terms continuous 1st derivative nuttall window
3208 minimum 3-terms discontinuous nuttall window
3210 4-terms continuous 1st derivative nuttall window
3212 minimum 4-terms discontinuous nuttall (blackman-nuttall) window
3214 blackman-harris window
3220 If enabled, use fixed number of audio samples. This improves speed when
3221 filtering with large delay. Default is disabled.
3224 Enable multichannels evaluation on gain. Default is disabled.
3227 Enable zero phase mode by subtracting timestamp to compensate delay.
3228 Default is disabled.
3231 Set scale used by gain. Acceptable values are:
3234 linear frequency, linear gain
3236 linear frequency, logarithmic (in dB) gain (default)
3238 logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain
3240 logarithmic frequency, logarithmic gain
3244 Set file for dumping, suitable for gnuplot.
3247 Set scale for dumpfile. Acceptable values are same with scale option.
3251 Enable 2-channel convolution using complex FFT. This improves speed significantly.
3252 Default is disabled.
3255 Enable minimum phase impulse response. Default is disabled.
3258 @subsection Examples
3263 firequalizer=gain='if(lt(f,1000), 0, -INF)'
3266 lowpass at 1000 Hz with gain_entry:
3268 firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
3271 custom equalization:
3273 firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
3276 higher delay with zero phase to compensate delay:
3278 firequalizer=delay=0.1:fixed=on:zero_phase=on
3281 lowpass on left channel, highpass on right channel:
3283 firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
3284 :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
3289 Apply a flanging effect to the audio.
3291 The filter accepts the following options:
3295 Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
3298 Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2.
3301 Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
3305 Set percentage of delayed signal mixed with original. Range from 0 to 100.
3306 Default value is 71.
3309 Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
3312 Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
3313 Default value is @var{sinusoidal}.
3316 Set swept wave percentage-shift for multi channel. Range from 0 to 100.
3317 Default value is 25.
3320 Set delay-line interpolation, @var{linear} or @var{quadratic}.
3321 Default is @var{linear}.
3325 Apply Haas effect to audio.
3327 Note that this makes most sense to apply on mono signals.
3328 With this filter applied to mono signals it give some directionality and
3329 stretches its stereo image.
3331 The filter accepts the following options:
3335 Set input level. By default is @var{1}, or 0dB
3338 Set output level. By default is @var{1}, or 0dB.
3341 Set gain applied to side part of signal. By default is @var{1}.
3344 Set kind of middle source. Can be one of the following:
3354 Pick middle part signal of stereo image.
3357 Pick side part signal of stereo image.
3361 Change middle phase. By default is disabled.
3364 Set left channel delay. By default is @var{2.05} milliseconds.
3367 Set left channel balance. By default is @var{-1}.
3370 Set left channel gain. By default is @var{1}.
3373 Change left phase. By default is disabled.
3376 Set right channel delay. By defaults is @var{2.12} milliseconds.
3379 Set right channel balance. By default is @var{1}.
3382 Set right channel gain. By default is @var{1}.
3385 Change right phase. By default is enabled.
3390 Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
3391 embedded HDCD codes is expanded into a 20-bit PCM stream.
3393 The filter supports the Peak Extend and Low-level Gain Adjustment features
3394 of HDCD, and detects the Transient Filter flag.
3397 ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
3400 When using the filter with wav, note the default encoding for wav is 16-bit,
3401 so the resulting 20-bit stream will be truncated back to 16-bit. Use something
3402 like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
3404 ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
3405 ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
3408 The filter accepts the following options:
3411 @item disable_autoconvert
3412 Disable any automatic format conversion or resampling in the filter graph.
3414 @item process_stereo
3415 Process the stereo channels together. If target_gain does not match between
3416 channels, consider it invalid and use the last valid target_gain.
3419 Set the code detect timer period in ms.
3422 Always extend peaks above -3dBFS even if PE isn't signaled.
3425 Replace audio with a solid tone and adjust the amplitude to signal some
3426 specific aspect of the decoding process. The output file can be loaded in
3427 an audio editor alongside the original to aid analysis.
3429 @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
3436 Gain adjustment level at each sample
3438 Samples where peak extend occurs
3440 Samples where the code detect timer is active
3442 Samples where the target gain does not match between channels
3448 Apply head-related transfer functions (HRTFs) to create virtual
3449 loudspeakers around the user for binaural listening via headphones.
3450 The HRIRs are provided via additional streams, for each channel
3451 one stereo input stream is needed.
3453 The filter accepts the following options:
3457 Set mapping of input streams for convolution.
3458 The argument is a '|'-separated list of channel names in order as they
3459 are given as additional stream inputs for filter.
3460 This also specify number of input streams. Number of input streams
3461 must be not less than number of channels in first stream plus one.
3464 Set gain applied to audio. Value is in dB. Default is 0.
3467 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
3468 processing audio in time domain which is slow.
3469 @var{freq} is processing audio in frequency domain which is fast.
3470 Default is @var{freq}.
3473 Set custom gain for LFE channels. Value is in dB. Default is 0.
3476 Set size of frame in number of samples which will be processed at once.
3477 Default value is @var{1024}. Allowed range is from 1024 to 96000.
3480 Set format of hrir stream.
3481 Default value is @var{stereo}. Alternative value is @var{multich}.
3482 If value is set to @var{stereo}, number of additional streams should
3483 be greater or equal to number of input channels in first input stream.
3484 Also each additional stream should have stereo number of channels.
3485 If value is set to @var{multich}, number of additional streams should
3486 be exactly one. Also number of input channels of additional stream
3487 should be equal or greater than twice number of channels of first input
3491 @subsection Examples
3495 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
3496 each amovie filter use stereo file with IR coefficients as input.
3497 The files give coefficients for each position of virtual loudspeaker:
3499 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"
3504 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
3505 but now in @var{multich} @var{hrir} format.
3507 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"
3514 Apply a high-pass filter with 3dB point frequency.
3515 The filter can be either single-pole, or double-pole (the default).
3516 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
3518 The filter accepts the following options:
3522 Set frequency in Hz. Default is 3000.
3525 Set number of poles. Default is 2.
3528 Set method to specify band-width of filter.
3543 Specify the band-width of a filter in width_type units.
3544 Applies only to double-pole filter.
3545 The default is 0.707q and gives a Butterworth response.
3548 Specify which channels to filter, by default all available are filtered.
3551 @subsection Commands
3553 This filter supports the following commands:
3556 Change highpass frequency.
3557 Syntax for the command is : "@var{frequency}"
3560 Change highpass width_type.
3561 Syntax for the command is : "@var{width_type}"
3564 Change highpass width.
3565 Syntax for the command is : "@var{width}"
3570 Join multiple input streams into one multi-channel stream.
3572 It accepts the following parameters:
3576 The number of input streams. It defaults to 2.
3578 @item channel_layout
3579 The desired output channel layout. It defaults to stereo.
3582 Map channels from inputs to output. The argument is a '|'-separated list of
3583 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
3584 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
3585 can be either the name of the input channel (e.g. FL for front left) or its
3586 index in the specified input stream. @var{out_channel} is the name of the output
3590 The filter will attempt to guess the mappings when they are not specified
3591 explicitly. It does so by first trying to find an unused matching input channel
3592 and if that fails it picks the first unused input channel.
3594 Join 3 inputs (with properly set channel layouts):
3596 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
3599 Build a 5.1 output from 6 single-channel streams:
3601 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
3602 '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'
3608 Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
3610 To enable compilation of this filter you need to configure FFmpeg with
3611 @code{--enable-ladspa}.
3615 Specifies the name of LADSPA plugin library to load. If the environment
3616 variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
3617 each one of the directories specified by the colon separated list in
3618 @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
3619 this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
3620 @file{/usr/lib/ladspa/}.
3623 Specifies the plugin within the library. Some libraries contain only
3624 one plugin, but others contain many of them. If this is not set filter
3625 will list all available plugins within the specified library.
3628 Set the '|' separated list of controls which are zero or more floating point
3629 values that determine the behavior of the loaded plugin (for example delay,
3631 Controls need to be defined using the following syntax:
3632 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
3633 @var{valuei} is the value set on the @var{i}-th control.
3634 Alternatively they can be also defined using the following syntax:
3635 @var{value0}|@var{value1}|@var{value2}|..., where
3636 @var{valuei} is the value set on the @var{i}-th control.
3637 If @option{controls} is set to @code{help}, all available controls and
3638 their valid ranges are printed.
3640 @item sample_rate, s
3641 Specify the sample rate, default to 44100. Only used if plugin have
3645 Set the number of samples per channel per each output frame, default
3646 is 1024. Only used if plugin have zero inputs.
3649 Set the minimum duration of the sourced audio. See
3650 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
3651 for the accepted syntax.
3652 Note that the resulting duration may be greater than the specified duration,
3653 as the generated audio is always cut at the end of a complete frame.
3654 If not specified, or the expressed duration is negative, the audio is
3655 supposed to be generated forever.
3656 Only used if plugin have zero inputs.
3660 @subsection Examples
3664 List all available plugins within amp (LADSPA example plugin) library:
3670 List all available controls and their valid ranges for @code{vcf_notch}
3671 plugin from @code{VCF} library:
3673 ladspa=f=vcf:p=vcf_notch:c=help
3677 Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
3680 ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
3684 Add reverberation to the audio using TAP-plugins
3685 (Tom's Audio Processing plugins):
3687 ladspa=file=tap_reverb:tap_reverb
3691 Generate white noise, with 0.2 amplitude:
3693 ladspa=file=cmt:noise_source_white:c=c0=.2
3697 Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
3698 @code{C* Audio Plugin Suite} (CAPS) library:
3700 ladspa=file=caps:Click:c=c1=20'
3704 Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
3706 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
3710 Increase volume by 20dB using fast lookahead limiter from Steve Harris
3711 @code{SWH Plugins} collection:
3713 ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
3717 Attenuate low frequencies using Multiband EQ from Steve Harris
3718 @code{SWH Plugins} collection:
3720 ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
3724 Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite}
3727 ladspa=caps:Narrower
3731 Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library:
3733 ladspa=caps:White:.2
3737 Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library:
3739 ladspa=caps:Fractal:c=c1=1
3743 Dynamic volume normalization using @code{VLevel} plugin:
3745 ladspa=vlevel-ladspa:vlevel_mono
3749 @subsection Commands
3751 This filter supports the following commands:
3754 Modify the @var{N}-th control value.
3756 If the specified value is not valid, it is ignored and prior one is kept.
3761 EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
3762 Support for both single pass (livestreams, files) and double pass (files) modes.
3763 This algorithm can target IL, LRA, and maximum true peak. To accurately detect true peaks,
3764 the audio stream will be upsampled to 192 kHz unless the normalization mode is linear.
3765 Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate.
3767 The filter accepts the following options:
3771 Set integrated loudness target.
3772 Range is -70.0 - -5.0. Default value is -24.0.
3775 Set loudness range target.
3776 Range is 1.0 - 20.0. Default value is 7.0.
3779 Set maximum true peak.
3780 Range is -9.0 - +0.0. Default value is -2.0.
3782 @item measured_I, measured_i
3783 Measured IL of input file.
3784 Range is -99.0 - +0.0.
3786 @item measured_LRA, measured_lra
3787 Measured LRA of input file.
3788 Range is 0.0 - 99.0.
3790 @item measured_TP, measured_tp
3791 Measured true peak of input file.
3792 Range is -99.0 - +99.0.
3794 @item measured_thresh
3795 Measured threshold of input file.
3796 Range is -99.0 - +0.0.
3799 Set offset gain. Gain is applied before the true-peak limiter.
3800 Range is -99.0 - +99.0. Default is +0.0.
3803 Normalize linearly if possible.
3804 measured_I, measured_LRA, measured_TP, and measured_thresh must also
3805 to be specified in order to use this mode.
3806 Options are true or false. Default is true.
3809 Treat mono input files as "dual-mono". If a mono file is intended for playback
3810 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
3811 If set to @code{true}, this option will compensate for this effect.
3812 Multi-channel input files are not affected by this option.
3813 Options are true or false. Default is false.
3816 Set print format for stats. Options are summary, json, or none.
3817 Default value is none.
3822 Apply a low-pass filter with 3dB point frequency.
3823 The filter can be either single-pole or double-pole (the default).
3824 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
3826 The filter accepts the following options:
3830 Set frequency in Hz. Default is 500.
3833 Set number of poles. Default is 2.
3836 Set method to specify band-width of filter.
3851 Specify the band-width of a filter in width_type units.
3852 Applies only to double-pole filter.
3853 The default is 0.707q and gives a Butterworth response.
3856 Specify which channels to filter, by default all available are filtered.
3859 @subsection Examples
3862 Lowpass only LFE channel, it LFE is not present it does nothing:
3868 @subsection Commands
3870 This filter supports the following commands:
3873 Change lowpass frequency.
3874 Syntax for the command is : "@var{frequency}"
3877 Change lowpass width_type.
3878 Syntax for the command is : "@var{width_type}"
3881 Change lowpass width.
3882 Syntax for the command is : "@var{width}"
3887 Load a LV2 (LADSPA Version 2) plugin.
3889 To enable compilation of this filter you need to configure FFmpeg with
3890 @code{--enable-lv2}.
3894 Specifies the plugin URI. You may need to escape ':'.
3897 Set the '|' separated list of controls which are zero or more floating point
3898 values that determine the behavior of the loaded plugin (for example delay,
3900 If @option{controls} is set to @code{help}, all available controls and
3901 their valid ranges are printed.
3903 @item sample_rate, s
3904 Specify the sample rate, default to 44100. Only used if plugin have
3908 Set the number of samples per channel per each output frame, default
3909 is 1024. Only used if plugin have zero inputs.
3912 Set the minimum duration of the sourced audio. See
3913 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
3914 for the accepted syntax.
3915 Note that the resulting duration may be greater than the specified duration,
3916 as the generated audio is always cut at the end of a complete frame.
3917 If not specified, or the expressed duration is negative, the audio is
3918 supposed to be generated forever.
3919 Only used if plugin have zero inputs.
3922 @subsection Examples
3926 Apply bass enhancer plugin from Calf:
3928 lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
3932 Apply vinyl plugin from Calf:
3934 lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
3938 Apply bit crusher plugin from ArtyFX:
3940 lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
3945 Multiband Compress or expand the audio's dynamic range.
3947 The input audio is divided into bands using 4th order Linkwitz-Riley IIRs.
3948 This is akin to the crossover of a loudspeaker, and results in flat frequency
3949 response when absent compander action.
3951 It accepts the following parameters:
3955 This option syntax is:
3956 attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ...
3957 For explanation of each item refer to compand filter documentation.
3963 Mix channels with specific gain levels. The filter accepts the output
3964 channel layout followed by a set of channels definitions.
3966 This filter is also designed to efficiently remap the channels of an audio
3969 The filter accepts parameters of the form:
3970 "@var{l}|@var{outdef}|@var{outdef}|..."
3974 output channel layout or number of channels
3977 output channel specification, of the form:
3978 "@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]"
3981 output channel to define, either a channel name (FL, FR, etc.) or a channel
3982 number (c0, c1, etc.)
3985 multiplicative coefficient for the channel, 1 leaving the volume unchanged
3988 input channel to use, see out_name for details; it is not possible to mix
3989 named and numbered input channels
3992 If the `=' in a channel specification is replaced by `<', then the gains for
3993 that specification will be renormalized so that the total is 1, thus
3994 avoiding clipping noise.
3996 @subsection Mixing examples
3998 For example, if you want to down-mix from stereo to mono, but with a bigger
3999 factor for the left channel:
4001 pan=1c|c0=0.9*c0+0.1*c1
4004 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
4005 7-channels surround:
4007 pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
4010 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
4011 that should be preferred (see "-ac" option) unless you have very specific
4014 @subsection Remapping examples
4016 The channel remapping will be effective if, and only if:
4019 @item gain coefficients are zeroes or ones,
4020 @item only one input per channel output,
4023 If all these conditions are satisfied, the filter will notify the user ("Pure
4024 channel mapping detected"), and use an optimized and lossless method to do the
4027 For example, if you have a 5.1 source and want a stereo audio stream by
4028 dropping the extra channels:
4030 pan="stereo| c0=FL | c1=FR"
4033 Given the same source, you can also switch front left and front right channels
4034 and keep the input channel layout:
4036 pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
4039 If the input is a stereo audio stream, you can mute the front left channel (and
4040 still keep the stereo channel layout) with:
4045 Still with a stereo audio stream input, you can copy the right channel in both
4046 front left and right:
4048 pan="stereo| c0=FR | c1=FR"
4053 ReplayGain scanner filter. This filter takes an audio stream as an input and
4054 outputs it unchanged.
4055 At end of filtering it displays @code{track_gain} and @code{track_peak}.
4059 Convert the audio sample format, sample rate and channel layout. It is
4060 not meant to be used directly.
4063 Apply time-stretching and pitch-shifting with librubberband.
4065 To enable compilation of this filter, you need to configure FFmpeg with
4066 @code{--enable-librubberband}.
4068 The filter accepts the following options:
4072 Set tempo scale factor.
4075 Set pitch scale factor.
4078 Set transients detector.
4079 Possible values are:
4088 Possible values are:
4097 Possible values are:
4104 Set processing window size.
4105 Possible values are:
4114 Possible values are:
4121 Enable formant preservation when shift pitching.
4122 Possible values are:
4130 Possible values are:
4139 Possible values are:
4146 @section sidechaincompress
4148 This filter acts like normal compressor but has the ability to compress
4149 detected signal using second input signal.
4150 It needs two input streams and returns one output stream.
4151 First input stream will be processed depending on second stream signal.
4152 The filtered signal then can be filtered with other filters in later stages of
4153 processing. See @ref{pan} and @ref{amerge} filter.
4155 The filter accepts the following options:
4159 Set input gain. Default is 1. Range is between 0.015625 and 64.
4162 If a signal of second stream raises above this level it will affect the gain
4163 reduction of first stream.
4164 By default is 0.125. Range is between 0.00097563 and 1.
4167 Set a ratio about which the signal is reduced. 1:2 means that if the level
4168 raised 4dB above the threshold, it will be only 2dB above after the reduction.
4169 Default is 2. Range is between 1 and 20.
4172 Amount of milliseconds the signal has to rise above the threshold before gain
4173 reduction starts. Default is 20. Range is between 0.01 and 2000.
4176 Amount of milliseconds the signal has to fall below the threshold before
4177 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
4180 Set the amount by how much signal will be amplified after processing.
4181 Default is 1. Range is from 1 to 64.
4184 Curve the sharp knee around the threshold to enter gain reduction more softly.
4185 Default is 2.82843. Range is between 1 and 8.
4188 Choose if the @code{average} level between all channels of side-chain stream
4189 or the louder(@code{maximum}) channel of side-chain stream affects the
4190 reduction. Default is @code{average}.
4193 Should the exact signal be taken in case of @code{peak} or an RMS one in case
4194 of @code{rms}. Default is @code{rms} which is mainly smoother.
4197 Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
4200 How much to use compressed signal in output. Default is 1.
4201 Range is between 0 and 1.
4204 @subsection Examples
4208 Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
4209 depending on the signal of 2nd input and later compressed signal to be
4210 merged with 2nd input:
4212 ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
4216 @section sidechaingate
4218 A sidechain gate acts like a normal (wideband) gate but has the ability to
4219 filter the detected signal before sending it to the gain reduction stage.
4220 Normally a gate uses the full range signal to detect a level above the
4222 For example: If you cut all lower frequencies from your sidechain signal
4223 the gate will decrease the volume of your track only if not enough highs
4224 appear. With this technique you are able to reduce the resonation of a
4225 natural drum or remove "rumbling" of muted strokes from a heavily distorted
4227 It needs two input streams and returns one output stream.
4228 First input stream will be processed depending on second stream signal.
4230 The filter accepts the following options:
4234 Set input level before filtering.
4235 Default is 1. Allowed range is from 0.015625 to 64.
4238 Set the level of gain reduction when the signal is below the threshold.
4239 Default is 0.06125. Allowed range is from 0 to 1.
4242 If a signal rises above this level the gain reduction is released.
4243 Default is 0.125. Allowed range is from 0 to 1.
4246 Set a ratio about which the signal is reduced.
4247 Default is 2. Allowed range is from 1 to 9000.
4250 Amount of milliseconds the signal has to rise above the threshold before gain
4252 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
4255 Amount of milliseconds the signal has to fall below the threshold before the
4256 reduction is increased again. Default is 250 milliseconds.
4257 Allowed range is from 0.01 to 9000.
4260 Set amount of amplification of signal after processing.
4261 Default is 1. Allowed range is from 1 to 64.
4264 Curve the sharp knee around the threshold to enter gain reduction more softly.
4265 Default is 2.828427125. Allowed range is from 1 to 8.
4268 Choose if exact signal should be taken for detection or an RMS like one.
4269 Default is rms. Can be peak or rms.
4272 Choose if the average level between all channels or the louder channel affects
4274 Default is average. Can be average or maximum.
4277 Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
4280 @section silencedetect
4282 Detect silence in an audio stream.
4284 This filter logs a message when it detects that the input audio volume is less
4285 or equal to a noise tolerance value for a duration greater or equal to the
4286 minimum detected noise duration.
4288 The printed times and duration are expressed in seconds.
4290 The filter accepts the following options:
4294 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
4295 specified value) or amplitude ratio. Default is -60dB, or 0.001.
4298 Set silence duration until notification (default is 2 seconds).
4301 Process each channel separately, instead of combined. By default is disabled.
4304 @subsection Examples
4308 Detect 5 seconds of silence with -50dB noise tolerance:
4310 silencedetect=n=-50dB:d=5
4314 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
4315 tolerance in @file{silence.mp3}:
4317 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
4321 @section silenceremove
4323 Remove silence from the beginning, middle or end of the audio.
4325 The filter accepts the following options:
4329 This value is used to indicate if audio should be trimmed at beginning of
4330 the audio. A value of zero indicates no silence should be trimmed from the
4331 beginning. When specifying a non-zero value, it trims audio up until it
4332 finds non-silence. Normally, when trimming silence from beginning of audio
4333 the @var{start_periods} will be @code{1} but it can be increased to higher
4334 values to trim all audio up to specific count of non-silence periods.
4335 Default value is @code{0}.
4337 @item start_duration
4338 Specify the amount of time that non-silence must be detected before it stops
4339 trimming audio. By increasing the duration, bursts of noises can be treated
4340 as silence and trimmed off. Default value is @code{0}.
4342 @item start_threshold
4343 This indicates what sample value should be treated as silence. For digital
4344 audio, a value of @code{0} may be fine but for audio recorded from analog,
4345 you may wish to increase the value to account for background noise.
4346 Can be specified in dB (in case "dB" is appended to the specified value)
4347 or amplitude ratio. Default value is @code{0}.
4350 Specify max duration of silence at beginning that will be kept after
4351 trimming. Default is 0, which is equal to trimming all samples detected
4355 Specify mode of detection of silence end in start of multi-channel audio.
4356 Can be @var{any} or @var{all}. Default is @var{any}.
4357 With @var{any}, any sample that is detected as non-silence will cause
4358 stopped trimming of silence.
4359 With @var{all}, only if all channels are detected as non-silence will cause
4360 stopped trimming of silence.
4363 Set the count for trimming silence from the end of audio.
4364 To remove silence from the middle of a file, specify a @var{stop_periods}
4365 that is negative. This value is then treated as a positive value and is
4366 used to indicate the effect should restart processing as specified by
4367 @var{start_periods}, making it suitable for removing periods of silence
4368 in the middle of the audio.
4369 Default value is @code{0}.
4372 Specify a duration of silence that must exist before audio is not copied any
4373 more. By specifying a higher duration, silence that is wanted can be left in
4375 Default value is @code{0}.
4377 @item stop_threshold
4378 This is the same as @option{start_threshold} but for trimming silence from
4380 Can be specified in dB (in case "dB" is appended to the specified value)
4381 or amplitude ratio. Default value is @code{0}.
4384 Specify max duration of silence at end that will be kept after
4385 trimming. Default is 0, which is equal to trimming all samples detected
4389 Specify mode of detection of silence start in end of multi-channel audio.
4390 Can be @var{any} or @var{all}. Default is @var{any}.
4391 With @var{any}, any sample that is detected as non-silence will cause
4392 stopped trimming of silence.
4393 With @var{all}, only if all channels are detected as non-silence will cause
4394 stopped trimming of silence.
4397 Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
4398 and works better with digital silence which is exactly 0.
4399 Default value is @code{rms}.
4402 Set duration in number of seconds used to calculate size of window in number
4403 of samples for detecting silence.
4404 Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
4407 @subsection Examples
4411 The following example shows how this filter can be used to start a recording
4412 that does not contain the delay at the start which usually occurs between
4413 pressing the record button and the start of the performance:
4415 silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
4419 Trim all silence encountered from beginning to end where there is more than 1
4420 second of silence in audio:
4422 silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
4428 SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
4429 loudspeakers around the user for binaural listening via headphones (audio
4430 formats up to 9 channels supported).
4431 The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
4432 SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
4433 Austrian Academy of Sciences.
4435 To enable compilation of this filter you need to configure FFmpeg with
4436 @code{--enable-libmysofa}.
4438 The filter accepts the following options:
4442 Set the SOFA file used for rendering.
4445 Set gain applied to audio. Value is in dB. Default is 0.
4448 Set rotation of virtual loudspeakers in deg. Default is 0.
4451 Set elevation of virtual speakers in deg. Default is 0.
4454 Set distance in meters between loudspeakers and the listener with near-field
4455 HRTFs. Default is 1.
4458 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
4459 processing audio in time domain which is slow.
4460 @var{freq} is processing audio in frequency domain which is fast.
4461 Default is @var{freq}.
4464 Set custom positions of virtual loudspeakers. Syntax for this option is:
4465 <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
4466 Each virtual loudspeaker is described with short channel name following with
4467 azimuth and elevation in degrees.
4468 Each virtual loudspeaker description is separated by '|'.
4469 For example to override front left and front right channel positions use:
4470 'speakers=FL 45 15|FR 345 15'.
4471 Descriptions with unrecognised channel names are ignored.
4474 Set custom gain for LFE channels. Value is in dB. Default is 0.
4477 @subsection Examples
4481 Using ClubFritz6 sofa file:
4483 sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
4487 Using ClubFritz12 sofa file and bigger radius with small rotation:
4489 sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
4493 Similar as above but with custom speaker positions for front left, front right, back left and back right
4494 and also with custom gain:
4496 "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
4500 @section stereotools
4502 This filter has some handy utilities to manage stereo signals, for converting
4503 M/S stereo recordings to L/R signal while having control over the parameters
4504 or spreading the stereo image of master track.
4506 The filter accepts the following options:
4510 Set input level before filtering for both channels. Defaults is 1.
4511 Allowed range is from 0.015625 to 64.
4514 Set output level after filtering for both channels. Defaults is 1.
4515 Allowed range is from 0.015625 to 64.
4518 Set input balance between both channels. Default is 0.
4519 Allowed range is from -1 to 1.
4522 Set output balance between both channels. Default is 0.
4523 Allowed range is from -1 to 1.
4526 Enable softclipping. Results in analog distortion instead of harsh digital 0dB
4527 clipping. Disabled by default.
4530 Mute the left channel. Disabled by default.
4533 Mute the right channel. Disabled by default.
4536 Change the phase of the left channel. Disabled by default.
4539 Change the phase of the right channel. Disabled by default.
4542 Set stereo mode. Available values are:
4546 Left/Right to Left/Right, this is default.
4549 Left/Right to Mid/Side.
4552 Mid/Side to Left/Right.
4555 Left/Right to Left/Left.
4558 Left/Right to Right/Right.
4561 Left/Right to Left + Right.
4564 Left/Right to Right/Left.
4567 Mid/Side to Left/Left.
4570 Mid/Side to Right/Right.
4574 Set level of side signal. Default is 1.
4575 Allowed range is from 0.015625 to 64.
4578 Set balance of side signal. Default is 0.
4579 Allowed range is from -1 to 1.
4582 Set level of the middle signal. Default is 1.
4583 Allowed range is from 0.015625 to 64.
4586 Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
4589 Set stereo base between mono and inversed channels. Default is 0.
4590 Allowed range is from -1 to 1.
4593 Set delay in milliseconds how much to delay left from right channel and
4594 vice versa. Default is 0. Allowed range is from -20 to 20.
4597 Set S/C level. Default is 1. Allowed range is from 1 to 100.
4600 Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
4602 @item bmode_in, bmode_out
4603 Set balance mode for balance_in/balance_out option.
4605 Can be one of the following:
4609 Classic balance mode. Attenuate one channel at time.
4610 Gain is raised up to 1.
4613 Similar as classic mode above but gain is raised up to 2.
4616 Equal power distribution, from -6dB to +6dB range.
4620 @subsection Examples
4624 Apply karaoke like effect:
4626 stereotools=mlev=0.015625
4630 Convert M/S signal to L/R:
4632 "stereotools=mode=ms>lr"
4636 @section stereowiden
4638 This filter enhance the stereo effect by suppressing signal common to both
4639 channels and by delaying the signal of left into right and vice versa,
4640 thereby widening the stereo effect.
4642 The filter accepts the following options:
4646 Time in milliseconds of the delay of left signal into right and vice versa.
4647 Default is 20 milliseconds.
4650 Amount of gain in delayed signal into right and vice versa. Gives a delay
4651 effect of left signal in right output and vice versa which gives widening
4652 effect. Default is 0.3.
4655 Cross feed of left into right with inverted phase. This helps in suppressing
4656 the mono. If the value is 1 it will cancel all the signal common to both
4657 channels. Default is 0.3.
4660 Set level of input signal of original channel. Default is 0.8.
4663 @section superequalizer
4664 Apply 18 band equalizer.
4666 The filter accepts the following options:
4673 Set 131Hz band gain.
4675 Set 185Hz band gain.
4677 Set 262Hz band gain.
4679 Set 370Hz band gain.
4681 Set 523Hz band gain.
4683 Set 740Hz band gain.
4685 Set 1047Hz band gain.
4687 Set 1480Hz band gain.
4689 Set 2093Hz band gain.
4691 Set 2960Hz band gain.
4693 Set 4186Hz band gain.
4695 Set 5920Hz band gain.
4697 Set 8372Hz band gain.
4699 Set 11840Hz band gain.
4701 Set 16744Hz band gain.
4703 Set 20000Hz band gain.
4707 Apply audio surround upmix filter.
4709 This filter allows to produce multichannel output from audio stream.
4711 The filter accepts the following options:
4715 Set output channel layout. By default, this is @var{5.1}.
4717 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4718 for the required syntax.
4721 Set input channel layout. By default, this is @var{stereo}.
4723 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4724 for the required syntax.
4727 Set input volume level. By default, this is @var{1}.
4730 Set output volume level. By default, this is @var{1}.
4733 Enable LFE channel output if output channel layout has it. By default, this is enabled.
4736 Set LFE low cut off frequency. By default, this is @var{128} Hz.
4739 Set LFE high cut off frequency. By default, this is @var{256} Hz.
4742 Set front center input volume. By default, this is @var{1}.
4745 Set front center output volume. By default, this is @var{1}.
4748 Set LFE input volume. By default, this is @var{1}.
4751 Set LFE output volume. By default, this is @var{1}.
4754 @section treble, highshelf
4756 Boost or cut treble (upper) frequencies of the audio using a two-pole
4757 shelving filter with a response similar to that of a standard
4758 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
4760 The filter accepts the following options:
4764 Give the gain at whichever is the lower of ~22 kHz and the
4765 Nyquist frequency. Its useful range is about -20 (for a large cut)
4766 to +20 (for a large boost). Beware of clipping when using a positive gain.
4769 Set the filter's central frequency and so can be used
4770 to extend or reduce the frequency range to be boosted or cut.
4771 The default value is @code{3000} Hz.
4774 Set method to specify band-width of filter.
4789 Determine how steep is the filter's shelf transition.
4792 Specify which channels to filter, by default all available are filtered.
4795 @subsection Commands
4797 This filter supports the following commands:
4800 Change treble frequency.
4801 Syntax for the command is : "@var{frequency}"
4804 Change treble width_type.
4805 Syntax for the command is : "@var{width_type}"
4808 Change treble width.
4809 Syntax for the command is : "@var{width}"
4813 Syntax for the command is : "@var{gain}"
4818 Sinusoidal amplitude modulation.
4820 The filter accepts the following options:
4824 Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
4825 (20 Hz or lower) will result in a tremolo effect.
4826 This filter may also be used as a ring modulator by specifying
4827 a modulation frequency higher than 20 Hz.
4828 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
4831 Depth of modulation as a percentage. Range is 0.0 - 1.0.
4832 Default value is 0.5.
4837 Sinusoidal phase modulation.
4839 The filter accepts the following options:
4843 Modulation frequency in Hertz.
4844 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
4847 Depth of modulation as a percentage. Range is 0.0 - 1.0.
4848 Default value is 0.5.
4853 Adjust the input audio volume.
4855 It accepts the following parameters:
4859 Set audio volume expression.
4861 Output values are clipped to the maximum value.
4863 The output audio volume is given by the relation:
4865 @var{output_volume} = @var{volume} * @var{input_volume}
4868 The default value for @var{volume} is "1.0".
4871 This parameter represents the mathematical precision.
4873 It determines which input sample formats will be allowed, which affects the
4874 precision of the volume scaling.
4878 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
4880 32-bit floating-point; this limits input sample format to FLT. (default)
4882 64-bit floating-point; this limits input sample format to DBL.
4886 Choose the behaviour on encountering ReplayGain side data in input frames.
4890 Remove ReplayGain side data, ignoring its contents (the default).
4893 Ignore ReplayGain side data, but leave it in the frame.
4896 Prefer the track gain, if present.
4899 Prefer the album gain, if present.
4902 @item replaygain_preamp
4903 Pre-amplification gain in dB to apply to the selected replaygain gain.
4905 Default value for @var{replaygain_preamp} is 0.0.
4908 Set when the volume expression is evaluated.
4910 It accepts the following values:
4913 only evaluate expression once during the filter initialization, or
4914 when the @samp{volume} command is sent
4917 evaluate expression for each incoming frame
4920 Default value is @samp{once}.
4923 The volume expression can contain the following parameters.
4927 frame number (starting at zero)
4930 @item nb_consumed_samples
4931 number of samples consumed by the filter
4933 number of samples in the current frame
4935 original frame position in the file
4941 PTS at start of stream
4943 time at start of stream
4949 last set volume value
4952 Note that when @option{eval} is set to @samp{once} only the
4953 @var{sample_rate} and @var{tb} variables are available, all other
4954 variables will evaluate to NAN.
4956 @subsection Commands
4958 This filter supports the following commands:
4961 Modify the volume expression.
4962 The command accepts the same syntax of the corresponding option.
4964 If the specified expression is not valid, it is kept at its current
4966 @item replaygain_noclip
4967 Prevent clipping by limiting the gain applied.
4969 Default value for @var{replaygain_noclip} is 1.
4973 @subsection Examples
4977 Halve the input audio volume:
4981 volume=volume=-6.0206dB
4984 In all the above example the named key for @option{volume} can be
4985 omitted, for example like in:
4991 Increase input audio power by 6 decibels using fixed-point precision:
4993 volume=volume=6dB:precision=fixed
4997 Fade volume after time 10 with an annihilation period of 5 seconds:
4999 volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
5003 @section volumedetect
5005 Detect the volume of the input video.
5007 The filter has no parameters. The input is not modified. Statistics about
5008 the volume will be printed in the log when the input stream end is reached.
5010 In particular it will show the mean volume (root mean square), maximum
5011 volume (on a per-sample basis), and the beginning of a histogram of the
5012 registered volume values (from the maximum value to a cumulated 1/1000 of
5015 All volumes are in decibels relative to the maximum PCM value.
5017 @subsection Examples
5019 Here is an excerpt of the output:
5021 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
5022 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
5023 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
5024 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
5025 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
5026 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
5027 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
5028 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
5029 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
5035 The mean square energy is approximately -27 dB, or 10^-2.7.
5037 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
5039 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
5042 In other words, raising the volume by +4 dB does not cause any clipping,
5043 raising it by +5 dB causes clipping for 6 samples, etc.
5045 @c man end AUDIO FILTERS
5047 @chapter Audio Sources
5048 @c man begin AUDIO SOURCES
5050 Below is a description of the currently available audio sources.
5054 Buffer audio frames, and make them available to the filter chain.
5056 This source is mainly intended for a programmatic use, in particular
5057 through the interface defined in @file{libavfilter/asrc_abuffer.h}.
5059 It accepts the following parameters:
5063 The timebase which will be used for timestamps of submitted frames. It must be
5064 either a floating-point number or in @var{numerator}/@var{denominator} form.
5067 The sample rate of the incoming audio buffers.
5070 The sample format of the incoming audio buffers.
5071 Either a sample format name or its corresponding integer representation from
5072 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
5074 @item channel_layout
5075 The channel layout of the incoming audio buffers.
5076 Either a channel layout name from channel_layout_map in
5077 @file{libavutil/channel_layout.c} or its corresponding integer representation
5078 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
5081 The number of channels of the incoming audio buffers.
5082 If both @var{channels} and @var{channel_layout} are specified, then they
5087 @subsection Examples
5090 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
5093 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
5094 Since the sample format with name "s16p" corresponds to the number
5095 6 and the "stereo" channel layout corresponds to the value 0x3, this is
5098 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
5103 Generate an audio signal specified by an expression.
5105 This source accepts in input one or more expressions (one for each
5106 channel), which are evaluated and used to generate a corresponding
5109 This source accepts the following options:
5113 Set the '|'-separated expressions list for each separate channel. In case the
5114 @option{channel_layout} option is not specified, the selected channel layout
5115 depends on the number of provided expressions. Otherwise the last
5116 specified expression is applied to the remaining output channels.
5118 @item channel_layout, c
5119 Set the channel layout. The number of channels in the specified layout
5120 must be equal to the number of specified expressions.
5123 Set the minimum duration of the sourced audio. See
5124 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5125 for the accepted syntax.
5126 Note that the resulting duration may be greater than the specified
5127 duration, as the generated audio is always cut at the end of a
5130 If not specified, or the expressed duration is negative, the audio is
5131 supposed to be generated forever.
5134 Set the number of samples per channel per each output frame,
5137 @item sample_rate, s
5138 Specify the sample rate, default to 44100.
5141 Each expression in @var{exprs} can contain the following constants:
5145 number of the evaluated sample, starting from 0
5148 time of the evaluated sample expressed in seconds, starting from 0
5155 @subsection Examples
5165 Generate a sin signal with frequency of 440 Hz, set sample rate to
5168 aevalsrc="sin(440*2*PI*t):s=8000"
5172 Generate a two channels signal, specify the channel layout (Front
5173 Center + Back Center) explicitly:
5175 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
5179 Generate white noise:
5181 aevalsrc="-2+random(0)"
5185 Generate an amplitude modulated signal:
5187 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
5191 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
5193 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
5200 The null audio source, return unprocessed audio frames. It is mainly useful
5201 as a template and to be employed in analysis / debugging tools, or as
5202 the source for filters which ignore the input data (for example the sox
5205 This source accepts the following options:
5209 @item channel_layout, cl
5211 Specifies the channel layout, and can be either an integer or a string
5212 representing a channel layout. The default value of @var{channel_layout}
5215 Check the channel_layout_map definition in
5216 @file{libavutil/channel_layout.c} for the mapping between strings and
5217 channel layout values.
5219 @item sample_rate, r
5220 Specifies the sample rate, and defaults to 44100.
5223 Set the number of samples per requested frames.
5227 @subsection Examples
5231 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
5233 anullsrc=r=48000:cl=4
5237 Do the same operation with a more obvious syntax:
5239 anullsrc=r=48000:cl=mono
5243 All the parameters need to be explicitly defined.
5247 Synthesize a voice utterance using the libflite library.
5249 To enable compilation of this filter you need to configure FFmpeg with
5250 @code{--enable-libflite}.
5252 Note that versions of the flite library prior to 2.0 are not thread-safe.
5254 The filter accepts the following options:
5259 If set to 1, list the names of the available voices and exit
5260 immediately. Default value is 0.
5263 Set the maximum number of samples per frame. Default value is 512.
5266 Set the filename containing the text to speak.
5269 Set the text to speak.
5272 Set the voice to use for the speech synthesis. Default value is
5273 @code{kal}. See also the @var{list_voices} option.
5276 @subsection Examples
5280 Read from file @file{speech.txt}, and synthesize the text using the
5281 standard flite voice:
5283 flite=textfile=speech.txt
5287 Read the specified text selecting the @code{slt} voice:
5289 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
5293 Input text to ffmpeg:
5295 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
5299 Make @file{ffplay} speak the specified text, using @code{flite} and
5300 the @code{lavfi} device:
5302 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
5306 For more information about libflite, check:
5307 @url{http://www.festvox.org/flite/}
5311 Generate a noise audio signal.
5313 The filter accepts the following options:
5316 @item sample_rate, r
5317 Specify the sample rate. Default value is 48000 Hz.
5320 Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value
5324 Specify the duration of the generated audio stream. Not specifying this option
5325 results in noise with an infinite length.
5327 @item color, colour, c
5328 Specify the color of noise. Available noise colors are white, pink, brown,
5329 blue and violet. Default color is white.
5332 Specify a value used to seed the PRNG.
5335 Set the number of samples per each output frame, default is 1024.
5338 @subsection Examples
5343 Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5:
5345 anoisesrc=d=60:c=pink:r=44100:a=0.5
5351 Generate odd-tap Hilbert transform FIR coefficients.
5353 The resulting stream can be used with @ref{afir} filter for phase-shifting
5354 the signal by 90 degrees.
5356 This is used in many matrix coding schemes and for analytic signal generation.
5357 The process is often written as a multiplication by i (or j), the imaginary unit.
5359 The filter accepts the following options:
5363 @item sample_rate, s
5364 Set sample rate, default is 44100.
5367 Set length of FIR filter, default is 22051.
5370 Set number of samples per each frame.
5373 Set window function to be used when generating FIR coefficients.
5378 Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients.
5380 The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
5382 The filter accepts the following options:
5385 @item sample_rate, r
5386 Set sample rate, default is 44100.
5389 Set number of samples per each frame. Default is 1024.
5392 Set high-pass frequency. Default is 0.
5395 Set low-pass frequency. Default is 0.
5396 If high-pass frequency is lower than low-pass frequency and low-pass frequency
5397 is higher than 0 then filter will create band-pass filter coefficients,
5398 otherwise band-reject filter coefficients.
5401 Set filter phase response. Default is 50. Allowed range is from 0 to 100.
5404 Set Kaiser window beta.
5407 Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB.
5410 Enable rounding, by default is disabled.
5413 Set number of taps for high-pass filter.
5416 Set number of taps for low-pass filter.
5421 Generate an audio signal made of a sine wave with amplitude 1/8.
5423 The audio signal is bit-exact.
5425 The filter accepts the following options:
5430 Set the carrier frequency. Default is 440 Hz.
5432 @item beep_factor, b
5433 Enable a periodic beep every second with frequency @var{beep_factor} times
5434 the carrier frequency. Default is 0, meaning the beep is disabled.
5436 @item sample_rate, r
5437 Specify the sample rate, default is 44100.
5440 Specify the duration of the generated audio stream.
5442 @item samples_per_frame
5443 Set the number of samples per output frame.
5445 The expression can contain the following constants:
5449 The (sequential) number of the output audio frame, starting from 0.
5452 The PTS (Presentation TimeStamp) of the output audio frame,
5453 expressed in @var{TB} units.
5456 The PTS of the output audio frame, expressed in seconds.
5459 The timebase of the output audio frames.
5462 Default is @code{1024}.
5465 @subsection Examples
5470 Generate a simple 440 Hz sine wave:
5476 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
5480 sine=frequency=220:beep_factor=4:duration=5
5484 Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC
5487 sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
5491 @c man end AUDIO SOURCES
5493 @chapter Audio Sinks
5494 @c man begin AUDIO SINKS
5496 Below is a description of the currently available audio sinks.
5498 @section abuffersink
5500 Buffer audio frames, and make them available to the end of filter chain.
5502 This sink is mainly intended for programmatic use, in particular
5503 through the interface defined in @file{libavfilter/buffersink.h}
5504 or the options system.
5506 It accepts a pointer to an AVABufferSinkContext structure, which
5507 defines the incoming buffers' formats, to be passed as the opaque
5508 parameter to @code{avfilter_init_filter} for initialization.
5511 Null audio sink; do absolutely nothing with the input audio. It is
5512 mainly useful as a template and for use in analysis / debugging
5515 @c man end AUDIO SINKS
5517 @chapter Video Filters
5518 @c man begin VIDEO FILTERS
5520 When you configure your FFmpeg build, you can disable any of the
5521 existing filters using @code{--disable-filters}.
5522 The configure output will show the video filters included in your
5525 Below is a description of the currently available video filters.
5527 @section alphaextract
5529 Extract the alpha component from the input as a grayscale video. This
5530 is especially useful with the @var{alphamerge} filter.
5534 Add or replace the alpha component of the primary input with the
5535 grayscale value of a second input. This is intended for use with
5536 @var{alphaextract} to allow the transmission or storage of frame
5537 sequences that have alpha in a format that doesn't support an alpha
5540 For example, to reconstruct full frames from a normal YUV-encoded video
5541 and a separate video created with @var{alphaextract}, you might use:
5543 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
5546 Since this filter is designed for reconstruction, it operates on frame
5547 sequences without considering timestamps, and terminates when either
5548 input reaches end of stream. This will cause problems if your encoding
5549 pipeline drops frames. If you're trying to apply an image as an
5550 overlay to a video stream, consider the @var{overlay} filter instead.
5554 Amplify differences between current pixel and pixels of adjacent frames in
5555 same pixel location.
5557 This filter accepts the following options:
5561 Set frame radius. Default is 2. Allowed range is from 1 to 63.
5562 For example radius of 3 will instruct filter to calculate average of 7 frames.
5565 Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535.
5568 Set threshold for difference amplification. Any differrence greater or equal to
5569 this value will not alter source pixel. Default is 10.
5570 Allowed range is from 0 to 65535.
5573 Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
5574 This option controls maximum possible value that will decrease source pixel value.
5577 Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
5578 This option controls maximum possible value that will increase source pixel value.
5581 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
5586 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
5587 and libavformat to work. On the other hand, it is limited to ASS (Advanced
5588 Substation Alpha) subtitles files.
5590 This filter accepts the following option in addition to the common options from
5591 the @ref{subtitles} filter:
5595 Set the shaping engine
5597 Available values are:
5600 The default libass shaping engine, which is the best available.
5602 Fast, font-agnostic shaper that can do only substitutions
5604 Slower shaper using OpenType for substitutions and positioning
5607 The default is @code{auto}.
5611 Apply an Adaptive Temporal Averaging Denoiser to the video input.
5613 The filter accepts the following options:
5617 Set threshold A for 1st plane. Default is 0.02.
5618 Valid range is 0 to 0.3.
5621 Set threshold B for 1st plane. Default is 0.04.
5622 Valid range is 0 to 5.
5625 Set threshold A for 2nd plane. Default is 0.02.
5626 Valid range is 0 to 0.3.
5629 Set threshold B for 2nd plane. Default is 0.04.
5630 Valid range is 0 to 5.
5633 Set threshold A for 3rd plane. Default is 0.02.
5634 Valid range is 0 to 0.3.
5637 Set threshold B for 3rd plane. Default is 0.04.
5638 Valid range is 0 to 5.
5640 Threshold A is designed to react on abrupt changes in the input signal and
5641 threshold B is designed to react on continuous changes in the input signal.
5644 Set number of frames filter will use for averaging. Default is 9. Must be odd
5645 number in range [5, 129].
5648 Set what planes of frame filter will use for averaging. Default is all.
5653 Apply average blur filter.
5655 The filter accepts the following options:
5659 Set horizontal radius size.
5662 Set which planes to filter. By default all planes are filtered.
5665 Set vertical radius size, if zero it will be same as @code{sizeX}.
5666 Default is @code{0}.
5671 Compute the bounding box for the non-black pixels in the input frame
5674 This filter computes the bounding box containing all the pixels with a
5675 luminance value greater than the minimum allowed value.
5676 The parameters describing the bounding box are printed on the filter
5679 The filter accepts the following option:
5683 Set the minimal luminance value. Default is @code{16}.
5686 @section bitplanenoise
5688 Show and measure bit plane noise.
5690 The filter accepts the following options:
5694 Set which plane to analyze. Default is @code{1}.
5697 Filter out noisy pixels from @code{bitplane} set above.
5698 Default is disabled.
5701 @section blackdetect
5703 Detect video intervals that are (almost) completely black. Can be
5704 useful to detect chapter transitions, commercials, or invalid
5705 recordings. Output lines contains the time for the start, end and
5706 duration of the detected black interval expressed in seconds.
5708 In order to display the output lines, you need to set the loglevel at
5709 least to the AV_LOG_INFO value.
5711 The filter accepts the following options:
5714 @item black_min_duration, d
5715 Set the minimum detected black duration expressed in seconds. It must
5716 be a non-negative floating point number.
5718 Default value is 2.0.
5720 @item picture_black_ratio_th, pic_th
5721 Set the threshold for considering a picture "black".
5722 Express the minimum value for the ratio:
5724 @var{nb_black_pixels} / @var{nb_pixels}
5727 for which a picture is considered black.
5728 Default value is 0.98.
5730 @item pixel_black_th, pix_th
5731 Set the threshold for considering a pixel "black".
5733 The threshold expresses the maximum pixel luminance value for which a
5734 pixel is considered "black". The provided value is scaled according to
5735 the following equation:
5737 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
5740 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
5741 the input video format, the range is [0-255] for YUV full-range
5742 formats and [16-235] for YUV non full-range formats.
5744 Default value is 0.10.
5747 The following example sets the maximum pixel threshold to the minimum
5748 value, and detects only black intervals of 2 or more seconds:
5750 blackdetect=d=2:pix_th=0.00
5755 Detect frames that are (almost) completely black. Can be useful to
5756 detect chapter transitions or commercials. Output lines consist of
5757 the frame number of the detected frame, the percentage of blackness,
5758 the position in the file if known or -1 and the timestamp in seconds.
5760 In order to display the output lines, you need to set the loglevel at
5761 least to the AV_LOG_INFO value.
5763 This filter exports frame metadata @code{lavfi.blackframe.pblack}.
5764 The value represents the percentage of pixels in the picture that
5765 are below the threshold value.
5767 It accepts the following parameters:
5772 The percentage of the pixels that have to be below the threshold; it defaults to
5775 @item threshold, thresh
5776 The threshold below which a pixel value is considered black; it defaults to
5781 @section blend, tblend
5783 Blend two video frames into each other.
5785 The @code{blend} filter takes two input streams and outputs one
5786 stream, the first input is the "top" layer and second input is
5787 "bottom" layer. By default, the output terminates when the longest input terminates.
5789 The @code{tblend} (time blend) filter takes two consecutive frames
5790 from one single stream, and outputs the result obtained by blending
5791 the new frame on top of the old frame.
5793 A description of the accepted options follows.
5801 Set blend mode for specific pixel component or all pixel components in case
5802 of @var{all_mode}. Default value is @code{normal}.
5804 Available values for component modes are:
5846 Set blend opacity for specific pixel component or all pixel components in case
5847 of @var{all_opacity}. Only used in combination with pixel component blend modes.
5854 Set blend expression for specific pixel component or all pixel components in case
5855 of @var{all_expr}. Note that related mode options will be ignored if those are set.
5857 The expressions can use the following variables:
5861 The sequential number of the filtered frame, starting from @code{0}.
5865 the coordinates of the current sample
5869 the width and height of currently filtered plane
5873 Width and height scale for the plane being filtered. It is the
5874 ratio between the dimensions of the current plane to the luma plane,
5875 e.g. for a @code{yuv420p} frame, the values are @code{1,1} for
5876 the luma plane and @code{0.5,0.5} for the chroma planes.
5879 Time of the current frame, expressed in seconds.
5882 Value of pixel component at current location for first video frame (top layer).
5885 Value of pixel component at current location for second video frame (bottom layer).
5889 The @code{blend} filter also supports the @ref{framesync} options.
5891 @subsection Examples
5895 Apply transition from bottom layer to top layer in first 10 seconds:
5897 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
5901 Apply linear horizontal transition from top layer to bottom layer:
5903 blend=all_expr='A*(X/W)+B*(1-X/W)'
5907 Apply 1x1 checkerboard effect:
5909 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
5913 Apply uncover left effect:
5915 blend=all_expr='if(gte(N*SW+X,W),A,B)'
5919 Apply uncover down effect:
5921 blend=all_expr='if(gte(Y-N*SH,0),A,B)'
5925 Apply uncover up-left effect:
5927 blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
5931 Split diagonally video and shows top and bottom layer on each side:
5933 blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
5937 Display differences between the current and the previous frame:
5939 tblend=all_mode=grainextract
5945 Denoise frames using Block-Matching 3D algorithm.
5947 The filter accepts the following options.
5951 Set denoising strength. Default value is 1.
5952 Allowed range is from 0 to 999.9.
5953 The denoising algorith is very sensitive to sigma, so adjust it
5954 according to the source.
5957 Set local patch size. This sets dimensions in 2D.
5960 Set sliding step for processing blocks. Default value is 4.
5961 Allowed range is from 1 to 64.
5962 Smaller values allows processing more reference blocks and is slower.
5965 Set maximal number of similar blocks for 3rd dimension. Default value is 1.
5966 When set to 1, no block matching is done. Larger values allows more blocks
5968 Allowed range is from 1 to 256.
5971 Set radius for search block matching. Default is 9.
5972 Allowed range is from 1 to INT32_MAX.
5975 Set step between two search locations for block matching. Default is 1.
5976 Allowed range is from 1 to 64. Smaller is slower.
5979 Set threshold of mean square error for block matching. Valid range is 0 to
5983 Set thresholding parameter for hard thresholding in 3D transformed domain.
5984 Larger values results in stronger hard-thresholding filtering in frequency
5988 Set filtering estimation mode. Can be @code{basic} or @code{final}.
5989 Default is @code{basic}.
5992 If enabled, filter will use 2nd stream for block matching.
5993 Default is disabled for @code{basic} value of @var{estim} option,
5994 and always enabled if value of @var{estim} is @code{final}.
5997 Set planes to filter. Default is all available except alpha.
6000 @subsection Examples
6004 Basic filtering with bm3d:
6006 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
6010 Same as above, but filtering only luma:
6012 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
6016 Same as above, but with both estimation modes:
6018 split[a][b],[a]bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
6022 Same as above, but prefilter with @ref{nlmeans} filter instead:
6024 split[a][b],[a]nlmeans=s=3:r=7:p=3[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
6030 Apply a boxblur algorithm to the input video.
6032 It accepts the following parameters:
6036 @item luma_radius, lr
6037 @item luma_power, lp
6038 @item chroma_radius, cr
6039 @item chroma_power, cp
6040 @item alpha_radius, ar
6041 @item alpha_power, ap
6045 A description of the accepted options follows.
6048 @item luma_radius, lr
6049 @item chroma_radius, cr
6050 @item alpha_radius, ar
6051 Set an expression for the box radius in pixels used for blurring the
6052 corresponding input plane.
6054 The radius value must be a non-negative number, and must not be
6055 greater than the value of the expression @code{min(w,h)/2} for the
6056 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
6059 Default value for @option{luma_radius} is "2". If not specified,
6060 @option{chroma_radius} and @option{alpha_radius} default to the
6061 corresponding value set for @option{luma_radius}.
6063 The expressions can contain the following constants:
6067 The input width and height in pixels.
6071 The input chroma image width and height in pixels.
6075 The horizontal and vertical chroma subsample values. For example, for the
6076 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
6079 @item luma_power, lp
6080 @item chroma_power, cp
6081 @item alpha_power, ap
6082 Specify how many times the boxblur filter is applied to the
6083 corresponding plane.
6085 Default value for @option{luma_power} is 2. If not specified,
6086 @option{chroma_power} and @option{alpha_power} default to the
6087 corresponding value set for @option{luma_power}.
6089 A value of 0 will disable the effect.
6092 @subsection Examples
6096 Apply a boxblur filter with the luma, chroma, and alpha radii
6099 boxblur=luma_radius=2:luma_power=1
6104 Set the luma radius to 2, and alpha and chroma radius to 0:
6106 boxblur=2:1:cr=0:ar=0
6110 Set the luma and chroma radii to a fraction of the video dimension:
6112 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
6118 Deinterlace the input video ("bwdif" stands for "Bob Weaver
6119 Deinterlacing Filter").
6121 Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
6122 interpolation algorithms.
6123 It accepts the following parameters:
6127 The interlacing mode to adopt. It accepts one of the following values:
6131 Output one frame for each frame.
6133 Output one frame for each field.
6136 The default value is @code{send_field}.
6139 The picture field parity assumed for the input interlaced video. It accepts one
6140 of the following values:
6144 Assume the top field is first.
6146 Assume the bottom field is first.
6148 Enable automatic detection of field parity.
6151 The default value is @code{auto}.
6152 If the interlacing is unknown or the decoder does not export this information,
6153 top field first will be assumed.
6156 Specify which frames to deinterlace. Accept one of the following
6161 Deinterlace all frames.
6163 Only deinterlace frames marked as interlaced.
6166 The default value is @code{all}.
6170 Remove all color information for all colors except for certain one.
6172 The filter accepts the following options:
6176 The color which will not be replaced with neutral chroma.
6179 Similarity percentage with the above color.
6180 0.01 matches only the exact key color, while 1.0 matches everything.
6183 Signals that the color passed is already in YUV instead of RGB.
6185 Literal colors like "green" or "red" don't make sense with this enabled anymore.
6186 This can be used to pass exact YUV values as hexadecimal numbers.
6190 YUV colorspace color/chroma keying.
6192 The filter accepts the following options:
6196 The color which will be replaced with transparency.
6199 Similarity percentage with the key color.
6201 0.01 matches only the exact key color, while 1.0 matches everything.
6206 0.0 makes pixels either fully transparent, or not transparent at all.
6208 Higher values result in semi-transparent pixels, with a higher transparency
6209 the more similar the pixels color is to the key color.
6212 Signals that the color passed is already in YUV instead of RGB.
6214 Literal colors like "green" or "red" don't make sense with this enabled anymore.
6215 This can be used to pass exact YUV values as hexadecimal numbers.
6218 @subsection Examples
6222 Make every green pixel in the input image transparent:
6224 ffmpeg -i input.png -vf chromakey=green out.png
6228 Overlay a greenscreen-video on top of a static black background.
6230 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
6236 Display CIE color diagram with pixels overlaid onto it.
6238 The filter accepts the following options:
6253 @item uhdtv, rec2020
6266 Set what gamuts to draw.
6268 See @code{system} option for available values.
6271 Set ciescope size, by default set to 512.
6274 Set intensity used to map input pixel values to CIE diagram.
6277 Set contrast used to draw tongue colors that are out of active color system gamut.
6280 Correct gamma displayed on scope, by default enabled.
6283 Show white point on CIE diagram, by default disabled.
6286 Set input gamma. Used only with XYZ input color space.
6291 Visualize information exported by some codecs.
6293 Some codecs can export information through frames using side-data or other
6294 means. For example, some MPEG based codecs export motion vectors through the
6295 @var{export_mvs} flag in the codec @option{flags2} option.
6297 The filter accepts the following option:
6301 Set motion vectors to visualize.
6303 Available flags for @var{mv} are:
6307 forward predicted MVs of P-frames
6309 forward predicted MVs of B-frames
6311 backward predicted MVs of B-frames
6315 Display quantization parameters using the chroma planes.
6318 Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
6320 Available flags for @var{mv_type} are:
6324 forward predicted MVs
6326 backward predicted MVs
6329 @item frame_type, ft
6330 Set frame type to visualize motion vectors of.
6332 Available flags for @var{frame_type} are:
6336 intra-coded frames (I-frames)
6338 predicted frames (P-frames)
6340 bi-directionally predicted frames (B-frames)
6344 @subsection Examples
6348 Visualize forward predicted MVs of all frames using @command{ffplay}:
6350 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
6354 Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
6356 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
6360 @section colorbalance
6361 Modify intensity of primary colors (red, green and blue) of input frames.
6363 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
6364 regions for the red-cyan, green-magenta or blue-yellow balance.
6366 A positive adjustment value shifts the balance towards the primary color, a negative
6367 value towards the complementary color.
6369 The filter accepts the following options:
6375 Adjust red, green and blue shadows (darkest pixels).
6380 Adjust red, green and blue midtones (medium pixels).
6385 Adjust red, green and blue highlights (brightest pixels).
6387 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
6390 @subsection Examples
6394 Add red color cast to shadows:
6401 RGB colorspace color keying.
6403 The filter accepts the following options:
6407 The color which will be replaced with transparency.
6410 Similarity percentage with the key color.
6412 0.01 matches only the exact key color, while 1.0 matches everything.
6417 0.0 makes pixels either fully transparent, or not transparent at all.
6419 Higher values result in semi-transparent pixels, with a higher transparency
6420 the more similar the pixels color is to the key color.
6423 @subsection Examples
6427 Make every green pixel in the input image transparent:
6429 ffmpeg -i input.png -vf colorkey=green out.png
6433 Overlay a greenscreen-video on top of a static background image.
6435 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
6439 @section colorlevels
6441 Adjust video input frames using levels.
6443 The filter accepts the following options:
6450 Adjust red, green, blue and alpha input black point.
6451 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
6457 Adjust red, green, blue and alpha input white point.
6458 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
6460 Input levels are used to lighten highlights (bright tones), darken shadows
6461 (dark tones), change the balance of bright and dark tones.
6467 Adjust red, green, blue and alpha output black point.
6468 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
6474 Adjust red, green, blue and alpha output white point.
6475 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
6477 Output levels allows manual selection of a constrained output level range.
6480 @subsection Examples
6484 Make video output darker:
6486 colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
6492 colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
6496 Make video output lighter:
6498 colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
6502 Increase brightness:
6504 colorlevels=romin=0.5:gomin=0.5:bomin=0.5
6508 @section colorchannelmixer
6510 Adjust video input frames by re-mixing color channels.
6512 This filter modifies a color channel by adding the values associated to
6513 the other channels of the same pixels. For example if the value to
6514 modify is red, the output value will be:
6516 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
6519 The filter accepts the following options:
6526 Adjust contribution of input red, green, blue and alpha channels for output red channel.
6527 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
6533 Adjust contribution of input red, green, blue and alpha channels for output green channel.
6534 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
6540 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
6541 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
6547 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
6548 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
6550 Allowed ranges for options are @code{[-2.0, 2.0]}.
6553 @subsection Examples
6557 Convert source to grayscale:
6559 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
6562 Simulate sepia tones:
6564 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
6568 @section colormatrix
6570 Convert color matrix.
6572 The filter accepts the following options:
6577 Specify the source and destination color matrix. Both values must be
6580 The accepted values are:
6608 For example to convert from BT.601 to SMPTE-240M, use the command:
6610 colormatrix=bt601:smpte240m
6615 Convert colorspace, transfer characteristics or color primaries.
6616 Input video needs to have an even size.
6618 The filter accepts the following options:
6623 Specify all color properties at once.
6625 The accepted values are:
6655 Specify output colorspace.
6657 The accepted values are:
6666 BT.470BG or BT.601-6 625
6669 SMPTE-170M or BT.601-6 525
6678 BT.2020 with non-constant luminance
6684 Specify output transfer characteristics.
6686 The accepted values are:
6698 Constant gamma of 2.2
6701 Constant gamma of 2.8
6704 SMPTE-170M, BT.601-6 625 or BT.601-6 525
6722 BT.2020 for 10-bits content
6725 BT.2020 for 12-bits content
6731 Specify output color primaries.
6733 The accepted values are:
6742 BT.470BG or BT.601-6 625
6745 SMPTE-170M or BT.601-6 525
6769 Specify output color range.
6771 The accepted values are:
6774 TV (restricted) range
6777 MPEG (restricted) range
6788 Specify output color format.
6790 The accepted values are:
6793 YUV 4:2:0 planar 8-bits
6796 YUV 4:2:0 planar 10-bits
6799 YUV 4:2:0 planar 12-bits
6802 YUV 4:2:2 planar 8-bits
6805 YUV 4:2:2 planar 10-bits
6808 YUV 4:2:2 planar 12-bits
6811 YUV 4:4:4 planar 8-bits
6814 YUV 4:4:4 planar 10-bits
6817 YUV 4:4:4 planar 12-bits
6822 Do a fast conversion, which skips gamma/primary correction. This will take
6823 significantly less CPU, but will be mathematically incorrect. To get output
6824 compatible with that produced by the colormatrix filter, use fast=1.
6827 Specify dithering mode.
6829 The accepted values are:
6835 Floyd-Steinberg dithering
6839 Whitepoint adaptation mode.
6841 The accepted values are:
6844 Bradford whitepoint adaptation
6847 von Kries whitepoint adaptation
6850 identity whitepoint adaptation (i.e. no whitepoint adaptation)
6854 Override all input properties at once. Same accepted values as @ref{all}.
6857 Override input colorspace. Same accepted values as @ref{space}.
6860 Override input color primaries. Same accepted values as @ref{primaries}.
6863 Override input transfer characteristics. Same accepted values as @ref{trc}.
6866 Override input color range. Same accepted values as @ref{range}.
6870 The filter converts the transfer characteristics, color space and color
6871 primaries to the specified user values. The output value, if not specified,
6872 is set to a default value based on the "all" property. If that property is
6873 also not specified, the filter will log an error. The output color range and
6874 format default to the same value as the input color range and format. The
6875 input transfer characteristics, color space, color primaries and color range
6876 should be set on the input data. If any of these are missing, the filter will
6877 log an error and no conversion will take place.
6879 For example to convert the input to SMPTE-240M, use the command:
6881 colorspace=smpte240m
6884 @section convolution
6886 Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
6888 The filter accepts the following options:
6895 Set matrix for each plane.
6896 Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode,
6897 and from 1 to 49 odd number of signed integers in @var{row} mode.
6903 Set multiplier for calculated value for each plane.
6904 If unset or 0, it will be sum of all matrix elements.
6910 Set bias for each plane. This value is added to the result of the multiplication.
6911 Useful for making the overall image brighter or darker. Default is 0.0.
6917 Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}.
6918 Default is @var{square}.
6921 @subsection Examples
6927 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"
6933 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"
6939 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"
6945 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"
6949 Apply laplacian edge detector which includes diagonals:
6951 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"
6957 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"
6963 Apply 2D convolution of video stream in frequency domain using second stream
6966 The filter accepts the following options:
6970 Set which planes to process.
6973 Set which impulse video frames will be processed, can be @var{first}
6974 or @var{all}. Default is @var{all}.
6977 The @code{convolve} filter also supports the @ref{framesync} options.
6981 Copy the input video source unchanged to the output. This is mainly useful for
6986 Video filtering on GPU using Apple's CoreImage API on OSX.
6988 Hardware acceleration is based on an OpenGL context. Usually, this means it is
6989 processed by video hardware. However, software-based OpenGL implementations
6990 exist which means there is no guarantee for hardware processing. It depends on
6993 There are many filters and image generators provided by Apple that come with a
6994 large variety of options. The filter has to be referenced by its name along
6997 The coreimage filter accepts the following options:
7000 List all available filters and generators along with all their respective
7001 options as well as possible minimum and maximum values along with the default
7008 Specify all filters by their respective name and options.
7009 Use @var{list_filters} to determine all valid filter names and options.
7010 Numerical options are specified by a float value and are automatically clamped
7011 to their respective value range. Vector and color options have to be specified
7012 by a list of space separated float values. Character escaping has to be done.
7013 A special option name @code{default} is available to use default options for a
7016 It is required to specify either @code{default} or at least one of the filter options.
7017 All omitted options are used with their default values.
7018 The syntax of the filter string is as follows:
7020 filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
7024 Specify a rectangle where the output of the filter chain is copied into the
7025 input image. It is given by a list of space separated float values:
7027 output_rect=x\ y\ width\ height
7029 If not given, the output rectangle equals the dimensions of the input image.
7030 The output rectangle is automatically cropped at the borders of the input
7031 image. Negative values are valid for each component.
7033 output_rect=25\ 25\ 100\ 100
7037 Several filters can be chained for successive processing without GPU-HOST
7038 transfers allowing for fast processing of complex filter chains.
7039 Currently, only filters with zero (generators) or exactly one (filters) input
7040 image and one output image are supported. Also, transition filters are not yet
7043 Some filters generate output images with additional padding depending on the
7044 respective filter kernel. The padding is automatically removed to ensure the
7045 filter output has the same size as the input image.
7047 For image generators, the size of the output image is determined by the
7048 previous output image of the filter chain or the input image of the whole
7049 filterchain, respectively. The generators do not use the pixel information of
7050 this image to generate their output. However, the generated output is
7051 blended onto this image, resulting in partial or complete coverage of the
7054 The @ref{coreimagesrc} video source can be used for generating input images
7055 which are directly fed into the filter chain. By using it, providing input
7056 images by another video source or an input video is not required.
7058 @subsection Examples
7063 List all filters available:
7065 coreimage=list_filters=true
7069 Use the CIBoxBlur filter with default options to blur an image:
7071 coreimage=filter=CIBoxBlur@@default
7075 Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
7076 its center at 100x100 and a radius of 50 pixels:
7078 coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
7082 Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
7083 given as complete and escaped command-line for Apple's standard bash shell:
7085 ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
7091 Crop the input video to given dimensions.
7093 It accepts the following parameters:
7097 The width of the output video. It defaults to @code{iw}.
7098 This expression is evaluated only once during the filter
7099 configuration, or when the @samp{w} or @samp{out_w} command is sent.
7102 The height of the output video. It defaults to @code{ih}.
7103 This expression is evaluated only once during the filter
7104 configuration, or when the @samp{h} or @samp{out_h} command is sent.
7107 The horizontal position, in the input video, of the left edge of the output
7108 video. It defaults to @code{(in_w-out_w)/2}.
7109 This expression is evaluated per-frame.
7112 The vertical position, in the input video, of the top edge of the output video.
7113 It defaults to @code{(in_h-out_h)/2}.
7114 This expression is evaluated per-frame.
7117 If set to 1 will force the output display aspect ratio
7118 to be the same of the input, by changing the output sample aspect
7119 ratio. It defaults to 0.
7122 Enable exact cropping. If enabled, subsampled videos will be cropped at exact
7123 width/height/x/y as specified and will not be rounded to nearest smaller value.
7127 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
7128 expressions containing the following constants:
7133 The computed values for @var{x} and @var{y}. They are evaluated for
7138 The input width and height.
7142 These are the same as @var{in_w} and @var{in_h}.
7146 The output (cropped) width and height.
7150 These are the same as @var{out_w} and @var{out_h}.
7153 same as @var{iw} / @var{ih}
7156 input sample aspect ratio
7159 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
7163 horizontal and vertical chroma subsample values. For example for the
7164 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
7167 The number of the input frame, starting from 0.
7170 the position in the file of the input frame, NAN if unknown
7173 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
7177 The expression for @var{out_w} may depend on the value of @var{out_h},
7178 and the expression for @var{out_h} may depend on @var{out_w}, but they
7179 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
7180 evaluated after @var{out_w} and @var{out_h}.
7182 The @var{x} and @var{y} parameters specify the expressions for the
7183 position of the top-left corner of the output (non-cropped) area. They
7184 are evaluated for each frame. If the evaluated value is not valid, it
7185 is approximated to the nearest valid value.
7187 The expression for @var{x} may depend on @var{y}, and the expression
7188 for @var{y} may depend on @var{x}.
7190 @subsection Examples
7194 Crop area with size 100x100 at position (12,34).
7199 Using named options, the example above becomes:
7201 crop=w=100:h=100:x=12:y=34
7205 Crop the central input area with size 100x100:
7211 Crop the central input area with size 2/3 of the input video:
7213 crop=2/3*in_w:2/3*in_h
7217 Crop the input video central square:
7224 Delimit the rectangle with the top-left corner placed at position
7225 100:100 and the right-bottom corner corresponding to the right-bottom
7226 corner of the input image.
7228 crop=in_w-100:in_h-100:100:100
7232 Crop 10 pixels from the left and right borders, and 20 pixels from
7233 the top and bottom borders
7235 crop=in_w-2*10:in_h-2*20
7239 Keep only the bottom right quarter of the input image:
7241 crop=in_w/2:in_h/2:in_w/2:in_h/2
7245 Crop height for getting Greek harmony:
7247 crop=in_w:1/PHI*in_w
7251 Apply trembling effect:
7253 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)
7257 Apply erratic camera effect depending on timestamp:
7259 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)"
7263 Set x depending on the value of y:
7265 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
7269 @subsection Commands
7271 This filter supports the following commands:
7277 Set width/height of the output video and the horizontal/vertical position
7279 The command accepts the same syntax of the corresponding option.
7281 If the specified expression is not valid, it is kept at its current
7287 Auto-detect the crop size.
7289 It calculates the necessary cropping parameters and prints the
7290 recommended parameters via the logging system. The detected dimensions
7291 correspond to the non-black area of the input video.
7293 It accepts the following parameters:
7298 Set higher black value threshold, which can be optionally specified
7299 from nothing (0) to everything (255 for 8-bit based formats). An intensity
7300 value greater to the set value is considered non-black. It defaults to 24.
7301 You can also specify a value between 0.0 and 1.0 which will be scaled depending
7302 on the bitdepth of the pixel format.
7305 The value which the width/height should be divisible by. It defaults to
7306 16. The offset is automatically adjusted to center the video. Use 2 to
7307 get only even dimensions (needed for 4:2:2 video). 16 is best when
7308 encoding to most video codecs.
7310 @item reset_count, reset
7311 Set the counter that determines after how many frames cropdetect will
7312 reset the previously detected largest video area and start over to
7313 detect the current optimal crop area. Default value is 0.
7315 This can be useful when channel logos distort the video area. 0
7316 indicates 'never reset', and returns the largest area encountered during
7323 Delay video filtering until a given wallclock timestamp. The filter first
7324 passes on @option{preroll} amount of frames, then it buffers at most
7325 @option{buffer} amount of frames and waits for the cue. After reaching the cue
7326 it forwards the buffered frames and also any subsequent frames coming in its
7329 The filter can be used synchronize the output of multiple ffmpeg processes for
7330 realtime output devices like decklink. By putting the delay in the filtering
7331 chain and pre-buffering frames the process can pass on data to output almost
7332 immediately after the target wallclock timestamp is reached.
7334 Perfect frame accuracy cannot be guaranteed, but the result is good enough for
7340 The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0.
7343 The duration of content to pass on as preroll expressed in seconds. Default is 0.
7346 The maximum duration of content to buffer before waiting for the cue expressed
7347 in seconds. Default is 0.
7354 Apply color adjustments using curves.
7356 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
7357 component (red, green and blue) has its values defined by @var{N} key points
7358 tied from each other using a smooth curve. The x-axis represents the pixel
7359 values from the input frame, and the y-axis the new pixel values to be set for
7362 By default, a component curve is defined by the two points @var{(0;0)} and
7363 @var{(1;1)}. This creates a straight line where each original pixel value is
7364 "adjusted" to its own value, which means no change to the image.
7366 The filter allows you to redefine these two points and add some more. A new
7367 curve (using a natural cubic spline interpolation) will be define to pass
7368 smoothly through all these new coordinates. The new defined points needs to be
7369 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
7370 be in the @var{[0;1]} interval. If the computed curves happened to go outside
7371 the vector spaces, the values will be clipped accordingly.
7373 The filter accepts the following options:
7377 Select one of the available color presets. This option can be used in addition
7378 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
7379 options takes priority on the preset values.
7380 Available presets are:
7383 @item color_negative
7386 @item increase_contrast
7388 @item linear_contrast
7389 @item medium_contrast
7391 @item strong_contrast
7394 Default is @code{none}.
7396 Set the master key points. These points will define a second pass mapping. It
7397 is sometimes called a "luminance" or "value" mapping. It can be used with
7398 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
7399 post-processing LUT.
7401 Set the key points for the red component.
7403 Set the key points for the green component.
7405 Set the key points for the blue component.
7407 Set the key points for all components (not including master).
7408 Can be used in addition to the other key points component
7409 options. In this case, the unset component(s) will fallback on this
7410 @option{all} setting.
7412 Specify a Photoshop curves file (@code{.acv}) to import the settings from.
7414 Save Gnuplot script of the curves in specified file.
7417 To avoid some filtergraph syntax conflicts, each key points list need to be
7418 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
7420 @subsection Examples
7424 Increase slightly the middle level of blue:
7426 curves=blue='0/0 0.5/0.58 1/1'
7432 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'
7434 Here we obtain the following coordinates for each components:
7437 @code{(0;0.11) (0.42;0.51) (1;0.95)}
7439 @code{(0;0) (0.50;0.48) (1;1)}
7441 @code{(0;0.22) (0.49;0.44) (1;0.80)}
7445 The previous example can also be achieved with the associated built-in preset:
7447 curves=preset=vintage
7457 Use a Photoshop preset and redefine the points of the green component:
7459 curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
7463 Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
7464 and @command{gnuplot}:
7466 ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
7467 gnuplot -p /tmp/curves.plt
7473 Video data analysis filter.
7475 This filter shows hexadecimal pixel values of part of video.
7477 The filter accepts the following options:
7481 Set output video size.
7484 Set x offset from where to pick pixels.
7487 Set y offset from where to pick pixels.
7490 Set scope mode, can be one of the following:
7493 Draw hexadecimal pixel values with white color on black background.
7496 Draw hexadecimal pixel values with input video pixel color on black
7500 Draw hexadecimal pixel values on color background picked from input video,
7501 the text color is picked in such way so its always visible.
7505 Draw rows and columns numbers on left and top of video.
7508 Set background opacity.
7513 Denoise frames using 2D DCT (frequency domain filtering).
7515 This filter is not designed for real time.
7517 The filter accepts the following options:
7521 Set the noise sigma constant.
7523 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
7524 coefficient (absolute value) below this threshold with be dropped.
7526 If you need a more advanced filtering, see @option{expr}.
7528 Default is @code{0}.
7531 Set number overlapping pixels for each block. Since the filter can be slow, you
7532 may want to reduce this value, at the cost of a less effective filter and the
7533 risk of various artefacts.
7535 If the overlapping value doesn't permit processing the whole input width or
7536 height, a warning will be displayed and according borders won't be denoised.
7538 Default value is @var{blocksize}-1, which is the best possible setting.
7541 Set the coefficient factor expression.
7543 For each coefficient of a DCT block, this expression will be evaluated as a
7544 multiplier value for the coefficient.
7546 If this is option is set, the @option{sigma} option will be ignored.
7548 The absolute value of the coefficient can be accessed through the @var{c}
7552 Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
7553 @var{blocksize}, which is the width and height of the processed blocks.
7555 The default value is @var{3} (8x8) and can be raised to @var{4} for a
7556 @var{blocksize} of 16x16. Note that changing this setting has huge consequences
7557 on the speed processing. Also, a larger block size does not necessarily means a
7561 @subsection Examples
7563 Apply a denoise with a @option{sigma} of @code{4.5}:
7568 The same operation can be achieved using the expression system:
7570 dctdnoiz=e='gte(c, 4.5*3)'
7573 Violent denoise using a block size of @code{16x16}:
7580 Remove banding artifacts from input video.
7581 It works by replacing banded pixels with average value of referenced pixels.
7583 The filter accepts the following options:
7590 Set banding detection threshold for each plane. Default is 0.02.
7591 Valid range is 0.00003 to 0.5.
7592 If difference between current pixel and reference pixel is less than threshold,
7593 it will be considered as banded.
7596 Banding detection range in pixels. Default is 16. If positive, random number
7597 in range 0 to set value will be used. If negative, exact absolute value
7599 The range defines square of four pixels around current pixel.
7602 Set direction in radians from which four pixel will be compared. If positive,
7603 random direction from 0 to set direction will be picked. If negative, exact of
7604 absolute value will be picked. For example direction 0, -PI or -2*PI radians
7605 will pick only pixels on same row and -PI/2 will pick only pixels on same
7609 If enabled, current pixel is compared with average value of all four
7610 surrounding pixels. The default is enabled. If disabled current pixel is
7611 compared with all four surrounding pixels. The pixel is considered banded
7612 if only all four differences with surrounding pixels are less than threshold.
7615 If enabled, current pixel is changed if and only if all pixel components are banded,
7616 e.g. banding detection threshold is triggered for all color components.
7617 The default is disabled.
7622 Remove blocking artifacts from input video.
7624 The filter accepts the following options:
7628 Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}.
7629 This controls what kind of deblocking is applied.
7632 Set size of block, allowed range is from 4 to 512. Default is @var{8}.
7638 Set blocking detection thresholds. Allowed range is 0 to 1.
7639 Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest.
7640 Using higher threshold gives more deblocking strength.
7641 Setting @var{alpha} controls threshold detection at exact edge of block.
7642 Remaining options controls threshold detection near the edge. Each one for
7643 below/above or left/right. Setting any of those to @var{0} disables
7647 Set planes to filter. Default is to filter all available planes.
7650 @subsection Examples
7654 Deblock using weak filter and block size of 4 pixels.
7656 deblock=filter=weak:block=4
7660 Deblock using strong filter, block size of 4 pixels and custom thresholds for
7661 deblocking more edges.
7663 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
7667 Similar as above, but filter only first plane.
7669 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
7673 Similar as above, but filter only second and third plane.
7675 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
7682 Drop duplicated frames at regular intervals.
7684 The filter accepts the following options:
7688 Set the number of frames from which one will be dropped. Setting this to
7689 @var{N} means one frame in every batch of @var{N} frames will be dropped.
7690 Default is @code{5}.
7693 Set the threshold for duplicate detection. If the difference metric for a frame
7694 is less than or equal to this value, then it is declared as duplicate. Default
7698 Set scene change threshold. Default is @code{15}.
7702 Set the size of the x and y-axis blocks used during metric calculations.
7703 Larger blocks give better noise suppression, but also give worse detection of
7704 small movements. Must be a power of two. Default is @code{32}.
7707 Mark main input as a pre-processed input and activate clean source input
7708 stream. This allows the input to be pre-processed with various filters to help
7709 the metrics calculation while keeping the frame selection lossless. When set to
7710 @code{1}, the first stream is for the pre-processed input, and the second
7711 stream is the clean source from where the kept frames are chosen. Default is
7715 Set whether or not chroma is considered in the metric calculations. Default is
7721 Apply 2D deconvolution of video stream in frequency domain using second stream
7724 The filter accepts the following options:
7728 Set which planes to process.
7731 Set which impulse video frames will be processed, can be @var{first}
7732 or @var{all}. Default is @var{all}.
7735 Set noise when doing divisions. Default is @var{0.0000001}. Useful when width
7736 and height are not same and not power of 2 or if stream prior to convolving
7740 The @code{deconvolve} filter also supports the @ref{framesync} options.
7744 Apply deflate effect to the video.
7746 This filter replaces the pixel by the local(3x3) average by taking into account
7747 only values lower than the pixel.
7749 It accepts the following options:
7756 Limit the maximum change for each plane, default is 65535.
7757 If 0, plane will remain unchanged.
7762 Remove temporal frame luminance variations.
7764 It accepts the following options:
7768 Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129.
7771 Set averaging mode to smooth temporal luminance variations.
7773 Available values are:
7798 Do not actually modify frame. Useful when one only wants metadata.
7803 Remove judder produced by partially interlaced telecined content.
7805 Judder can be introduced, for instance, by @ref{pullup} filter. If the original
7806 source was partially telecined content then the output of @code{pullup,dejudder}
7807 will have a variable frame rate. May change the recorded frame rate of the
7808 container. Aside from that change, this filter will not affect constant frame
7811 The option available in this filter is:
7815 Specify the length of the window over which the judder repeats.
7817 Accepts any integer greater than 1. Useful values are:
7821 If the original was telecined from 24 to 30 fps (Film to NTSC).
7824 If the original was telecined from 25 to 30 fps (PAL to NTSC).
7827 If a mixture of the two.
7830 The default is @samp{4}.
7835 Suppress a TV station logo by a simple interpolation of the surrounding
7836 pixels. Just set a rectangle covering the logo and watch it disappear
7837 (and sometimes something even uglier appear - your mileage may vary).
7839 It accepts the following parameters:
7844 Specify the top left corner coordinates of the logo. They must be
7849 Specify the width and height of the logo to clear. They must be
7853 Specify the thickness of the fuzzy edge of the rectangle (added to
7854 @var{w} and @var{h}). The default value is 1. This option is
7855 deprecated, setting higher values should no longer be necessary and
7859 When set to 1, a green rectangle is drawn on the screen to simplify
7860 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
7861 The default value is 0.
7863 The rectangle is drawn on the outermost pixels which will be (partly)
7864 replaced with interpolated values. The values of the next pixels
7865 immediately outside this rectangle in each direction will be used to
7866 compute the interpolated pixel values inside the rectangle.
7870 @subsection Examples
7874 Set a rectangle covering the area with top left corner coordinates 0,0
7875 and size 100x77, and a band of size 10:
7877 delogo=x=0:y=0:w=100:h=77:band=10
7884 Attempt to fix small changes in horizontal and/or vertical shift. This
7885 filter helps remove camera shake from hand-holding a camera, bumping a
7886 tripod, moving on a vehicle, etc.
7888 The filter accepts the following options:
7896 Specify a rectangular area where to limit the search for motion
7898 If desired the search for motion vectors can be limited to a
7899 rectangular area of the frame defined by its top left corner, width
7900 and height. These parameters have the same meaning as the drawbox
7901 filter which can be used to visualise the position of the bounding
7904 This is useful when simultaneous movement of subjects within the frame
7905 might be confused for camera motion by the motion vector search.
7907 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
7908 then the full frame is used. This allows later options to be set
7909 without specifying the bounding box for the motion vector search.
7911 Default - search the whole frame.
7915 Specify the maximum extent of movement in x and y directions in the
7916 range 0-64 pixels. Default 16.
7919 Specify how to generate pixels to fill blanks at the edge of the
7920 frame. Available values are:
7923 Fill zeroes at blank locations
7925 Original image at blank locations
7927 Extruded edge value at blank locations
7929 Mirrored edge at blank locations
7931 Default value is @samp{mirror}.
7934 Specify the blocksize to use for motion search. Range 4-128 pixels,
7938 Specify the contrast threshold for blocks. Only blocks with more than
7939 the specified contrast (difference between darkest and lightest
7940 pixels) will be considered. Range 1-255, default 125.
7943 Specify the search strategy. Available values are:
7946 Set exhaustive search
7948 Set less exhaustive search.
7950 Default value is @samp{exhaustive}.
7953 If set then a detailed log of the motion search is written to the
7960 Remove unwanted contamination of foreground colors, caused by reflected color of
7961 greenscreen or bluescreen.
7963 This filter accepts the following options:
7967 Set what type of despill to use.
7970 Set how spillmap will be generated.
7973 Set how much to get rid of still remaining spill.
7976 Controls amount of red in spill area.
7979 Controls amount of green in spill area.
7980 Should be -1 for greenscreen.
7983 Controls amount of blue in spill area.
7984 Should be -1 for bluescreen.
7987 Controls brightness of spill area, preserving colors.
7990 Modify alpha from generated spillmap.
7995 Apply an exact inverse of the telecine operation. It requires a predefined
7996 pattern specified using the pattern option which must be the same as that passed
7997 to the telecine filter.
7999 This filter accepts the following options:
8008 The default value is @code{top}.
8012 A string of numbers representing the pulldown pattern you wish to apply.
8013 The default value is @code{23}.
8016 A number representing position of the first frame with respect to the telecine
8017 pattern. This is to be used if the stream is cut. The default value is @code{0}.
8022 Apply dilation effect to the video.
8024 This filter replaces the pixel by the local(3x3) maximum.
8026 It accepts the following options:
8033 Limit the maximum change for each plane, default is 65535.
8034 If 0, plane will remain unchanged.
8037 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
8040 Flags to local 3x3 coordinates maps like this:
8049 Displace pixels as indicated by second and third input stream.
8051 It takes three input streams and outputs one stream, the first input is the
8052 source, and second and third input are displacement maps.
8054 The second input specifies how much to displace pixels along the
8055 x-axis, while the third input specifies how much to displace pixels
8057 If one of displacement map streams terminates, last frame from that
8058 displacement map will be used.
8060 Note that once generated, displacements maps can be reused over and over again.
8062 A description of the accepted options follows.
8066 Set displace behavior for pixels that are out of range.
8068 Available values are:
8071 Missing pixels are replaced by black pixels.
8074 Adjacent pixels will spread out to replace missing pixels.
8077 Out of range pixels are wrapped so they point to pixels of other side.
8080 Out of range pixels will be replaced with mirrored pixels.
8082 Default is @samp{smear}.
8086 @subsection Examples
8090 Add ripple effect to rgb input of video size hd720:
8092 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
8096 Add wave effect to rgb input of video size hd720:
8098 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
8104 Draw a colored box on the input image.
8106 It accepts the following parameters:
8111 The expressions which specify the top left corner coordinates of the box. It defaults to 0.
8115 The expressions which specify the width and height of the box; if 0 they are interpreted as
8116 the input width and height. It defaults to 0.
8119 Specify the color of the box to write. For the general syntax of this option,
8120 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
8121 value @code{invert} is used, the box edge color is the same as the
8122 video with inverted luma.
8125 The expression which sets the thickness of the box edge.
8126 A value of @code{fill} will create a filled box. Default value is @code{3}.
8128 See below for the list of accepted constants.
8131 Applicable if the input has alpha. With value @code{1}, the pixels of the painted box
8132 will overwrite the video's color and alpha pixels.
8133 Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact.
8136 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
8137 following constants:
8141 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
8145 horizontal and vertical chroma subsample values. For example for the
8146 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8150 The input width and height.
8153 The input sample aspect ratio.
8157 The x and y offset coordinates where the box is drawn.
8161 The width and height of the drawn box.
8164 The thickness of the drawn box.
8166 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
8167 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
8171 @subsection Examples
8175 Draw a black box around the edge of the input image:
8181 Draw a box with color red and an opacity of 50%:
8183 drawbox=10:20:200:60:red@@0.5
8186 The previous example can be specified as:
8188 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
8192 Fill the box with pink color:
8194 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill
8198 Draw a 2-pixel red 2.40:1 mask:
8200 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
8206 Draw a grid on the input image.
8208 It accepts the following parameters:
8213 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
8217 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
8218 input width and height, respectively, minus @code{thickness}, so image gets
8219 framed. Default to 0.
8222 Specify the color of the grid. For the general syntax of this option,
8223 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
8224 value @code{invert} is used, the grid color is the same as the
8225 video with inverted luma.
8228 The expression which sets the thickness of the grid line. Default value is @code{1}.
8230 See below for the list of accepted constants.
8233 Applicable if the input has alpha. With @code{1} the pixels of the painted grid
8234 will overwrite the video's color and alpha pixels.
8235 Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact.
8238 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
8239 following constants:
8243 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
8247 horizontal and vertical chroma subsample values. For example for the
8248 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8252 The input grid cell width and height.
8255 The input sample aspect ratio.
8259 The x and y coordinates of some point of grid intersection (meant to configure offset).
8263 The width and height of the drawn cell.
8266 The thickness of the drawn cell.
8268 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
8269 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
8273 @subsection Examples
8277 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
8279 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
8283 Draw a white 3x3 grid with an opacity of 50%:
8285 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
8292 Draw a text string or text from a specified file on top of a video, using the
8293 libfreetype library.
8295 To enable compilation of this filter, you need to configure FFmpeg with
8296 @code{--enable-libfreetype}.
8297 To enable default font fallback and the @var{font} option you need to
8298 configure FFmpeg with @code{--enable-libfontconfig}.
8299 To enable the @var{text_shaping} option, you need to configure FFmpeg with
8300 @code{--enable-libfribidi}.
8304 It accepts the following parameters:
8309 Used to draw a box around text using the background color.
8310 The value must be either 1 (enable) or 0 (disable).
8311 The default value of @var{box} is 0.
8314 Set the width of the border to be drawn around the box using @var{boxcolor}.
8315 The default value of @var{boxborderw} is 0.
8318 The color to be used for drawing box around text. For the syntax of this
8319 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
8321 The default value of @var{boxcolor} is "white".
8324 Set the line spacing in pixels of the border to be drawn around the box using @var{box}.
8325 The default value of @var{line_spacing} is 0.
8328 Set the width of the border to be drawn around the text using @var{bordercolor}.
8329 The default value of @var{borderw} is 0.
8332 Set the color to be used for drawing border around text. For the syntax of this
8333 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
8335 The default value of @var{bordercolor} is "black".
8338 Select how the @var{text} is expanded. Can be either @code{none},
8339 @code{strftime} (deprecated) or
8340 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
8344 Set a start time for the count. Value is in microseconds. Only applied
8345 in the deprecated strftime expansion mode. To emulate in normal expansion
8346 mode use the @code{pts} function, supplying the start time (in seconds)
8347 as the second argument.
8350 If true, check and fix text coords to avoid clipping.
8353 The color to be used for drawing fonts. For the syntax of this option, check
8354 the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
8356 The default value of @var{fontcolor} is "black".
8358 @item fontcolor_expr
8359 String which is expanded the same way as @var{text} to obtain dynamic
8360 @var{fontcolor} value. By default this option has empty value and is not
8361 processed. When this option is set, it overrides @var{fontcolor} option.
8364 The font family to be used for drawing text. By default Sans.
8367 The font file to be used for drawing text. The path must be included.
8368 This parameter is mandatory if the fontconfig support is disabled.
8371 Draw the text applying alpha blending. The value can
8372 be a number between 0.0 and 1.0.
8373 The expression accepts the same variables @var{x, y} as well.
8374 The default value is 1.
8375 Please see @var{fontcolor_expr}.
8378 The font size to be used for drawing text.
8379 The default value of @var{fontsize} is 16.
8382 If set to 1, attempt to shape the text (for example, reverse the order of
8383 right-to-left text and join Arabic characters) before drawing it.
8384 Otherwise, just draw the text exactly as given.
8385 By default 1 (if supported).
8388 The flags to be used for loading the fonts.
8390 The flags map the corresponding flags supported by libfreetype, and are
8391 a combination of the following values:
8398 @item vertical_layout
8399 @item force_autohint
8402 @item ignore_global_advance_width
8404 @item ignore_transform
8410 Default value is "default".
8412 For more information consult the documentation for the FT_LOAD_*
8416 The color to be used for drawing a shadow behind the drawn text. For the
8417 syntax of this option, check the @ref{color syntax,,"Color" section in the
8418 ffmpeg-utils manual,ffmpeg-utils}.
8420 The default value of @var{shadowcolor} is "black".
8424 The x and y offsets for the text shadow position with respect to the
8425 position of the text. They can be either positive or negative
8426 values. The default value for both is "0".
8429 The starting frame number for the n/frame_num variable. The default value
8433 The size in number of spaces to use for rendering the tab.
8437 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
8438 format. It can be used with or without text parameter. @var{timecode_rate}
8439 option must be specified.
8441 @item timecode_rate, rate, r
8442 Set the timecode frame rate (timecode only). Value will be rounded to nearest
8443 integer. Minimum value is "1".
8444 Drop-frame timecode is supported for frame rates 30 & 60.
8447 If set to 1, the output of the timecode option will wrap around at 24 hours.
8448 Default is 0 (disabled).
8451 The text string to be drawn. The text must be a sequence of UTF-8
8453 This parameter is mandatory if no file is specified with the parameter
8457 A text file containing text to be drawn. The text must be a sequence
8458 of UTF-8 encoded characters.
8460 This parameter is mandatory if no text string is specified with the
8461 parameter @var{text}.
8463 If both @var{text} and @var{textfile} are specified, an error is thrown.
8466 If set to 1, the @var{textfile} will be reloaded before each frame.
8467 Be sure to update it atomically, or it may be read partially, or even fail.
8471 The expressions which specify the offsets where text will be drawn
8472 within the video frame. They are relative to the top/left border of the
8475 The default value of @var{x} and @var{y} is "0".
8477 See below for the list of accepted constants and functions.
8480 The parameters for @var{x} and @var{y} are expressions containing the
8481 following constants and functions:
8485 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
8489 horizontal and vertical chroma subsample values. For example for the
8490 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8493 the height of each text line
8501 @item max_glyph_a, ascent
8502 the maximum distance from the baseline to the highest/upper grid
8503 coordinate used to place a glyph outline point, for all the rendered
8505 It is a positive value, due to the grid's orientation with the Y axis
8508 @item max_glyph_d, descent
8509 the maximum distance from the baseline to the lowest grid coordinate
8510 used to place a glyph outline point, for all the rendered glyphs.
8511 This is a negative value, due to the grid's orientation, with the Y axis
8515 maximum glyph height, that is the maximum height for all the glyphs
8516 contained in the rendered text, it is equivalent to @var{ascent} -
8520 maximum glyph width, that is the maximum width for all the glyphs
8521 contained in the rendered text
8524 the number of input frame, starting from 0
8526 @item rand(min, max)
8527 return a random number included between @var{min} and @var{max}
8530 The input sample aspect ratio.
8533 timestamp expressed in seconds, NAN if the input timestamp is unknown
8536 the height of the rendered text
8539 the width of the rendered text
8543 the x and y offset coordinates where the text is drawn.
8545 These parameters allow the @var{x} and @var{y} expressions to refer
8546 each other, so you can for example specify @code{y=x/dar}.
8549 @anchor{drawtext_expansion}
8550 @subsection Text expansion
8552 If @option{expansion} is set to @code{strftime},
8553 the filter recognizes strftime() sequences in the provided text and
8554 expands them accordingly. Check the documentation of strftime(). This
8555 feature is deprecated.
8557 If @option{expansion} is set to @code{none}, the text is printed verbatim.
8559 If @option{expansion} is set to @code{normal} (which is the default),
8560 the following expansion mechanism is used.
8562 The backslash character @samp{\}, followed by any character, always expands to
8563 the second character.
8565 Sequences of the form @code{%@{...@}} are expanded. The text between the
8566 braces is a function name, possibly followed by arguments separated by ':'.
8567 If the arguments contain special characters or delimiters (':' or '@}'),
8568 they should be escaped.
8570 Note that they probably must also be escaped as the value for the
8571 @option{text} option in the filter argument string and as the filter
8572 argument in the filtergraph description, and possibly also for the shell,
8573 that makes up to four levels of escaping; using a text file avoids these
8576 The following functions are available:
8581 The expression evaluation result.
8583 It must take one argument specifying the expression to be evaluated,
8584 which accepts the same constants and functions as the @var{x} and
8585 @var{y} values. Note that not all constants should be used, for
8586 example the text size is not known when evaluating the expression, so
8587 the constants @var{text_w} and @var{text_h} will have an undefined
8590 @item expr_int_format, eif
8591 Evaluate the expression's value and output as formatted integer.
8593 The first argument is the expression to be evaluated, just as for the @var{expr} function.
8594 The second argument specifies the output format. Allowed values are @samp{x},
8595 @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
8596 @code{printf} function.
8597 The third parameter is optional and sets the number of positions taken by the output.
8598 It can be used to add padding with zeros from the left.
8601 The time at which the filter is running, expressed in UTC.
8602 It can accept an argument: a strftime() format string.
8605 The time at which the filter is running, expressed in the local time zone.
8606 It can accept an argument: a strftime() format string.
8609 Frame metadata. Takes one or two arguments.
8611 The first argument is mandatory and specifies the metadata key.
8613 The second argument is optional and specifies a default value, used when the
8614 metadata key is not found or empty.
8617 The frame number, starting from 0.
8620 A 1 character description of the current picture type.
8623 The timestamp of the current frame.
8624 It can take up to three arguments.
8626 The first argument is the format of the timestamp; it defaults to @code{flt}
8627 for seconds as a decimal number with microsecond accuracy; @code{hms} stands
8628 for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
8629 @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
8630 @code{localtime} stands for the timestamp of the frame formatted as
8631 local time zone time.
8633 The second argument is an offset added to the timestamp.
8635 If the format is set to @code{hms}, a third argument @code{24HH} may be
8636 supplied to present the hour part of the formatted timestamp in 24h format
8639 If the format is set to @code{localtime} or @code{gmtime},
8640 a third argument may be supplied: a strftime() format string.
8641 By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
8644 @subsection Examples
8648 Draw "Test Text" with font FreeSerif, using the default values for the
8649 optional parameters.
8652 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
8656 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
8657 and y=50 (counting from the top-left corner of the screen), text is
8658 yellow with a red box around it. Both the text and the box have an
8662 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
8663 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
8666 Note that the double quotes are not necessary if spaces are not used
8667 within the parameter list.
8670 Show the text at the center of the video frame:
8672 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
8676 Show the text at a random position, switching to a new position every 30 seconds:
8678 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)"
8682 Show a text line sliding from right to left in the last row of the video
8683 frame. The file @file{LONG_LINE} is assumed to contain a single line
8686 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
8690 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
8692 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
8696 Draw a single green letter "g", at the center of the input video.
8697 The glyph baseline is placed at half screen height.
8699 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
8703 Show text for 1 second every 3 seconds:
8705 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
8709 Use fontconfig to set the font. Note that the colons need to be escaped.
8711 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
8715 Print the date of a real-time encoding (see strftime(3)):
8717 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
8721 Show text fading in and out (appearing/disappearing):
8724 DS=1.0 # display start
8725 DE=10.0 # display end
8726 FID=1.5 # fade in duration
8727 FOD=5 # fade out duration
8728 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 @}"
8732 Horizontally align multiple separate texts. Note that @option{max_glyph_a}
8733 and the @option{fontsize} value are included in the @option{y} offset.
8735 drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
8736 drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
8741 For more information about libfreetype, check:
8742 @url{http://www.freetype.org/}.
8744 For more information about fontconfig, check:
8745 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
8747 For more information about libfribidi, check:
8748 @url{http://fribidi.org/}.
8752 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
8754 The filter accepts the following options:
8759 Set low and high threshold values used by the Canny thresholding
8762 The high threshold selects the "strong" edge pixels, which are then
8763 connected through 8-connectivity with the "weak" edge pixels selected
8764 by the low threshold.
8766 @var{low} and @var{high} threshold values must be chosen in the range
8767 [0,1], and @var{low} should be lesser or equal to @var{high}.
8769 Default value for @var{low} is @code{20/255}, and default value for @var{high}
8773 Define the drawing mode.
8777 Draw white/gray wires on black background.
8780 Mix the colors to create a paint/cartoon effect.
8783 Apply Canny edge detector on all selected planes.
8785 Default value is @var{wires}.
8788 Select planes for filtering. By default all available planes are filtered.
8791 @subsection Examples
8795 Standard edge detection with custom values for the hysteresis thresholding:
8797 edgedetect=low=0.1:high=0.4
8801 Painting effect without thresholding:
8803 edgedetect=mode=colormix:high=0
8808 Set brightness, contrast, saturation and approximate gamma adjustment.
8810 The filter accepts the following options:
8814 Set the contrast expression. The value must be a float value in range
8815 @code{-2.0} to @code{2.0}. The default value is "1".
8818 Set the brightness expression. The value must be a float value in
8819 range @code{-1.0} to @code{1.0}. The default value is "0".
8822 Set the saturation expression. The value must be a float in
8823 range @code{0.0} to @code{3.0}. The default value is "1".
8826 Set the gamma expression. The value must be a float in range
8827 @code{0.1} to @code{10.0}. The default value is "1".
8830 Set the gamma expression for red. The value must be a float in
8831 range @code{0.1} to @code{10.0}. The default value is "1".
8834 Set the gamma expression for green. The value must be a float in range
8835 @code{0.1} to @code{10.0}. The default value is "1".
8838 Set the gamma expression for blue. The value must be a float in range
8839 @code{0.1} to @code{10.0}. The default value is "1".
8842 Set the gamma weight expression. It can be used to reduce the effect
8843 of a high gamma value on bright image areas, e.g. keep them from
8844 getting overamplified and just plain white. The value must be a float
8845 in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
8846 gamma correction all the way down while @code{1.0} leaves it at its
8847 full strength. Default is "1".
8850 Set when the expressions for brightness, contrast, saturation and
8851 gamma expressions are evaluated.
8853 It accepts the following values:
8856 only evaluate expressions once during the filter initialization or
8857 when a command is processed
8860 evaluate expressions for each incoming frame
8863 Default value is @samp{init}.
8866 The expressions accept the following parameters:
8869 frame count of the input frame starting from 0
8872 byte position of the corresponding packet in the input file, NAN if
8876 frame rate of the input video, NAN if the input frame rate is unknown
8879 timestamp expressed in seconds, NAN if the input timestamp is unknown
8882 @subsection Commands
8883 The filter supports the following commands:
8887 Set the contrast expression.
8890 Set the brightness expression.
8893 Set the saturation expression.
8896 Set the gamma expression.
8899 Set the gamma_r expression.
8902 Set gamma_g expression.
8905 Set gamma_b expression.
8908 Set gamma_weight expression.
8910 The command accepts the same syntax of the corresponding option.
8912 If the specified expression is not valid, it is kept at its current
8919 Apply erosion effect to the video.
8921 This filter replaces the pixel by the local(3x3) minimum.
8923 It accepts the following options:
8930 Limit the maximum change for each plane, default is 65535.
8931 If 0, plane will remain unchanged.
8934 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
8937 Flags to local 3x3 coordinates maps like this:
8944 @section extractplanes
8946 Extract color channel components from input video stream into
8947 separate grayscale video streams.
8949 The filter accepts the following option:
8953 Set plane(s) to extract.
8955 Available values for planes are:
8966 Choosing planes not available in the input will result in an error.
8967 That means you cannot select @code{r}, @code{g}, @code{b} planes
8968 with @code{y}, @code{u}, @code{v} planes at same time.
8971 @subsection Examples
8975 Extract luma, u and v color channel component from input video frame
8976 into 3 grayscale outputs:
8978 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
8984 Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
8986 For each input image, the filter will compute the optimal mapping from
8987 the input to the output given the codebook length, that is the number
8988 of distinct output colors.
8990 This filter accepts the following options.
8993 @item codebook_length, l
8994 Set codebook length. The value must be a positive integer, and
8995 represents the number of distinct output colors. Default value is 256.
8998 Set the maximum number of iterations to apply for computing the optimal
8999 mapping. The higher the value the better the result and the higher the
9000 computation time. Default value is 1.
9003 Set a random seed, must be an integer included between 0 and
9004 UINT32_MAX. If not specified, or if explicitly set to -1, the filter
9005 will try to use a good random seed on a best effort basis.
9008 Set pal8 output pixel format. This option does not work with codebook
9009 length greater than 256.
9014 Measure graylevel entropy in histogram of color channels of video frames.
9016 It accepts the following parameters:
9020 Can be either @var{normal} or @var{diff}. Default is @var{normal}.
9022 @var{diff} mode measures entropy of histogram delta values, absolute differences
9023 between neighbour histogram values.
9028 Apply a fade-in/out effect to the input video.
9030 It accepts the following parameters:
9034 The effect type can be either "in" for a fade-in, or "out" for a fade-out
9036 Default is @code{in}.
9038 @item start_frame, s
9039 Specify the number of the frame to start applying the fade
9040 effect at. Default is 0.
9043 The number of frames that the fade effect lasts. At the end of the
9044 fade-in effect, the output video will have the same intensity as the input video.
9045 At the end of the fade-out transition, the output video will be filled with the
9046 selected @option{color}.
9050 If set to 1, fade only alpha channel, if one exists on the input.
9053 @item start_time, st
9054 Specify the timestamp (in seconds) of the frame to start to apply the fade
9055 effect. If both start_frame and start_time are specified, the fade will start at
9056 whichever comes last. Default is 0.
9059 The number of seconds for which the fade effect has to last. At the end of the
9060 fade-in effect the output video will have the same intensity as the input video,
9061 at the end of the fade-out transition the output video will be filled with the
9062 selected @option{color}.
9063 If both duration and nb_frames are specified, duration is used. Default is 0
9064 (nb_frames is used by default).
9067 Specify the color of the fade. Default is "black".
9070 @subsection Examples
9074 Fade in the first 30 frames of video:
9079 The command above is equivalent to:
9085 Fade out the last 45 frames of a 200-frame video:
9088 fade=type=out:start_frame=155:nb_frames=45
9092 Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
9094 fade=in:0:25, fade=out:975:25
9098 Make the first 5 frames yellow, then fade in from frame 5-24:
9100 fade=in:5:20:color=yellow
9104 Fade in alpha over first 25 frames of video:
9106 fade=in:0:25:alpha=1
9110 Make the first 5.5 seconds black, then fade in for 0.5 seconds:
9112 fade=t=in:st=5.5:d=0.5
9118 Apply arbitrary expressions to samples in frequency domain
9122 Adjust the dc value (gain) of the luma plane of the image. The filter
9123 accepts an integer value in range @code{0} to @code{1000}. The default
9124 value is set to @code{0}.
9127 Adjust the dc value (gain) of the 1st chroma plane of the image. The
9128 filter accepts an integer value in range @code{0} to @code{1000}. The
9129 default value is set to @code{0}.
9132 Adjust the dc value (gain) of the 2nd chroma plane of the image. The
9133 filter accepts an integer value in range @code{0} to @code{1000}. The
9134 default value is set to @code{0}.
9137 Set the frequency domain weight expression for the luma plane.
9140 Set the frequency domain weight expression for the 1st chroma plane.
9143 Set the frequency domain weight expression for the 2nd chroma plane.
9146 Set when the expressions are evaluated.
9148 It accepts the following values:
9151 Only evaluate expressions once during the filter initialization.
9154 Evaluate expressions for each incoming frame.
9157 Default value is @samp{init}.
9159 The filter accepts the following variables:
9162 The coordinates of the current sample.
9166 The width and height of the image.
9169 The number of input frame, starting from 0.
9172 @subsection Examples
9178 fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
9184 fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
9190 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
9196 fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
9202 Denoise frames using 3D FFT (frequency domain filtering).
9204 The filter accepts the following options:
9208 Set the noise sigma constant. This sets denoising strength.
9209 Default value is 1. Allowed range is from 0 to 30.
9210 Using very high sigma with low overlap may give blocking artifacts.
9213 Set amount of denoising. By default all detected noise is reduced.
9214 Default value is 1. Allowed range is from 0 to 1.
9217 Set size of block, Default is 4, can be 3, 4, 5 or 6.
9218 Actual size of block in pixels is 2 to power of @var{block}, so by default
9219 block size in pixels is 2^4 which is 16.
9222 Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8.
9225 Set number of previous frames to use for denoising. By default is set to 0.
9228 Set number of next frames to to use for denoising. By default is set to 0.
9231 Set planes which will be filtered, by default are all available filtered
9237 Extract a single field from an interlaced image using stride
9238 arithmetic to avoid wasting CPU time. The output frames are marked as
9241 The filter accepts the following options:
9245 Specify whether to extract the top (if the value is @code{0} or
9246 @code{top}) or the bottom field (if the value is @code{1} or
9252 Create new frames by copying the top and bottom fields from surrounding frames
9253 supplied as numbers by the hint file.
9257 Set file containing hints: absolute/relative frame numbers.
9259 There must be one line for each frame in a clip. Each line must contain two
9260 numbers separated by the comma, optionally followed by @code{-} or @code{+}.
9261 Numbers supplied on each line of file can not be out of [N-1,N+1] where N
9262 is current frame number for @code{absolute} mode or out of [-1, 1] range
9263 for @code{relative} mode. First number tells from which frame to pick up top
9264 field and second number tells from which frame to pick up bottom field.
9266 If optionally followed by @code{+} output frame will be marked as interlaced,
9267 else if followed by @code{-} output frame will be marked as progressive, else
9268 it will be marked same as input frame.
9269 If line starts with @code{#} or @code{;} that line is skipped.
9272 Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
9275 Example of first several lines of @code{hint} file for @code{relative} mode:
9278 1,0 - # second frame, use third's frame top field and second's frame bottom field
9279 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
9296 Field matching filter for inverse telecine. It is meant to reconstruct the
9297 progressive frames from a telecined stream. The filter does not drop duplicated
9298 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
9299 followed by a decimation filter such as @ref{decimate} in the filtergraph.
9301 The separation of the field matching and the decimation is notably motivated by
9302 the possibility of inserting a de-interlacing filter fallback between the two.
9303 If the source has mixed telecined and real interlaced content,
9304 @code{fieldmatch} will not be able to match fields for the interlaced parts.
9305 But these remaining combed frames will be marked as interlaced, and thus can be
9306 de-interlaced by a later filter such as @ref{yadif} before decimation.
9308 In addition to the various configuration options, @code{fieldmatch} can take an
9309 optional second stream, activated through the @option{ppsrc} option. If
9310 enabled, the frames reconstruction will be based on the fields and frames from
9311 this second stream. This allows the first input to be pre-processed in order to
9312 help the various algorithms of the filter, while keeping the output lossless
9313 (assuming the fields are matched properly). Typically, a field-aware denoiser,
9314 or brightness/contrast adjustments can help.
9316 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
9317 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
9318 which @code{fieldmatch} is based on. While the semantic and usage are very
9319 close, some behaviour and options names can differ.
9321 The @ref{decimate} filter currently only works for constant frame rate input.
9322 If your input has mixed telecined (30fps) and progressive content with a lower
9323 framerate like 24fps use the following filterchain to produce the necessary cfr
9324 stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
9326 The filter accepts the following options:
9330 Specify the assumed field order of the input stream. Available values are:
9334 Auto detect parity (use FFmpeg's internal parity value).
9336 Assume bottom field first.
9338 Assume top field first.
9341 Note that it is sometimes recommended not to trust the parity announced by the
9344 Default value is @var{auto}.
9347 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
9348 sense that it won't risk creating jerkiness due to duplicate frames when
9349 possible, but if there are bad edits or blended fields it will end up
9350 outputting combed frames when a good match might actually exist. On the other
9351 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
9352 but will almost always find a good frame if there is one. The other values are
9353 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
9354 jerkiness and creating duplicate frames versus finding good matches in sections
9355 with bad edits, orphaned fields, blended fields, etc.
9357 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
9359 Available values are:
9363 2-way matching (p/c)
9365 2-way matching, and trying 3rd match if still combed (p/c + n)
9367 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
9369 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
9370 still combed (p/c + n + u/b)
9372 3-way matching (p/c/n)
9374 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
9375 detected as combed (p/c/n + u/b)
9378 The parenthesis at the end indicate the matches that would be used for that
9379 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
9382 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
9385 Default value is @var{pc_n}.
9388 Mark the main input stream as a pre-processed input, and enable the secondary
9389 input stream as the clean source to pick the fields from. See the filter
9390 introduction for more details. It is similar to the @option{clip2} feature from
9393 Default value is @code{0} (disabled).
9396 Set the field to match from. It is recommended to set this to the same value as
9397 @option{order} unless you experience matching failures with that setting. In
9398 certain circumstances changing the field that is used to match from can have a
9399 large impact on matching performance. Available values are:
9403 Automatic (same value as @option{order}).
9405 Match from the bottom field.
9407 Match from the top field.
9410 Default value is @var{auto}.
9413 Set whether or not chroma is included during the match comparisons. In most
9414 cases it is recommended to leave this enabled. You should set this to @code{0}
9415 only if your clip has bad chroma problems such as heavy rainbowing or other
9416 artifacts. Setting this to @code{0} could also be used to speed things up at
9417 the cost of some accuracy.
9419 Default value is @code{1}.
9423 These define an exclusion band which excludes the lines between @option{y0} and
9424 @option{y1} from being included in the field matching decision. An exclusion
9425 band can be used to ignore subtitles, a logo, or other things that may
9426 interfere with the matching. @option{y0} sets the starting scan line and
9427 @option{y1} sets the ending line; all lines in between @option{y0} and
9428 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
9429 @option{y0} and @option{y1} to the same value will disable the feature.
9430 @option{y0} and @option{y1} defaults to @code{0}.
9433 Set the scene change detection threshold as a percentage of maximum change on
9434 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
9435 detection is only relevant in case @option{combmatch}=@var{sc}. The range for
9436 @option{scthresh} is @code{[0.0, 100.0]}.
9438 Default value is @code{12.0}.
9441 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
9442 account the combed scores of matches when deciding what match to use as the
9443 final match. Available values are:
9447 No final matching based on combed scores.
9449 Combed scores are only used when a scene change is detected.
9451 Use combed scores all the time.
9454 Default is @var{sc}.
9457 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
9458 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
9459 Available values are:
9463 No forced calculation.
9465 Force p/c/n calculations.
9467 Force p/c/n/u/b calculations.
9470 Default value is @var{none}.
9473 This is the area combing threshold used for combed frame detection. This
9474 essentially controls how "strong" or "visible" combing must be to be detected.
9475 Larger values mean combing must be more visible and smaller values mean combing
9476 can be less visible or strong and still be detected. Valid settings are from
9477 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
9478 be detected as combed). This is basically a pixel difference value. A good
9479 range is @code{[8, 12]}.
9481 Default value is @code{9}.
9484 Sets whether or not chroma is considered in the combed frame decision. Only
9485 disable this if your source has chroma problems (rainbowing, etc.) that are
9486 causing problems for the combed frame detection with chroma enabled. Actually,
9487 using @option{chroma}=@var{0} is usually more reliable, except for the case
9488 where there is chroma only combing in the source.
9490 Default value is @code{0}.
9494 Respectively set the x-axis and y-axis size of the window used during combed
9495 frame detection. This has to do with the size of the area in which
9496 @option{combpel} pixels are required to be detected as combed for a frame to be
9497 declared combed. See the @option{combpel} parameter description for more info.
9498 Possible values are any number that is a power of 2 starting at 4 and going up
9501 Default value is @code{16}.
9504 The number of combed pixels inside any of the @option{blocky} by
9505 @option{blockx} size blocks on the frame for the frame to be detected as
9506 combed. While @option{cthresh} controls how "visible" the combing must be, this
9507 setting controls "how much" combing there must be in any localized area (a
9508 window defined by the @option{blockx} and @option{blocky} settings) on the
9509 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
9510 which point no frames will ever be detected as combed). This setting is known
9511 as @option{MI} in TFM/VFM vocabulary.
9513 Default value is @code{80}.
9516 @anchor{p/c/n/u/b meaning}
9517 @subsection p/c/n/u/b meaning
9519 @subsubsection p/c/n
9521 We assume the following telecined stream:
9524 Top fields: 1 2 2 3 4
9525 Bottom fields: 1 2 3 4 4
9528 The numbers correspond to the progressive frame the fields relate to. Here, the
9529 first two frames are progressive, the 3rd and 4th are combed, and so on.
9531 When @code{fieldmatch} is configured to run a matching from bottom
9532 (@option{field}=@var{bottom}) this is how this input stream get transformed:
9537 B 1 2 3 4 4 <-- matching reference
9546 As a result of the field matching, we can see that some frames get duplicated.
9547 To perform a complete inverse telecine, you need to rely on a decimation filter
9548 after this operation. See for instance the @ref{decimate} filter.
9550 The same operation now matching from top fields (@option{field}=@var{top})
9555 T 1 2 2 3 4 <-- matching reference
9565 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
9566 basically, they refer to the frame and field of the opposite parity:
9569 @item @var{p} matches the field of the opposite parity in the previous frame
9570 @item @var{c} matches the field of the opposite parity in the current frame
9571 @item @var{n} matches the field of the opposite parity in the next frame
9576 The @var{u} and @var{b} matching are a bit special in the sense that they match
9577 from the opposite parity flag. In the following examples, we assume that we are
9578 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
9579 'x' is placed above and below each matched fields.
9581 With bottom matching (@option{field}=@var{bottom}):
9586 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
9587 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
9595 With top matching (@option{field}=@var{top}):
9600 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
9601 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
9609 @subsection Examples
9611 Simple IVTC of a top field first telecined stream:
9613 fieldmatch=order=tff:combmatch=none, decimate
9616 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
9618 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
9623 Transform the field order of the input video.
9625 It accepts the following parameters:
9630 The output field order. Valid values are @var{tff} for top field first or @var{bff}
9631 for bottom field first.
9634 The default value is @samp{tff}.
9636 The transformation is done by shifting the picture content up or down
9637 by one line, and filling the remaining line with appropriate picture content.
9638 This method is consistent with most broadcast field order converters.
9640 If the input video is not flagged as being interlaced, or it is already
9641 flagged as being of the required output field order, then this filter does
9642 not alter the incoming video.
9644 It is very useful when converting to or from PAL DV material,
9645 which is bottom field first.
9649 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
9652 @section fifo, afifo
9654 Buffer input images and send them when they are requested.
9656 It is mainly useful when auto-inserted by the libavfilter
9659 It does not take parameters.
9661 @section fillborders
9663 Fill borders of the input video, without changing video stream dimensions.
9664 Sometimes video can have garbage at the four edges and you may not want to
9665 crop video input to keep size multiple of some number.
9667 This filter accepts the following options:
9671 Number of pixels to fill from left border.
9674 Number of pixels to fill from right border.
9677 Number of pixels to fill from top border.
9680 Number of pixels to fill from bottom border.
9685 It accepts the following values:
9688 fill pixels using outermost pixels
9691 fill pixels using mirroring
9694 fill pixels with constant value
9697 Default is @var{smear}.
9700 Set color for pixels in fixed mode. Default is @var{black}.
9705 Find a rectangular object
9707 It accepts the following options:
9711 Filepath of the object image, needs to be in gray8.
9714 Detection threshold, default is 0.5.
9717 Number of mipmaps, default is 3.
9719 @item xmin, ymin, xmax, ymax
9720 Specifies the rectangle in which to search.
9723 @subsection Examples
9727 Generate a representative palette of a given video using @command{ffmpeg}:
9729 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
9735 Cover a rectangular object
9737 It accepts the following options:
9741 Filepath of the optional cover image, needs to be in yuv420.
9746 It accepts the following values:
9749 cover it by the supplied image
9751 cover it by interpolating the surrounding pixels
9754 Default value is @var{blur}.
9757 @subsection Examples
9761 Generate a representative palette of a given video using @command{ffmpeg}:
9763 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
9769 Flood area with values of same pixel components with another values.
9771 It accepts the following options:
9774 Set pixel x coordinate.
9777 Set pixel y coordinate.
9780 Set source #0 component value.
9783 Set source #1 component value.
9786 Set source #2 component value.
9789 Set source #3 component value.
9792 Set destination #0 component value.
9795 Set destination #1 component value.
9798 Set destination #2 component value.
9801 Set destination #3 component value.
9807 Convert the input video to one of the specified pixel formats.
9808 Libavfilter will try to pick one that is suitable as input to
9811 It accepts the following parameters:
9815 A '|'-separated list of pixel format names, such as
9816 "pix_fmts=yuv420p|monow|rgb24".
9820 @subsection Examples
9824 Convert the input video to the @var{yuv420p} format
9826 format=pix_fmts=yuv420p
9829 Convert the input video to any of the formats in the list
9831 format=pix_fmts=yuv420p|yuv444p|yuv410p
9838 Convert the video to specified constant frame rate by duplicating or dropping
9839 frames as necessary.
9841 It accepts the following parameters:
9845 The desired output frame rate. The default is @code{25}.
9848 Assume the first PTS should be the given value, in seconds. This allows for
9849 padding/trimming at the start of stream. By default, no assumption is made
9850 about the first frame's expected PTS, so no padding or trimming is done.
9851 For example, this could be set to 0 to pad the beginning with duplicates of
9852 the first frame if a video stream starts after the audio stream or to trim any
9853 frames with a negative PTS.
9856 Timestamp (PTS) rounding method.
9858 Possible values are:
9865 round towards -infinity
9867 round towards +infinity
9871 The default is @code{near}.
9874 Action performed when reading the last frame.
9876 Possible values are:
9879 Use same timestamp rounding method as used for other frames.
9881 Pass through last frame if input duration has not been reached yet.
9883 The default is @code{round}.
9887 Alternatively, the options can be specified as a flat string:
9888 @var{fps}[:@var{start_time}[:@var{round}]].
9890 See also the @ref{setpts} filter.
9892 @subsection Examples
9896 A typical usage in order to set the fps to 25:
9902 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
9904 fps=fps=film:round=near
9910 Pack two different video streams into a stereoscopic video, setting proper
9911 metadata on supported codecs. The two views should have the same size and
9912 framerate and processing will stop when the shorter video ends. Please note
9913 that you may conveniently adjust view properties with the @ref{scale} and
9916 It accepts the following parameters:
9920 The desired packing format. Supported values are:
9925 The views are next to each other (default).
9928 The views are on top of each other.
9931 The views are packed by line.
9934 The views are packed by column.
9937 The views are temporally interleaved.
9946 # Convert left and right views into a frame-sequential video
9947 ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
9949 # Convert views into a side-by-side video with the same output resolution as the input
9950 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
9955 Change the frame rate by interpolating new video output frames from the source
9958 This filter is not designed to function correctly with interlaced media. If
9959 you wish to change the frame rate of interlaced media then you are required
9960 to deinterlace before this filter and re-interlace after this filter.
9962 A description of the accepted options follows.
9966 Specify the output frames per second. This option can also be specified
9967 as a value alone. The default is @code{50}.
9970 Specify the start of a range where the output frame will be created as a
9971 linear interpolation of two frames. The range is [@code{0}-@code{255}],
9972 the default is @code{15}.
9975 Specify the end of a range where the output frame will be created as a
9976 linear interpolation of two frames. The range is [@code{0}-@code{255}],
9977 the default is @code{240}.
9980 Specify the level at which a scene change is detected as a value between
9981 0 and 100 to indicate a new scene; a low value reflects a low
9982 probability for the current frame to introduce a new scene, while a higher
9983 value means the current frame is more likely to be one.
9984 The default is @code{8.2}.
9987 Specify flags influencing the filter process.
9989 Available value for @var{flags} is:
9992 @item scene_change_detect, scd
9993 Enable scene change detection using the value of the option @var{scene}.
9994 This flag is enabled by default.
10000 Select one frame every N-th frame.
10002 This filter accepts the following option:
10005 Select frame after every @code{step} frames.
10006 Allowed values are positive integers higher than 0. Default value is @code{1}.
10012 Apply a frei0r effect to the input video.
10014 To enable the compilation of this filter, you need to install the frei0r
10015 header and configure FFmpeg with @code{--enable-frei0r}.
10017 It accepts the following parameters:
10022 The name of the frei0r effect to load. If the environment variable
10023 @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
10024 directories specified by the colon-separated list in @env{FREI0R_PATH}.
10025 Otherwise, the standard frei0r paths are searched, in this order:
10026 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
10027 @file{/usr/lib/frei0r-1/}.
10029 @item filter_params
10030 A '|'-separated list of parameters to pass to the frei0r effect.
10034 A frei0r effect parameter can be a boolean (its value is either
10035 "y" or "n"), a double, a color (specified as
10036 @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
10037 numbers between 0.0 and 1.0, inclusive) or a color description as specified in the
10038 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils},
10039 a position (specified as @var{X}/@var{Y}, where
10040 @var{X} and @var{Y} are floating point numbers) and/or a string.
10042 The number and types of parameters depend on the loaded effect. If an
10043 effect parameter is not specified, the default value is set.
10045 @subsection Examples
10049 Apply the distort0r effect, setting the first two double parameters:
10051 frei0r=filter_name=distort0r:filter_params=0.5|0.01
10055 Apply the colordistance effect, taking a color as the first parameter:
10057 frei0r=colordistance:0.2/0.3/0.4
10058 frei0r=colordistance:violet
10059 frei0r=colordistance:0x112233
10063 Apply the perspective effect, specifying the top left and top right image
10066 frei0r=perspective:0.2/0.2|0.8/0.2
10070 For more information, see
10071 @url{http://frei0r.dyne.org}
10075 Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
10077 It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
10078 processing filter, one of them is performed once per block, not per pixel.
10079 This allows for much higher speed.
10081 The filter accepts the following options:
10085 Set quality. This option defines the number of levels for averaging. It accepts
10086 an integer in the range 4-5. Default value is @code{4}.
10089 Force a constant quantization parameter. It accepts an integer in range 0-63.
10090 If not set, the filter will use the QP from the video stream (if available).
10093 Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
10094 more details but also more artifacts, while higher values make the image smoother
10095 but also blurrier. Default value is @code{0} − PSNR optimal.
10097 @item use_bframe_qp
10098 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
10099 option may cause flicker since the B-Frames have often larger QP. Default is
10100 @code{0} (not enabled).
10106 Apply Gaussian blur filter.
10108 The filter accepts the following options:
10112 Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
10115 Set number of steps for Gaussian approximation. Defauls is @code{1}.
10118 Set which planes to filter. By default all planes are filtered.
10121 Set vertical sigma, if negative it will be same as @code{sigma}.
10122 Default is @code{-1}.
10127 Apply generic equation to each pixel.
10129 The filter accepts the following options:
10132 @item lum_expr, lum
10133 Set the luminance expression.
10135 Set the chrominance blue expression.
10137 Set the chrominance red expression.
10138 @item alpha_expr, a
10139 Set the alpha expression.
10141 Set the red expression.
10142 @item green_expr, g
10143 Set the green expression.
10145 Set the blue expression.
10148 The colorspace is selected according to the specified options. If one
10149 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
10150 options is specified, the filter will automatically select a YCbCr
10151 colorspace. If one of the @option{red_expr}, @option{green_expr}, or
10152 @option{blue_expr} options is specified, it will select an RGB
10155 If one of the chrominance expression is not defined, it falls back on the other
10156 one. If no alpha expression is specified it will evaluate to opaque value.
10157 If none of chrominance expressions are specified, they will evaluate
10158 to the luminance expression.
10160 The expressions can use the following variables and functions:
10164 The sequential number of the filtered frame, starting from @code{0}.
10168 The coordinates of the current sample.
10172 The width and height of the image.
10176 Width and height scale depending on the currently filtered plane. It is the
10177 ratio between the corresponding luma plane number of pixels and the current
10178 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
10179 @code{0.5,0.5} for chroma planes.
10182 Time of the current frame, expressed in seconds.
10185 Return the value of the pixel at location (@var{x},@var{y}) of the current
10189 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
10193 Return the value of the pixel at location (@var{x},@var{y}) of the
10194 blue-difference chroma plane. Return 0 if there is no such plane.
10197 Return the value of the pixel at location (@var{x},@var{y}) of the
10198 red-difference chroma plane. Return 0 if there is no such plane.
10203 Return the value of the pixel at location (@var{x},@var{y}) of the
10204 red/green/blue component. Return 0 if there is no such component.
10207 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
10208 plane. Return 0 if there is no such plane.
10211 For functions, if @var{x} and @var{y} are outside the area, the value will be
10212 automatically clipped to the closer edge.
10214 @subsection Examples
10218 Flip the image horizontally:
10224 Generate a bidimensional sine wave, with angle @code{PI/3} and a
10225 wavelength of 100 pixels:
10227 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
10231 Generate a fancy enigmatic moving light:
10233 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
10237 Generate a quick emboss effect:
10239 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
10243 Modify RGB components depending on pixel position:
10245 geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
10249 Create a radial gradient that is the same size as the input (also see
10250 the @ref{vignette} filter):
10252 geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
10258 Fix the banding artifacts that are sometimes introduced into nearly flat
10259 regions by truncation to 8-bit color depth.
10260 Interpolate the gradients that should go where the bands are, and
10263 It is designed for playback only. Do not use it prior to
10264 lossy compression, because compression tends to lose the dither and
10265 bring back the bands.
10267 It accepts the following parameters:
10272 The maximum amount by which the filter will change any one pixel. This is also
10273 the threshold for detecting nearly flat regions. Acceptable values range from
10274 .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
10278 The neighborhood to fit the gradient to. A larger radius makes for smoother
10279 gradients, but also prevents the filter from modifying the pixels near detailed
10280 regions. Acceptable values are 8-32; the default value is 16. Out-of-range
10281 values will be clipped to the valid range.
10285 Alternatively, the options can be specified as a flat string:
10286 @var{strength}[:@var{radius}]
10288 @subsection Examples
10292 Apply the filter with a @code{3.5} strength and radius of @code{8}:
10298 Specify radius, omitting the strength (which will fall-back to the default
10306 @section graphmonitor, agraphmonitor
10307 Show various filtergraph stats.
10309 With this filter one can debug complete filtergraph.
10310 Especially issues with links filling with queued frames.
10312 The filter accepts the following options:
10316 Set video output size. Default is @var{hd720}.
10319 Set video opacity. Default is @var{0.9}. Allowed range is from @var{0} to @var{1}.
10322 Set output mode, can be @var{fulll} or @var{compact}.
10323 In @var{compact} mode only filters with some queued frames have displayed stats.
10326 Set flags which enable which stats are shown in video.
10328 Available values for flags are:
10331 Display number of queued frames in each link.
10333 @item frame_count_in
10334 Display number of frames taken from filter.
10336 @item frame_count_out
10337 Display number of frames given out from filter.
10340 Display current filtered frame pts.
10343 Display current filtered frame time.
10346 Display time base for filter link.
10349 Display used format for filter link.
10352 Display video size or number of audio channels in case of audio used by filter link.
10355 Display video frame rate or sample rate in case of audio used by filter link.
10359 Set upper limit for video rate of output stream, Default value is @var{25}.
10360 This guarantee that output video frame rate will not be higher than this value.
10364 A color constancy variation filter which estimates scene illumination via grey edge algorithm
10365 and corrects the scene colors accordingly.
10367 See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf}
10369 The filter accepts the following options:
10373 The order of differentiation to be applied on the scene. Must be chosen in the range
10374 [0,2] and default value is 1.
10377 The Minkowski parameter to be used for calculating the Minkowski distance. Must
10378 be chosen in the range [0,20] and default value is 1. Set to 0 for getting
10379 max value instead of calculating Minkowski distance.
10382 The standard deviation of Gaussian blur to be applied on the scene. Must be
10383 chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) )
10384 can't be euqal to 0 if @var{difford} is greater than 0.
10387 @subsection Examples
10393 greyedge=difford=1:minknorm=5:sigma=2
10399 greyedge=difford=1:minknorm=0:sigma=2
10407 Apply a Hald CLUT to a video stream.
10409 First input is the video stream to process, and second one is the Hald CLUT.
10410 The Hald CLUT input can be a simple picture or a complete video stream.
10412 The filter accepts the following options:
10416 Force termination when the shortest input terminates. Default is @code{0}.
10418 Continue applying the last CLUT after the end of the stream. A value of
10419 @code{0} disable the filter after the last frame of the CLUT is reached.
10420 Default is @code{1}.
10423 @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
10424 filters share the same internals).
10426 More information about the Hald CLUT can be found on Eskil Steenberg's website
10427 (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
10429 @subsection Workflow examples
10431 @subsubsection Hald CLUT video stream
10433 Generate an identity Hald CLUT stream altered with various effects:
10435 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
10438 Note: make sure you use a lossless codec.
10440 Then use it with @code{haldclut} to apply it on some random stream:
10442 ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
10445 The Hald CLUT will be applied to the 10 first seconds (duration of
10446 @file{clut.nut}), then the latest picture of that CLUT stream will be applied
10447 to the remaining frames of the @code{mandelbrot} stream.
10449 @subsubsection Hald CLUT with preview
10451 A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
10452 @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
10453 biggest possible square starting at the top left of the picture. The remaining
10454 padding pixels (bottom or right) will be ignored. This area can be used to add
10455 a preview of the Hald CLUT.
10457 Typically, the following generated Hald CLUT will be supported by the
10458 @code{haldclut} filter:
10461 ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
10462 pad=iw+320 [padded_clut];
10463 smptebars=s=320x256, split [a][b];
10464 [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
10465 [main][b] overlay=W-320" -frames:v 1 clut.png
10468 It contains the original and a preview of the effect of the CLUT: SMPTE color
10469 bars are displayed on the right-top, and below the same color bars processed by
10472 Then, the effect of this Hald CLUT can be visualized with:
10474 ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
10479 Flip the input video horizontally.
10481 For example, to horizontally flip the input video with @command{ffmpeg}:
10483 ffmpeg -i in.avi -vf "hflip" out.avi
10487 This filter applies a global color histogram equalization on a
10490 It can be used to correct video that has a compressed range of pixel
10491 intensities. The filter redistributes the pixel intensities to
10492 equalize their distribution across the intensity range. It may be
10493 viewed as an "automatically adjusting contrast filter". This filter is
10494 useful only for correcting degraded or poorly captured source
10497 The filter accepts the following options:
10501 Determine the amount of equalization to be applied. As the strength
10502 is reduced, the distribution of pixel intensities more-and-more
10503 approaches that of the input frame. The value must be a float number
10504 in the range [0,1] and defaults to 0.200.
10507 Set the maximum intensity that can generated and scale the output
10508 values appropriately. The strength should be set as desired and then
10509 the intensity can be limited if needed to avoid washing-out. The value
10510 must be a float number in the range [0,1] and defaults to 0.210.
10513 Set the antibanding level. If enabled the filter will randomly vary
10514 the luminance of output pixels by a small amount to avoid banding of
10515 the histogram. Possible values are @code{none}, @code{weak} or
10516 @code{strong}. It defaults to @code{none}.
10521 Compute and draw a color distribution histogram for the input video.
10523 The computed histogram is a representation of the color component
10524 distribution in an image.
10526 Standard histogram displays the color components distribution in an image.
10527 Displays color graph for each color component. Shows distribution of
10528 the Y, U, V, A or R, G, B components, depending on input format, in the
10529 current frame. Below each graph a color component scale meter is shown.
10531 The filter accepts the following options:
10535 Set height of level. Default value is @code{200}.
10536 Allowed range is [50, 2048].
10539 Set height of color scale. Default value is @code{12}.
10540 Allowed range is [0, 40].
10544 It accepts the following values:
10547 Per color component graphs are placed below each other.
10550 Per color component graphs are placed side by side.
10553 Presents information identical to that in the @code{parade}, except
10554 that the graphs representing color components are superimposed directly
10557 Default is @code{stack}.
10560 Set mode. Can be either @code{linear}, or @code{logarithmic}.
10561 Default is @code{linear}.
10564 Set what color components to display.
10565 Default is @code{7}.
10568 Set foreground opacity. Default is @code{0.7}.
10571 Set background opacity. Default is @code{0.5}.
10574 @subsection Examples
10579 Calculate and draw histogram:
10581 ffplay -i input -vf histogram
10589 This is a high precision/quality 3d denoise filter. It aims to reduce
10590 image noise, producing smooth images and making still images really
10591 still. It should enhance compressibility.
10593 It accepts the following optional parameters:
10597 A non-negative floating point number which specifies spatial luma strength.
10598 It defaults to 4.0.
10600 @item chroma_spatial
10601 A non-negative floating point number which specifies spatial chroma strength.
10602 It defaults to 3.0*@var{luma_spatial}/4.0.
10605 A floating point number which specifies luma temporal strength. It defaults to
10606 6.0*@var{luma_spatial}/4.0.
10609 A floating point number which specifies chroma temporal strength. It defaults to
10610 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
10613 @anchor{hwdownload}
10614 @section hwdownload
10616 Download hardware frames to system memory.
10618 The input must be in hardware frames, and the output a non-hardware format.
10619 Not all formats will be supported on the output - it may be necessary to insert
10620 an additional @option{format} filter immediately following in the graph to get
10621 the output in a supported format.
10625 Map hardware frames to system memory or to another device.
10627 This filter has several different modes of operation; which one is used depends
10628 on the input and output formats:
10631 Hardware frame input, normal frame output
10633 Map the input frames to system memory and pass them to the output. If the
10634 original hardware frame is later required (for example, after overlaying
10635 something else on part of it), the @option{hwmap} filter can be used again
10636 in the next mode to retrieve it.
10638 Normal frame input, hardware frame output
10640 If the input is actually a software-mapped hardware frame, then unmap it -
10641 that is, return the original hardware frame.
10643 Otherwise, a device must be provided. Create new hardware surfaces on that
10644 device for the output, then map them back to the software format at the input
10645 and give those frames to the preceding filter. This will then act like the
10646 @option{hwupload} filter, but may be able to avoid an additional copy when
10647 the input is already in a compatible format.
10649 Hardware frame input and output
10651 A device must be supplied for the output, either directly or with the
10652 @option{derive_device} option. The input and output devices must be of
10653 different types and compatible - the exact meaning of this is
10654 system-dependent, but typically it means that they must refer to the same
10655 underlying hardware context (for example, refer to the same graphics card).
10657 If the input frames were originally created on the output device, then unmap
10658 to retrieve the original frames.
10660 Otherwise, map the frames to the output device - create new hardware frames
10661 on the output corresponding to the frames on the input.
10664 The following additional parameters are accepted:
10668 Set the frame mapping mode. Some combination of:
10671 The mapped frame should be readable.
10673 The mapped frame should be writeable.
10675 The mapping will always overwrite the entire frame.
10677 This may improve performance in some cases, as the original contents of the
10678 frame need not be loaded.
10680 The mapping must not involve any copying.
10682 Indirect mappings to copies of frames are created in some cases where either
10683 direct mapping is not possible or it would have unexpected properties.
10684 Setting this flag ensures that the mapping is direct and will fail if that is
10687 Defaults to @var{read+write} if not specified.
10689 @item derive_device @var{type}
10690 Rather than using the device supplied at initialisation, instead derive a new
10691 device of type @var{type} from the device the input frames exist on.
10694 In a hardware to hardware mapping, map in reverse - create frames in the sink
10695 and map them back to the source. This may be necessary in some cases where
10696 a mapping in one direction is required but only the opposite direction is
10697 supported by the devices being used.
10699 This option is dangerous - it may break the preceding filter in undefined
10700 ways if there are any additional constraints on that filter's output.
10701 Do not use it without fully understanding the implications of its use.
10707 Upload system memory frames to hardware surfaces.
10709 The device to upload to must be supplied when the filter is initialised. If
10710 using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
10713 @anchor{hwupload_cuda}
10714 @section hwupload_cuda
10716 Upload system memory frames to a CUDA device.
10718 It accepts the following optional parameters:
10722 The number of the CUDA device to use
10727 Apply a high-quality magnification filter designed for pixel art. This filter
10728 was originally created by Maxim Stepin.
10730 It accepts the following option:
10734 Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
10735 @code{hq3x} and @code{4} for @code{hq4x}.
10736 Default is @code{3}.
10740 Stack input videos horizontally.
10742 All streams must be of same pixel format and of same height.
10744 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
10745 to create same output.
10747 The filter accept the following option:
10751 Set number of input streams. Default is 2.
10754 If set to 1, force the output to terminate when the shortest input
10755 terminates. Default value is 0.
10760 Modify the hue and/or the saturation of the input.
10762 It accepts the following parameters:
10766 Specify the hue angle as a number of degrees. It accepts an expression,
10767 and defaults to "0".
10770 Specify the saturation in the [-10,10] range. It accepts an expression and
10774 Specify the hue angle as a number of radians. It accepts an
10775 expression, and defaults to "0".
10778 Specify the brightness in the [-10,10] range. It accepts an expression and
10782 @option{h} and @option{H} are mutually exclusive, and can't be
10783 specified at the same time.
10785 The @option{b}, @option{h}, @option{H} and @option{s} option values are
10786 expressions containing the following constants:
10790 frame count of the input frame starting from 0
10793 presentation timestamp of the input frame expressed in time base units
10796 frame rate of the input video, NAN if the input frame rate is unknown
10799 timestamp expressed in seconds, NAN if the input timestamp is unknown
10802 time base of the input video
10805 @subsection Examples
10809 Set the hue to 90 degrees and the saturation to 1.0:
10815 Same command but expressing the hue in radians:
10821 Rotate hue and make the saturation swing between 0
10822 and 2 over a period of 1 second:
10824 hue="H=2*PI*t: s=sin(2*PI*t)+1"
10828 Apply a 3 seconds saturation fade-in effect starting at 0:
10830 hue="s=min(t/3\,1)"
10833 The general fade-in expression can be written as:
10835 hue="s=min(0\, max((t-START)/DURATION\, 1))"
10839 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
10841 hue="s=max(0\, min(1\, (8-t)/3))"
10844 The general fade-out expression can be written as:
10846 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
10851 @subsection Commands
10853 This filter supports the following commands:
10859 Modify the hue and/or the saturation and/or brightness of the input video.
10860 The command accepts the same syntax of the corresponding option.
10862 If the specified expression is not valid, it is kept at its current
10866 @section hysteresis
10868 Grow first stream into second stream by connecting components.
10869 This makes it possible to build more robust edge masks.
10871 This filter accepts the following options:
10875 Set which planes will be processed as bitmap, unprocessed planes will be
10876 copied from first stream.
10877 By default value 0xf, all planes will be processed.
10880 Set threshold which is used in filtering. If pixel component value is higher than
10881 this value filter algorithm for connecting components is activated.
10882 By default value is 0.
10887 Detect video interlacing type.
10889 This filter tries to detect if the input frames are interlaced, progressive,
10890 top or bottom field first. It will also try to detect fields that are
10891 repeated between adjacent frames (a sign of telecine).
10893 Single frame detection considers only immediately adjacent frames when classifying each frame.
10894 Multiple frame detection incorporates the classification history of previous frames.
10896 The filter will log these metadata values:
10899 @item single.current_frame
10900 Detected type of current frame using single-frame detection. One of:
10901 ``tff'' (top field first), ``bff'' (bottom field first),
10902 ``progressive'', or ``undetermined''
10905 Cumulative number of frames detected as top field first using single-frame detection.
10908 Cumulative number of frames detected as top field first using multiple-frame detection.
10911 Cumulative number of frames detected as bottom field first using single-frame detection.
10913 @item multiple.current_frame
10914 Detected type of current frame using multiple-frame detection. One of:
10915 ``tff'' (top field first), ``bff'' (bottom field first),
10916 ``progressive'', or ``undetermined''
10919 Cumulative number of frames detected as bottom field first using multiple-frame detection.
10921 @item single.progressive
10922 Cumulative number of frames detected as progressive using single-frame detection.
10924 @item multiple.progressive
10925 Cumulative number of frames detected as progressive using multiple-frame detection.
10927 @item single.undetermined
10928 Cumulative number of frames that could not be classified using single-frame detection.
10930 @item multiple.undetermined
10931 Cumulative number of frames that could not be classified using multiple-frame detection.
10933 @item repeated.current_frame
10934 Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
10936 @item repeated.neither
10937 Cumulative number of frames with no repeated field.
10940 Cumulative number of frames with the top field repeated from the previous frame's top field.
10942 @item repeated.bottom
10943 Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
10946 The filter accepts the following options:
10950 Set interlacing threshold.
10952 Set progressive threshold.
10954 Threshold for repeated field detection.
10956 Number of frames after which a given frame's contribution to the
10957 statistics is halved (i.e., it contributes only 0.5 to its
10958 classification). The default of 0 means that all frames seen are given
10959 full weight of 1.0 forever.
10960 @item analyze_interlaced_flag
10961 When this is not 0 then idet will use the specified number of frames to determine
10962 if the interlaced flag is accurate, it will not count undetermined frames.
10963 If the flag is found to be accurate it will be used without any further
10964 computations, if it is found to be inaccurate it will be cleared without any
10965 further computations. This allows inserting the idet filter as a low computational
10966 method to clean up the interlaced flag
10971 Deinterleave or interleave fields.
10973 This filter allows one to process interlaced images fields without
10974 deinterlacing them. Deinterleaving splits the input frame into 2
10975 fields (so called half pictures). Odd lines are moved to the top
10976 half of the output image, even lines to the bottom half.
10977 You can process (filter) them independently and then re-interleave them.
10979 The filter accepts the following options:
10983 @item chroma_mode, c
10984 @item alpha_mode, a
10985 Available values for @var{luma_mode}, @var{chroma_mode} and
10986 @var{alpha_mode} are:
10992 @item deinterleave, d
10993 Deinterleave fields, placing one above the other.
10995 @item interleave, i
10996 Interleave fields. Reverse the effect of deinterleaving.
10998 Default value is @code{none}.
11000 @item luma_swap, ls
11001 @item chroma_swap, cs
11002 @item alpha_swap, as
11003 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
11008 Apply inflate effect to the video.
11010 This filter replaces the pixel by the local(3x3) average by taking into account
11011 only values higher than the pixel.
11013 It accepts the following options:
11020 Limit the maximum change for each plane, default is 65535.
11021 If 0, plane will remain unchanged.
11026 Simple interlacing filter from progressive contents. This interleaves upper (or
11027 lower) lines from odd frames with lower (or upper) lines from even frames,
11028 halving the frame rate and preserving image height.
11031 Original Original New Frame
11032 Frame 'j' Frame 'j+1' (tff)
11033 ========== =========== ==================
11034 Line 0 --------------------> Frame 'j' Line 0
11035 Line 1 Line 1 ----> Frame 'j+1' Line 1
11036 Line 2 ---------------------> Frame 'j' Line 2
11037 Line 3 Line 3 ----> Frame 'j+1' Line 3
11039 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
11042 It accepts the following optional parameters:
11046 This determines whether the interlaced frame is taken from the even
11047 (tff - default) or odd (bff) lines of the progressive frame.
11050 Vertical lowpass filter to avoid twitter interlacing and
11051 reduce moire patterns.
11055 Disable vertical lowpass filter
11058 Enable linear filter (default)
11061 Enable complex filter. This will slightly less reduce twitter and moire
11062 but better retain detail and subjective sharpness impression.
11069 Deinterlace input video by applying Donald Graft's adaptive kernel
11070 deinterling. Work on interlaced parts of a video to produce
11071 progressive frames.
11073 The description of the accepted parameters follows.
11077 Set the threshold which affects the filter's tolerance when
11078 determining if a pixel line must be processed. It must be an integer
11079 in the range [0,255] and defaults to 10. A value of 0 will result in
11080 applying the process on every pixels.
11083 Paint pixels exceeding the threshold value to white if set to 1.
11087 Set the fields order. Swap fields if set to 1, leave fields alone if
11091 Enable additional sharpening if set to 1. Default is 0.
11094 Enable twoway sharpening if set to 1. Default is 0.
11097 @subsection Examples
11101 Apply default values:
11103 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
11107 Enable additional sharpening:
11113 Paint processed pixels in white:
11119 @section lenscorrection
11121 Correct radial lens distortion
11123 This filter can be used to correct for radial distortion as can result from the use
11124 of wide angle lenses, and thereby re-rectify the image. To find the right parameters
11125 one can use tools available for example as part of opencv or simply trial-and-error.
11126 To use opencv use the calibration sample (under samples/cpp) from the opencv sources
11127 and extract the k1 and k2 coefficients from the resulting matrix.
11129 Note that effectively the same filter is available in the open-source tools Krita and
11130 Digikam from the KDE project.
11132 In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
11133 this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
11134 brightness distribution, so you may want to use both filters together in certain
11135 cases, though you will have to take care of ordering, i.e. whether vignetting should
11136 be applied before or after lens correction.
11138 @subsection Options
11140 The filter accepts the following options:
11144 Relative x-coordinate of the focal point of the image, and thereby the center of the
11145 distortion. This value has a range [0,1] and is expressed as fractions of the image
11146 width. Default is 0.5.
11148 Relative y-coordinate of the focal point of the image, and thereby the center of the
11149 distortion. This value has a range [0,1] and is expressed as fractions of the image
11150 height. Default is 0.5.
11152 Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means
11153 no correction. Default is 0.
11155 Coefficient of the double quadratic correction term. This value has a range [-1,1].
11156 0 means no correction. Default is 0.
11159 The formula that generates the correction is:
11161 @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)
11163 where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
11164 distances from the focal point in the source and target images, respectively.
11168 Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}).
11170 The @code{lensfun} filter requires the camera make, camera model, and lens model
11171 to apply the lens correction. The filter will load the lensfun database and
11172 query it to find the corresponding camera and lens entries in the database. As
11173 long as these entries can be found with the given options, the filter can
11174 perform corrections on frames. Note that incomplete strings will result in the
11175 filter choosing the best match with the given options, and the filter will
11176 output the chosen camera and lens models (logged with level "info"). You must
11177 provide the make, camera model, and lens model as they are required.
11179 The filter accepts the following options:
11183 The make of the camera (for example, "Canon"). This option is required.
11186 The model of the camera (for example, "Canon EOS 100D"). This option is
11190 The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This
11191 option is required.
11194 The type of correction to apply. The following values are valid options:
11198 Enables fixing lens vignetting.
11201 Enables fixing lens geometry. This is the default.
11204 Enables fixing chromatic aberrations.
11207 Enables fixing lens vignetting and lens geometry.
11210 Enables fixing lens vignetting and chromatic aberrations.
11213 Enables fixing both lens geometry and chromatic aberrations.
11216 Enables all possible corrections.
11220 The focal length of the image/video (zoom; expected constant for video). For
11221 example, a 18--55mm lens has focal length range of [18--55], so a value in that
11222 range should be chosen when using that lens. Default 18.
11225 The aperture of the image/video (expected constant for video). Note that
11226 aperture is only used for vignetting correction. Default 3.5.
11228 @item focus_distance
11229 The focus distance of the image/video (expected constant for video). Note that
11230 focus distance is only used for vignetting and only slightly affects the
11231 vignetting correction process. If unknown, leave it at the default value (which
11234 @item target_geometry
11235 The target geometry of the output image/video. The following values are valid
11239 @item rectilinear (default)
11242 @item equirectangular
11243 @item fisheye_orthographic
11244 @item fisheye_stereographic
11245 @item fisheye_equisolid
11246 @item fisheye_thoby
11249 Apply the reverse of image correction (instead of correcting distortion, apply
11252 @item interpolation
11253 The type of interpolation used when correcting distortion. The following values
11258 @item linear (default)
11263 @subsection Examples
11267 Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens
11268 model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and
11272 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
11276 Apply the same as before, but only for the first 5 seconds of video.
11279 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
11286 Obtain the VMAF (Video Multi-Method Assessment Fusion)
11287 score between two input videos.
11289 The obtained VMAF score is printed through the logging system.
11291 It requires Netflix's vmaf library (libvmaf) as a pre-requisite.
11292 After installing the library it can be enabled using:
11293 @code{./configure --enable-libvmaf --enable-version3}.
11294 If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}.
11296 The filter has following options:
11300 Set the model path which is to be used for SVM.
11301 Default value: @code{"vmaf_v0.6.1.pkl"}
11304 Set the file path to be used to store logs.
11307 Set the format of the log file (xml or json).
11309 @item enable_transform
11310 Enables transform for computing vmaf.
11313 Invokes the phone model which will generate VMAF scores higher than in the
11314 regular model, which is more suitable for laptop, TV, etc. viewing conditions.
11317 Enables computing psnr along with vmaf.
11320 Enables computing ssim along with vmaf.
11323 Enables computing ms_ssim along with vmaf.
11326 Set the pool method (mean, min or harmonic mean) to be used for computing vmaf.
11329 Set number of threads to be used when computing vmaf.
11332 Set interval for frame subsampling used when computing vmaf.
11334 @item enable_conf_interval
11335 Enables confidence interval.
11338 This filter also supports the @ref{framesync} options.
11340 On the below examples the input file @file{main.mpg} being processed is
11341 compared with the reference file @file{ref.mpg}.
11344 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
11347 Example with options:
11349 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:enable-transform=1" -f null -
11354 Limits the pixel components values to the specified range [min, max].
11356 The filter accepts the following options:
11360 Lower bound. Defaults to the lowest allowed value for the input.
11363 Upper bound. Defaults to the highest allowed value for the input.
11366 Specify which planes will be processed. Defaults to all available.
11373 The filter accepts the following options:
11377 Set the number of loops. Setting this value to -1 will result in infinite loops.
11381 Set maximal size in number of frames. Default is 0.
11384 Set first frame of loop. Default is 0.
11387 @subsection Examples
11391 Loop single first frame infinitely:
11393 loop=loop=-1:size=1:start=0
11397 Loop single first frame 10 times:
11399 loop=loop=10:size=1:start=0
11403 Loop 10 first frames 5 times:
11405 loop=loop=5:size=10:start=0
11411 Apply a 1D LUT to an input video.
11413 The filter accepts the following options:
11417 Set the 1D LUT file name.
11419 Currently supported formats:
11426 Select interpolation mode.
11428 Available values are:
11432 Use values from the nearest defined point.
11434 Interpolate values using the linear interpolation.
11436 Interpolate values using the cubic interpolation.
11443 Apply a 3D LUT to an input video.
11445 The filter accepts the following options:
11449 Set the 3D LUT file name.
11451 Currently supported formats:
11463 Select interpolation mode.
11465 Available values are:
11469 Use values from the nearest defined point.
11471 Interpolate values using the 8 points defining a cube.
11473 Interpolate values using a tetrahedron.
11477 This filter also supports the @ref{framesync} options.
11481 Turn certain luma values into transparency.
11483 The filter accepts the following options:
11487 Set the luma which will be used as base for transparency.
11488 Default value is @code{0}.
11491 Set the range of luma values to be keyed out.
11492 Default value is @code{0}.
11495 Set the range of softness. Default value is @code{0}.
11496 Use this to control gradual transition from zero to full transparency.
11499 @section lut, lutrgb, lutyuv
11501 Compute a look-up table for binding each pixel component input value
11502 to an output value, and apply it to the input video.
11504 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
11505 to an RGB input video.
11507 These filters accept the following parameters:
11510 set first pixel component expression
11512 set second pixel component expression
11514 set third pixel component expression
11516 set fourth pixel component expression, corresponds to the alpha component
11519 set red component expression
11521 set green component expression
11523 set blue component expression
11525 alpha component expression
11528 set Y/luminance component expression
11530 set U/Cb component expression
11532 set V/Cr component expression
11535 Each of them specifies the expression to use for computing the lookup table for
11536 the corresponding pixel component values.
11538 The exact component associated to each of the @var{c*} options depends on the
11541 The @var{lut} filter requires either YUV or RGB pixel formats in input,
11542 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
11544 The expressions can contain the following constants and functions:
11549 The input width and height.
11552 The input value for the pixel component.
11555 The input value, clipped to the @var{minval}-@var{maxval} range.
11558 The maximum value for the pixel component.
11561 The minimum value for the pixel component.
11564 The negated value for the pixel component value, clipped to the
11565 @var{minval}-@var{maxval} range; it corresponds to the expression
11566 "maxval-clipval+minval".
11569 The computed value in @var{val}, clipped to the
11570 @var{minval}-@var{maxval} range.
11572 @item gammaval(gamma)
11573 The computed gamma correction value of the pixel component value,
11574 clipped to the @var{minval}-@var{maxval} range. It corresponds to the
11576 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
11580 All expressions default to "val".
11582 @subsection Examples
11586 Negate input video:
11588 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
11589 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
11592 The above is the same as:
11594 lutrgb="r=negval:g=negval:b=negval"
11595 lutyuv="y=negval:u=negval:v=negval"
11605 Remove chroma components, turning the video into a graytone image:
11607 lutyuv="u=128:v=128"
11611 Apply a luma burning effect:
11617 Remove green and blue components:
11623 Set a constant alpha channel value on input:
11625 format=rgba,lutrgb=a="maxval-minval/2"
11629 Correct luminance gamma by a factor of 0.5:
11631 lutyuv=y=gammaval(0.5)
11635 Discard least significant bits of luma:
11637 lutyuv=y='bitand(val, 128+64+32)'
11641 Technicolor like effect:
11643 lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
11647 @section lut2, tlut2
11649 The @code{lut2} filter takes two input streams and outputs one
11652 The @code{tlut2} (time lut2) filter takes two consecutive frames
11653 from one single stream.
11655 This filter accepts the following parameters:
11658 set first pixel component expression
11660 set second pixel component expression
11662 set third pixel component expression
11664 set fourth pixel component expression, corresponds to the alpha component
11667 Each of them specifies the expression to use for computing the lookup table for
11668 the corresponding pixel component values.
11670 The exact component associated to each of the @var{c*} options depends on the
11673 The expressions can contain the following constants:
11678 The input width and height.
11681 The first input value for the pixel component.
11684 The second input value for the pixel component.
11687 The first input video bit depth.
11690 The second input video bit depth.
11693 All expressions default to "x".
11695 @subsection Examples
11699 Highlight differences between two RGB video streams:
11701 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)'
11705 Highlight differences between two YUV video streams:
11707 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)'
11711 Show max difference between two video streams:
11713 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)))'
11717 @section maskedclamp
11719 Clamp the first input stream with the second input and third input stream.
11721 Returns the value of first stream to be between second input
11722 stream - @code{undershoot} and third input stream + @code{overshoot}.
11724 This filter accepts the following options:
11727 Default value is @code{0}.
11730 Default value is @code{0}.
11733 Set which planes will be processed as bitmap, unprocessed planes will be
11734 copied from first stream.
11735 By default value 0xf, all planes will be processed.
11738 @section maskedmerge
11740 Merge the first input stream with the second input stream using per pixel
11741 weights in the third input stream.
11743 A value of 0 in the third stream pixel component means that pixel component
11744 from first stream is returned unchanged, while maximum value (eg. 255 for
11745 8-bit videos) means that pixel component from second stream is returned
11746 unchanged. Intermediate values define the amount of merging between both
11747 input stream's pixel components.
11749 This filter accepts the following options:
11752 Set which planes will be processed as bitmap, unprocessed planes will be
11753 copied from first stream.
11754 By default value 0xf, all planes will be processed.
11759 Apply motion-compensation deinterlacing.
11761 It needs one field per frame as input and must thus be used together
11762 with yadif=1/3 or equivalent.
11764 This filter accepts the following options:
11767 Set the deinterlacing mode.
11769 It accepts one of the following values:
11774 use iterative motion estimation
11776 like @samp{slow}, but use multiple reference frames.
11778 Default value is @samp{fast}.
11781 Set the picture field parity assumed for the input video. It must be
11782 one of the following values:
11786 assume top field first
11788 assume bottom field first
11791 Default value is @samp{bff}.
11794 Set per-block quantization parameter (QP) used by the internal
11797 Higher values should result in a smoother motion vector field but less
11798 optimal individual vectors. Default value is 1.
11801 @section mergeplanes
11803 Merge color channel components from several video streams.
11805 The filter accepts up to 4 input streams, and merge selected input
11806 planes to the output video.
11808 This filter accepts the following options:
11811 Set input to output plane mapping. Default is @code{0}.
11813 The mappings is specified as a bitmap. It should be specified as a
11814 hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
11815 mapping for the first plane of the output stream. 'A' sets the number of
11816 the input stream to use (from 0 to 3), and 'a' the plane number of the
11817 corresponding input to use (from 0 to 3). The rest of the mappings is
11818 similar, 'Bb' describes the mapping for the output stream second
11819 plane, 'Cc' describes the mapping for the output stream third plane and
11820 'Dd' describes the mapping for the output stream fourth plane.
11823 Set output pixel format. Default is @code{yuva444p}.
11826 @subsection Examples
11830 Merge three gray video streams of same width and height into single video stream:
11832 [a0][a1][a2]mergeplanes=0x001020:yuv444p
11836 Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
11838 [a0][a1]mergeplanes=0x00010210:yuva444p
11842 Swap Y and A plane in yuva444p stream:
11844 format=yuva444p,mergeplanes=0x03010200:yuva444p
11848 Swap U and V plane in yuv420p stream:
11850 format=yuv420p,mergeplanes=0x000201:yuv420p
11854 Cast a rgb24 clip to yuv444p:
11856 format=rgb24,mergeplanes=0x000102:yuv444p
11862 Estimate and export motion vectors using block matching algorithms.
11863 Motion vectors are stored in frame side data to be used by other filters.
11865 This filter accepts the following options:
11868 Specify the motion estimation method. Accepts one of the following values:
11872 Exhaustive search algorithm.
11874 Three step search algorithm.
11876 Two dimensional logarithmic search algorithm.
11878 New three step search algorithm.
11880 Four step search algorithm.
11882 Diamond search algorithm.
11884 Hexagon-based search algorithm.
11886 Enhanced predictive zonal search algorithm.
11888 Uneven multi-hexagon search algorithm.
11890 Default value is @samp{esa}.
11893 Macroblock size. Default @code{16}.
11896 Search parameter. Default @code{7}.
11899 @section midequalizer
11901 Apply Midway Image Equalization effect using two video streams.
11903 Midway Image Equalization adjusts a pair of images to have the same
11904 histogram, while maintaining their dynamics as much as possible. It's
11905 useful for e.g. matching exposures from a pair of stereo cameras.
11907 This filter has two inputs and one output, which must be of same pixel format, but
11908 may be of different sizes. The output of filter is first input adjusted with
11909 midway histogram of both inputs.
11911 This filter accepts the following option:
11915 Set which planes to process. Default is @code{15}, which is all available planes.
11918 @section minterpolate
11920 Convert the video to specified frame rate using motion interpolation.
11922 This filter accepts the following options:
11925 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}.
11928 Motion interpolation mode. Following values are accepted:
11931 Duplicate previous or next frame for interpolating new ones.
11933 Blend source frames. Interpolated frame is mean of previous and next frames.
11935 Motion compensated interpolation. Following options are effective when this mode is selected:
11939 Motion compensation mode. Following values are accepted:
11942 Overlapped block motion compensation.
11944 Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
11946 Default mode is @samp{obmc}.
11949 Motion estimation mode. Following values are accepted:
11952 Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
11954 Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
11956 Default mode is @samp{bilat}.
11959 The algorithm to be used for motion estimation. Following values are accepted:
11962 Exhaustive search algorithm.
11964 Three step search algorithm.
11966 Two dimensional logarithmic search algorithm.
11968 New three step search algorithm.
11970 Four step search algorithm.
11972 Diamond search algorithm.
11974 Hexagon-based search algorithm.
11976 Enhanced predictive zonal search algorithm.
11978 Uneven multi-hexagon search algorithm.
11980 Default algorithm is @samp{epzs}.
11983 Macroblock size. Default @code{16}.
11986 Motion estimation search parameter. Default @code{32}.
11989 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).
11994 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:
11997 Disable scene change detection.
11999 Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected.
12001 Default method is @samp{fdiff}.
12003 @item scd_threshold
12004 Scene change detection threshold. Default is @code{5.0}.
12009 Mix several video input streams into one video stream.
12011 A description of the accepted options follows.
12015 The number of inputs. If unspecified, it defaults to 2.
12018 Specify weight of each input video stream as sequence.
12019 Each weight is separated by space. If number of weights
12020 is smaller than number of @var{frames} last specified
12021 weight will be used for all remaining unset weights.
12024 Specify scale, if it is set it will be multiplied with sum
12025 of each weight multiplied with pixel values to give final destination
12026 pixel value. By default @var{scale} is auto scaled to sum of weights.
12029 Specify how end of stream is determined.
12032 The duration of the longest input. (default)
12035 The duration of the shortest input.
12038 The duration of the first input.
12042 @section mpdecimate
12044 Drop frames that do not differ greatly from the previous frame in
12045 order to reduce frame rate.
12047 The main use of this filter is for very-low-bitrate encoding
12048 (e.g. streaming over dialup modem), but it could in theory be used for
12049 fixing movies that were inverse-telecined incorrectly.
12051 A description of the accepted options follows.
12055 Set the maximum number of consecutive frames which can be dropped (if
12056 positive), or the minimum interval between dropped frames (if
12057 negative). If the value is 0, the frame is dropped disregarding the
12058 number of previous sequentially dropped frames.
12060 Default value is 0.
12065 Set the dropping threshold values.
12067 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
12068 represent actual pixel value differences, so a threshold of 64
12069 corresponds to 1 unit of difference for each pixel, or the same spread
12070 out differently over the block.
12072 A frame is a candidate for dropping if no 8x8 blocks differ by more
12073 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
12074 meaning the whole image) differ by more than a threshold of @option{lo}.
12076 Default value for @option{hi} is 64*12, default value for @option{lo} is
12077 64*5, and default value for @option{frac} is 0.33.
12083 Negate (invert) the input video.
12085 It accepts the following option:
12090 With value 1, it negates the alpha component, if present. Default value is 0.
12096 Denoise frames using Non-Local Means algorithm.
12098 Each pixel is adjusted by looking for other pixels with similar contexts. This
12099 context similarity is defined by comparing their surrounding patches of size
12100 @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
12103 Note that the research area defines centers for patches, which means some
12104 patches will be made of pixels outside that research area.
12106 The filter accepts the following options.
12110 Set denoising strength.
12116 Same as @option{p} but for chroma planes.
12118 The default value is @var{0} and means automatic.
12124 Same as @option{r} but for chroma planes.
12126 The default value is @var{0} and means automatic.
12131 Deinterlace video using neural network edge directed interpolation.
12133 This filter accepts the following options:
12137 Mandatory option, without binary file filter can not work.
12138 Currently file can be found here:
12139 https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
12142 Set which frames to deinterlace, by default it is @code{all}.
12143 Can be @code{all} or @code{interlaced}.
12146 Set mode of operation.
12148 Can be one of the following:
12152 Use frame flags, both fields.
12154 Use frame flags, single field.
12156 Use top field only.
12158 Use bottom field only.
12160 Use both fields, top first.
12162 Use both fields, bottom first.
12166 Set which planes to process, by default filter process all frames.
12169 Set size of local neighborhood around each pixel, used by the predictor neural
12172 Can be one of the following:
12185 Set the number of neurons in predictor neural network.
12186 Can be one of the following:
12197 Controls the number of different neural network predictions that are blended
12198 together to compute the final output value. Can be @code{fast}, default or
12202 Set which set of weights to use in the predictor.
12203 Can be one of the following:
12207 weights trained to minimize absolute error
12209 weights trained to minimize squared error
12213 Controls whether or not the prescreener neural network is used to decide
12214 which pixels should be processed by the predictor neural network and which
12215 can be handled by simple cubic interpolation.
12216 The prescreener is trained to know whether cubic interpolation will be
12217 sufficient for a pixel or whether it should be predicted by the predictor nn.
12218 The computational complexity of the prescreener nn is much less than that of
12219 the predictor nn. Since most pixels can be handled by cubic interpolation,
12220 using the prescreener generally results in much faster processing.
12221 The prescreener is pretty accurate, so the difference between using it and not
12222 using it is almost always unnoticeable.
12224 Can be one of the following:
12232 Default is @code{new}.
12235 Set various debugging flags.
12240 Force libavfilter not to use any of the specified pixel formats for the
12241 input to the next filter.
12243 It accepts the following parameters:
12247 A '|'-separated list of pixel format names, such as
12248 pix_fmts=yuv420p|monow|rgb24".
12252 @subsection Examples
12256 Force libavfilter to use a format different from @var{yuv420p} for the
12257 input to the vflip filter:
12259 noformat=pix_fmts=yuv420p,vflip
12263 Convert the input video to any of the formats not contained in the list:
12265 noformat=yuv420p|yuv444p|yuv410p
12271 Add noise on video input frame.
12273 The filter accepts the following options:
12281 Set noise seed for specific pixel component or all pixel components in case
12282 of @var{all_seed}. Default value is @code{123457}.
12284 @item all_strength, alls
12285 @item c0_strength, c0s
12286 @item c1_strength, c1s
12287 @item c2_strength, c2s
12288 @item c3_strength, c3s
12289 Set noise strength for specific pixel component or all pixel components in case
12290 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
12292 @item all_flags, allf
12293 @item c0_flags, c0f
12294 @item c1_flags, c1f
12295 @item c2_flags, c2f
12296 @item c3_flags, c3f
12297 Set pixel component flags or set flags for all components if @var{all_flags}.
12298 Available values for component flags are:
12301 averaged temporal noise (smoother)
12303 mix random noise with a (semi)regular pattern
12305 temporal noise (noise pattern changes between frames)
12307 uniform noise (gaussian otherwise)
12311 @subsection Examples
12313 Add temporal and uniform noise to input video:
12315 noise=alls=20:allf=t+u
12320 Normalize RGB video (aka histogram stretching, contrast stretching).
12321 See: https://en.wikipedia.org/wiki/Normalization_(image_processing)
12323 For each channel of each frame, the filter computes the input range and maps
12324 it linearly to the user-specified output range. The output range defaults
12325 to the full dynamic range from pure black to pure white.
12327 Temporal smoothing can be used on the input range to reduce flickering (rapid
12328 changes in brightness) caused when small dark or bright objects enter or leave
12329 the scene. This is similar to the auto-exposure (automatic gain control) on a
12330 video camera, and, like a video camera, it may cause a period of over- or
12331 under-exposure of the video.
12333 The R,G,B channels can be normalized independently, which may cause some
12334 color shifting, or linked together as a single channel, which prevents
12335 color shifting. Linked normalization preserves hue. Independent normalization
12336 does not, so it can be used to remove some color casts. Independent and linked
12337 normalization can be combined in any ratio.
12339 The normalize filter accepts the following options:
12344 Colors which define the output range. The minimum input value is mapped to
12345 the @var{blackpt}. The maximum input value is mapped to the @var{whitept}.
12346 The defaults are black and white respectively. Specifying white for
12347 @var{blackpt} and black for @var{whitept} will give color-inverted,
12348 normalized video. Shades of grey can be used to reduce the dynamic range
12349 (contrast). Specifying saturated colors here can create some interesting
12353 The number of previous frames to use for temporal smoothing. The input range
12354 of each channel is smoothed using a rolling average over the current frame
12355 and the @var{smoothing} previous frames. The default is 0 (no temporal
12359 Controls the ratio of independent (color shifting) channel normalization to
12360 linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully
12361 independent. Defaults to 1.0 (fully independent).
12364 Overall strength of the filter. 1.0 is full strength. 0.0 is a rather
12365 expensive no-op. Defaults to 1.0 (full strength).
12369 @subsection Examples
12371 Stretch video contrast to use the full dynamic range, with no temporal
12372 smoothing; may flicker depending on the source content:
12374 normalize=blackpt=black:whitept=white:smoothing=0
12377 As above, but with 50 frames of temporal smoothing; flicker should be
12378 reduced, depending on the source content:
12380 normalize=blackpt=black:whitept=white:smoothing=50
12383 As above, but with hue-preserving linked channel normalization:
12385 normalize=blackpt=black:whitept=white:smoothing=50:independence=0
12388 As above, but with half strength:
12390 normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
12393 Map the darkest input color to red, the brightest input color to cyan:
12395 normalize=blackpt=red:whitept=cyan
12400 Pass the video source unchanged to the output.
12403 Optical Character Recognition
12405 This filter uses Tesseract for optical character recognition. To enable
12406 compilation of this filter, you need to configure FFmpeg with
12407 @code{--enable-libtesseract}.
12409 It accepts the following options:
12413 Set datapath to tesseract data. Default is to use whatever was
12414 set at installation.
12417 Set language, default is "eng".
12420 Set character whitelist.
12423 Set character blacklist.
12426 The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
12430 Apply a video transform using libopencv.
12432 To enable this filter, install the libopencv library and headers and
12433 configure FFmpeg with @code{--enable-libopencv}.
12435 It accepts the following parameters:
12440 The name of the libopencv filter to apply.
12442 @item filter_params
12443 The parameters to pass to the libopencv filter. If not specified, the default
12444 values are assumed.
12448 Refer to the official libopencv documentation for more precise
12450 @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
12452 Several libopencv filters are supported; see the following subsections.
12457 Dilate an image by using a specific structuring element.
12458 It corresponds to the libopencv function @code{cvDilate}.
12460 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
12462 @var{struct_el} represents a structuring element, and has the syntax:
12463 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
12465 @var{cols} and @var{rows} represent the number of columns and rows of
12466 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
12467 point, and @var{shape} the shape for the structuring element. @var{shape}
12468 must be "rect", "cross", "ellipse", or "custom".
12470 If the value for @var{shape} is "custom", it must be followed by a
12471 string of the form "=@var{filename}". The file with name
12472 @var{filename} is assumed to represent a binary image, with each
12473 printable character corresponding to a bright pixel. When a custom
12474 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
12475 or columns and rows of the read file are assumed instead.
12477 The default value for @var{struct_el} is "3x3+0x0/rect".
12479 @var{nb_iterations} specifies the number of times the transform is
12480 applied to the image, and defaults to 1.
12484 # Use the default values
12487 # Dilate using a structuring element with a 5x5 cross, iterating two times
12488 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
12490 # Read the shape from the file diamond.shape, iterating two times.
12491 # The file diamond.shape may contain a pattern of characters like this
12497 # The specified columns and rows are ignored
12498 # but the anchor point coordinates are not
12499 ocv=dilate:0x0+2x2/custom=diamond.shape|2
12504 Erode an image by using a specific structuring element.
12505 It corresponds to the libopencv function @code{cvErode}.
12507 It accepts the parameters: @var{struct_el}:@var{nb_iterations},
12508 with the same syntax and semantics as the @ref{dilate} filter.
12512 Smooth the input video.
12514 The filter takes the following parameters:
12515 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
12517 @var{type} is the type of smooth filter to apply, and must be one of
12518 the following values: "blur", "blur_no_scale", "median", "gaussian",
12519 or "bilateral". The default value is "gaussian".
12521 The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
12522 depend on the smooth type. @var{param1} and
12523 @var{param2} accept integer positive values or 0. @var{param3} and
12524 @var{param4} accept floating point values.
12526 The default value for @var{param1} is 3. The default value for the
12527 other parameters is 0.
12529 These parameters correspond to the parameters assigned to the
12530 libopencv function @code{cvSmooth}.
12532 @section oscilloscope
12534 2D Video Oscilloscope.
12536 Useful to measure spatial impulse, step responses, chroma delays, etc.
12538 It accepts the following parameters:
12542 Set scope center x position.
12545 Set scope center y position.
12548 Set scope size, relative to frame diagonal.
12551 Set scope tilt/rotation.
12557 Set trace center x position.
12560 Set trace center y position.
12563 Set trace width, relative to width of frame.
12566 Set trace height, relative to height of frame.
12569 Set which components to trace. By default it traces first three components.
12572 Draw trace grid. By default is enabled.
12575 Draw some statistics. By default is enabled.
12578 Draw scope. By default is enabled.
12581 @subsection Examples
12585 Inspect full first row of video frame.
12587 oscilloscope=x=0.5:y=0:s=1
12591 Inspect full last row of video frame.
12593 oscilloscope=x=0.5:y=1:s=1
12597 Inspect full 5th line of video frame of height 1080.
12599 oscilloscope=x=0.5:y=5/1080:s=1
12603 Inspect full last column of video frame.
12605 oscilloscope=x=1:y=0.5:s=1:t=1
12613 Overlay one video on top of another.
12615 It takes two inputs and has one output. The first input is the "main"
12616 video on which the second input is overlaid.
12618 It accepts the following parameters:
12620 A description of the accepted options follows.
12625 Set the expression for the x and y coordinates of the overlaid video
12626 on the main video. Default value is "0" for both expressions. In case
12627 the expression is invalid, it is set to a huge value (meaning that the
12628 overlay will not be displayed within the output visible area).
12631 See @ref{framesync}.
12634 Set when the expressions for @option{x}, and @option{y} are evaluated.
12636 It accepts the following values:
12639 only evaluate expressions once during the filter initialization or
12640 when a command is processed
12643 evaluate expressions for each incoming frame
12646 Default value is @samp{frame}.
12649 See @ref{framesync}.
12652 Set the format for the output video.
12654 It accepts the following values:
12657 force YUV420 output
12660 force YUV422 output
12663 force YUV444 output
12666 force packed RGB output
12669 force planar RGB output
12672 automatically pick format
12675 Default value is @samp{yuv420}.
12678 See @ref{framesync}.
12681 Set format of alpha of the overlaid video, it can be @var{straight} or
12682 @var{premultiplied}. Default is @var{straight}.
12685 The @option{x}, and @option{y} expressions can contain the following
12691 The main input width and height.
12695 The overlay input width and height.
12699 The computed values for @var{x} and @var{y}. They are evaluated for
12704 horizontal and vertical chroma subsample values of the output
12705 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
12709 the number of input frame, starting from 0
12712 the position in the file of the input frame, NAN if unknown
12715 The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
12719 This filter also supports the @ref{framesync} options.
12721 Note that the @var{n}, @var{pos}, @var{t} variables are available only
12722 when evaluation is done @emph{per frame}, and will evaluate to NAN
12723 when @option{eval} is set to @samp{init}.
12725 Be aware that frames are taken from each input video in timestamp
12726 order, hence, if their initial timestamps differ, it is a good idea
12727 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
12728 have them begin in the same zero timestamp, as the example for
12729 the @var{movie} filter does.
12731 You can chain together more overlays but you should test the
12732 efficiency of such approach.
12734 @subsection Commands
12736 This filter supports the following commands:
12740 Modify the x and y of the overlay input.
12741 The command accepts the same syntax of the corresponding option.
12743 If the specified expression is not valid, it is kept at its current
12747 @subsection Examples
12751 Draw the overlay at 10 pixels from the bottom right corner of the main
12754 overlay=main_w-overlay_w-10:main_h-overlay_h-10
12757 Using named options the example above becomes:
12759 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
12763 Insert a transparent PNG logo in the bottom left corner of the input,
12764 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
12766 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
12770 Insert 2 different transparent PNG logos (second logo on bottom
12771 right corner) using the @command{ffmpeg} tool:
12773 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
12777 Add a transparent color layer on top of the main video; @code{WxH}
12778 must specify the size of the main input to the overlay filter:
12780 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
12784 Play an original video and a filtered version (here with the deshake
12785 filter) side by side using the @command{ffplay} tool:
12787 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
12790 The above command is the same as:
12792 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
12796 Make a sliding overlay appearing from the left to the right top part of the
12797 screen starting since time 2:
12799 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
12803 Compose output by putting two input videos side to side:
12805 ffmpeg -i left.avi -i right.avi -filter_complex "
12806 nullsrc=size=200x100 [background];
12807 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
12808 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
12809 [background][left] overlay=shortest=1 [background+left];
12810 [background+left][right] overlay=shortest=1:x=100 [left+right]
12815 Mask 10-20 seconds of a video by applying the delogo filter to a section
12817 ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
12818 -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]'
12823 Chain several overlays in cascade:
12825 nullsrc=s=200x200 [bg];
12826 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
12827 [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
12828 [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
12829 [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
12830 [in3] null, [mid2] overlay=100:100 [out0]
12837 Apply Overcomplete Wavelet denoiser.
12839 The filter accepts the following options:
12845 Larger depth values will denoise lower frequency components more, but
12846 slow down filtering.
12848 Must be an int in the range 8-16, default is @code{8}.
12850 @item luma_strength, ls
12853 Must be a double value in the range 0-1000, default is @code{1.0}.
12855 @item chroma_strength, cs
12856 Set chroma strength.
12858 Must be a double value in the range 0-1000, default is @code{1.0}.
12864 Add paddings to the input image, and place the original input at the
12865 provided @var{x}, @var{y} coordinates.
12867 It accepts the following parameters:
12872 Specify an expression for the size of the output image with the
12873 paddings added. If the value for @var{width} or @var{height} is 0, the
12874 corresponding input size is used for the output.
12876 The @var{width} expression can reference the value set by the
12877 @var{height} expression, and vice versa.
12879 The default value of @var{width} and @var{height} is 0.
12883 Specify the offsets to place the input image at within the padded area,
12884 with respect to the top/left border of the output image.
12886 The @var{x} expression can reference the value set by the @var{y}
12887 expression, and vice versa.
12889 The default value of @var{x} and @var{y} is 0.
12891 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
12892 so the input image is centered on the padded area.
12895 Specify the color of the padded area. For the syntax of this option,
12896 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
12897 manual,ffmpeg-utils}.
12899 The default value of @var{color} is "black".
12902 Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression.
12904 It accepts the following values:
12908 Only evaluate expressions once during the filter initialization or when
12909 a command is processed.
12912 Evaluate expressions for each incoming frame.
12916 Default value is @samp{init}.
12919 Pad to aspect instead to a resolution.
12923 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
12924 options are expressions containing the following constants:
12929 The input video width and height.
12933 These are the same as @var{in_w} and @var{in_h}.
12937 The output width and height (the size of the padded area), as
12938 specified by the @var{width} and @var{height} expressions.
12942 These are the same as @var{out_w} and @var{out_h}.
12946 The x and y offsets as specified by the @var{x} and @var{y}
12947 expressions, or NAN if not yet specified.
12950 same as @var{iw} / @var{ih}
12953 input sample aspect ratio
12956 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
12960 The horizontal and vertical chroma subsample values. For example for the
12961 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
12964 @subsection Examples
12968 Add paddings with the color "violet" to the input video. The output video
12969 size is 640x480, and the top-left corner of the input video is placed at
12972 pad=640:480:0:40:violet
12975 The example above is equivalent to the following command:
12977 pad=width=640:height=480:x=0:y=40:color=violet
12981 Pad the input to get an output with dimensions increased by 3/2,
12982 and put the input video at the center of the padded area:
12984 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
12988 Pad the input to get a squared output with size equal to the maximum
12989 value between the input width and height, and put the input video at
12990 the center of the padded area:
12992 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
12996 Pad the input to get a final w/h ratio of 16:9:
12998 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
13002 In case of anamorphic video, in order to set the output display aspect
13003 correctly, it is necessary to use @var{sar} in the expression,
13004 according to the relation:
13006 (ih * X / ih) * sar = output_dar
13007 X = output_dar / sar
13010 Thus the previous example needs to be modified to:
13012 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
13016 Double the output size and put the input video in the bottom-right
13017 corner of the output padded area:
13019 pad="2*iw:2*ih:ow-iw:oh-ih"
13023 @anchor{palettegen}
13024 @section palettegen
13026 Generate one palette for a whole video stream.
13028 It accepts the following options:
13032 Set the maximum number of colors to quantize in the palette.
13033 Note: the palette will still contain 256 colors; the unused palette entries
13036 @item reserve_transparent
13037 Create a palette of 255 colors maximum and reserve the last one for
13038 transparency. Reserving the transparency color is useful for GIF optimization.
13039 If not set, the maximum of colors in the palette will be 256. You probably want
13040 to disable this option for a standalone image.
13043 @item transparency_color
13044 Set the color that will be used as background for transparency.
13047 Set statistics mode.
13049 It accepts the following values:
13052 Compute full frame histograms.
13054 Compute histograms only for the part that differs from previous frame. This
13055 might be relevant to give more importance to the moving part of your input if
13056 the background is static.
13058 Compute new histogram for each frame.
13061 Default value is @var{full}.
13064 The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
13065 (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
13066 color quantization of the palette. This information is also visible at
13067 @var{info} logging level.
13069 @subsection Examples
13073 Generate a representative palette of a given video using @command{ffmpeg}:
13075 ffmpeg -i input.mkv -vf palettegen palette.png
13079 @section paletteuse
13081 Use a palette to downsample an input video stream.
13083 The filter takes two inputs: one video stream and a palette. The palette must
13084 be a 256 pixels image.
13086 It accepts the following options:
13090 Select dithering mode. Available algorithms are:
13093 Ordered 8x8 bayer dithering (deterministic)
13095 Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
13096 Note: this dithering is sometimes considered "wrong" and is included as a
13098 @item floyd_steinberg
13099 Floyd and Steingberg dithering (error diffusion)
13101 Frankie Sierra dithering v2 (error diffusion)
13103 Frankie Sierra dithering v2 "Lite" (error diffusion)
13106 Default is @var{sierra2_4a}.
13109 When @var{bayer} dithering is selected, this option defines the scale of the
13110 pattern (how much the crosshatch pattern is visible). A low value means more
13111 visible pattern for less banding, and higher value means less visible pattern
13112 at the cost of more banding.
13114 The option must be an integer value in the range [0,5]. Default is @var{2}.
13117 If set, define the zone to process
13121 Only the changing rectangle will be reprocessed. This is similar to GIF
13122 cropping/offsetting compression mechanism. This option can be useful for speed
13123 if only a part of the image is changing, and has use cases such as limiting the
13124 scope of the error diffusal @option{dither} to the rectangle that bounds the
13125 moving scene (it leads to more deterministic output if the scene doesn't change
13126 much, and as a result less moving noise and better GIF compression).
13129 Default is @var{none}.
13132 Take new palette for each output frame.
13134 @item alpha_threshold
13135 Sets the alpha threshold for transparency. Alpha values above this threshold
13136 will be treated as completely opaque, and values below this threshold will be
13137 treated as completely transparent.
13139 The option must be an integer value in the range [0,255]. Default is @var{128}.
13142 @subsection Examples
13146 Use a palette (generated for example with @ref{palettegen}) to encode a GIF
13147 using @command{ffmpeg}:
13149 ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
13153 @section perspective
13155 Correct perspective of video not recorded perpendicular to the screen.
13157 A description of the accepted parameters follows.
13168 Set coordinates expression for top left, top right, bottom left and bottom right corners.
13169 Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
13170 If the @code{sense} option is set to @code{source}, then the specified points will be sent
13171 to the corners of the destination. If the @code{sense} option is set to @code{destination},
13172 then the corners of the source will be sent to the specified coordinates.
13174 The expressions can use the following variables:
13179 the width and height of video frame.
13183 Output frame count.
13186 @item interpolation
13187 Set interpolation for perspective correction.
13189 It accepts the following values:
13195 Default value is @samp{linear}.
13198 Set interpretation of coordinate options.
13200 It accepts the following values:
13204 Send point in the source specified by the given coordinates to
13205 the corners of the destination.
13207 @item 1, destination
13209 Send the corners of the source to the point in the destination specified
13210 by the given coordinates.
13212 Default value is @samp{source}.
13216 Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
13218 It accepts the following values:
13221 only evaluate expressions once during the filter initialization or
13222 when a command is processed
13225 evaluate expressions for each incoming frame
13228 Default value is @samp{init}.
13233 Delay interlaced video by one field time so that the field order changes.
13235 The intended use is to fix PAL movies that have been captured with the
13236 opposite field order to the film-to-video transfer.
13238 A description of the accepted parameters follows.
13244 It accepts the following values:
13247 Capture field order top-first, transfer bottom-first.
13248 Filter will delay the bottom field.
13251 Capture field order bottom-first, transfer top-first.
13252 Filter will delay the top field.
13255 Capture and transfer with the same field order. This mode only exists
13256 for the documentation of the other options to refer to, but if you
13257 actually select it, the filter will faithfully do nothing.
13260 Capture field order determined automatically by field flags, transfer
13262 Filter selects among @samp{t} and @samp{b} modes on a frame by frame
13263 basis using field flags. If no field information is available,
13264 then this works just like @samp{u}.
13267 Capture unknown or varying, transfer opposite.
13268 Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
13269 analyzing the images and selecting the alternative that produces best
13270 match between the fields.
13273 Capture top-first, transfer unknown or varying.
13274 Filter selects among @samp{t} and @samp{p} using image analysis.
13277 Capture bottom-first, transfer unknown or varying.
13278 Filter selects among @samp{b} and @samp{p} using image analysis.
13281 Capture determined by field flags, transfer unknown or varying.
13282 Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
13283 image analysis. If no field information is available, then this works just
13284 like @samp{U}. This is the default mode.
13287 Both capture and transfer unknown or varying.
13288 Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
13292 @section pixdesctest
13294 Pixel format descriptor test filter, mainly useful for internal
13295 testing. The output video should be equal to the input video.
13299 format=monow, pixdesctest
13302 can be used to test the monowhite pixel format descriptor definition.
13306 Display sample values of color channels. Mainly useful for checking color
13307 and levels. Minimum supported resolution is 640x480.
13309 The filters accept the following options:
13313 Set scope X position, relative offset on X axis.
13316 Set scope Y position, relative offset on Y axis.
13325 Set window opacity. This window also holds statistics about pixel area.
13328 Set window X position, relative offset on X axis.
13331 Set window Y position, relative offset on Y axis.
13336 Enable the specified chain of postprocessing subfilters using libpostproc. This
13337 library should be automatically selected with a GPL build (@code{--enable-gpl}).
13338 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
13339 Each subfilter and some options have a short and a long name that can be used
13340 interchangeably, i.e. dr/dering are the same.
13342 The filters accept the following options:
13346 Set postprocessing subfilters string.
13349 All subfilters share common options to determine their scope:
13353 Honor the quality commands for this subfilter.
13356 Do chrominance filtering, too (default).
13359 Do luminance filtering only (no chrominance).
13362 Do chrominance filtering only (no luminance).
13365 These options can be appended after the subfilter name, separated by a '|'.
13367 Available subfilters are:
13370 @item hb/hdeblock[|difference[|flatness]]
13371 Horizontal deblocking filter
13374 Difference factor where higher values mean more deblocking (default: @code{32}).
13376 Flatness threshold where lower values mean more deblocking (default: @code{39}).
13379 @item vb/vdeblock[|difference[|flatness]]
13380 Vertical deblocking filter
13383 Difference factor where higher values mean more deblocking (default: @code{32}).
13385 Flatness threshold where lower values mean more deblocking (default: @code{39}).
13388 @item ha/hadeblock[|difference[|flatness]]
13389 Accurate horizontal deblocking filter
13392 Difference factor where higher values mean more deblocking (default: @code{32}).
13394 Flatness threshold where lower values mean more deblocking (default: @code{39}).
13397 @item va/vadeblock[|difference[|flatness]]
13398 Accurate vertical deblocking filter
13401 Difference factor where higher values mean more deblocking (default: @code{32}).
13403 Flatness threshold where lower values mean more deblocking (default: @code{39}).
13407 The horizontal and vertical deblocking filters share the difference and
13408 flatness values so you cannot set different horizontal and vertical
13412 @item h1/x1hdeblock
13413 Experimental horizontal deblocking filter
13415 @item v1/x1vdeblock
13416 Experimental vertical deblocking filter
13421 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
13424 larger -> stronger filtering
13426 larger -> stronger filtering
13428 larger -> stronger filtering
13431 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
13434 Stretch luminance to @code{0-255}.
13437 @item lb/linblenddeint
13438 Linear blend deinterlacing filter that deinterlaces the given block by
13439 filtering all lines with a @code{(1 2 1)} filter.
13441 @item li/linipoldeint
13442 Linear interpolating deinterlacing filter that deinterlaces the given block by
13443 linearly interpolating every second line.
13445 @item ci/cubicipoldeint
13446 Cubic interpolating deinterlacing filter deinterlaces the given block by
13447 cubically interpolating every second line.
13449 @item md/mediandeint
13450 Median deinterlacing filter that deinterlaces the given block by applying a
13451 median filter to every second line.
13453 @item fd/ffmpegdeint
13454 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
13455 second line with a @code{(-1 4 2 4 -1)} filter.
13458 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
13459 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
13461 @item fq/forceQuant[|quantizer]
13462 Overrides the quantizer table from the input with the constant quantizer you
13470 Default pp filter combination (@code{hb|a,vb|a,dr|a})
13473 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
13476 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
13479 @subsection Examples
13483 Apply horizontal and vertical deblocking, deringing and automatic
13484 brightness/contrast:
13490 Apply default filters without brightness/contrast correction:
13496 Apply default filters and temporal denoiser:
13498 pp=default/tmpnoise|1|2|3
13502 Apply deblocking on luminance only, and switch vertical deblocking on or off
13503 automatically depending on available CPU time:
13510 Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
13511 similar to spp = 6 with 7 point DCT, where only the center sample is
13514 The filter accepts the following options:
13518 Force a constant quantization parameter. It accepts an integer in range
13519 0 to 63. If not set, the filter will use the QP from the video stream
13523 Set thresholding mode. Available modes are:
13527 Set hard thresholding.
13529 Set soft thresholding (better de-ringing effect, but likely blurrier).
13531 Set medium thresholding (good results, default).
13535 @section premultiply
13536 Apply alpha premultiply effect to input video stream using first plane
13537 of second stream as alpha.
13539 Both streams must have same dimensions and same pixel format.
13541 The filter accepts the following option:
13545 Set which planes will be processed, unprocessed planes will be copied.
13546 By default value 0xf, all planes will be processed.
13549 Do not require 2nd input for processing, instead use alpha plane from input stream.
13553 Apply prewitt operator to input video stream.
13555 The filter accepts the following option:
13559 Set which planes will be processed, unprocessed planes will be copied.
13560 By default value 0xf, all planes will be processed.
13563 Set value which will be multiplied with filtered result.
13566 Set value which will be added to filtered result.
13569 @anchor{program_opencl}
13570 @section program_opencl
13572 Filter video using an OpenCL program.
13577 OpenCL program source file.
13580 Kernel name in program.
13583 Number of inputs to the filter. Defaults to 1.
13586 Size of output frames. Defaults to the same as the first input.
13590 The program source file must contain a kernel function with the given name,
13591 which will be run once for each plane of the output. Each run on a plane
13592 gets enqueued as a separate 2D global NDRange with one work-item for each
13593 pixel to be generated. The global ID offset for each work-item is therefore
13594 the coordinates of a pixel in the destination image.
13596 The kernel function needs to take the following arguments:
13599 Destination image, @var{__write_only image2d_t}.
13601 This image will become the output; the kernel should write all of it.
13603 Frame index, @var{unsigned int}.
13605 This is a counter starting from zero and increasing by one for each frame.
13607 Source images, @var{__read_only image2d_t}.
13609 These are the most recent images on each input. The kernel may read from
13610 them to generate the output, but they can't be written to.
13617 Copy the input to the output (output must be the same size as the input).
13619 __kernel void copy(__write_only image2d_t destination,
13620 unsigned int index,
13621 __read_only image2d_t source)
13623 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
13625 int2 location = (int2)(get_global_id(0), get_global_id(1));
13627 float4 value = read_imagef(source, sampler, location);
13629 write_imagef(destination, location, value);
13634 Apply a simple transformation, rotating the input by an amount increasing
13635 with the index counter. Pixel values are linearly interpolated by the
13636 sampler, and the output need not have the same dimensions as the input.
13638 __kernel void rotate_image(__write_only image2d_t dst,
13639 unsigned int index,
13640 __read_only image2d_t src)
13642 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
13643 CLK_FILTER_LINEAR);
13645 float angle = (float)index / 100.0f;
13647 float2 dst_dim = convert_float2(get_image_dim(dst));
13648 float2 src_dim = convert_float2(get_image_dim(src));
13650 float2 dst_cen = dst_dim / 2.0f;
13651 float2 src_cen = src_dim / 2.0f;
13653 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
13655 float2 dst_pos = convert_float2(dst_loc) - dst_cen;
13657 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
13658 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
13660 src_pos = src_pos * src_dim / dst_dim;
13662 float2 src_loc = src_pos + src_cen;
13664 if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
13665 src_loc.x > src_dim.x || src_loc.y > src_dim.y)
13666 write_imagef(dst, dst_loc, 0.5f);
13668 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
13673 Blend two inputs together, with the amount of each input used varying
13674 with the index counter.
13676 __kernel void blend_images(__write_only image2d_t dst,
13677 unsigned int index,
13678 __read_only image2d_t src1,
13679 __read_only image2d_t src2)
13681 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
13682 CLK_FILTER_LINEAR);
13684 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
13686 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
13687 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
13688 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
13690 float4 val1 = read_imagef(src1, sampler, src1_loc);
13691 float4 val2 = read_imagef(src2, sampler, src2_loc);
13693 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
13699 @section pseudocolor
13701 Alter frame colors in video with pseudocolors.
13703 This filter accept the following options:
13707 set pixel first component expression
13710 set pixel second component expression
13713 set pixel third component expression
13716 set pixel fourth component expression, corresponds to the alpha component
13719 set component to use as base for altering colors
13722 Each of them specifies the expression to use for computing the lookup table for
13723 the corresponding pixel component values.
13725 The expressions can contain the following constants and functions:
13730 The input width and height.
13733 The input value for the pixel component.
13735 @item ymin, umin, vmin, amin
13736 The minimum allowed component value.
13738 @item ymax, umax, vmax, amax
13739 The maximum allowed component value.
13742 All expressions default to "val".
13744 @subsection Examples
13748 Change too high luma values to gradient:
13750 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'"
13756 Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
13757 Ratio) between two input videos.
13759 This filter takes in input two input videos, the first input is
13760 considered the "main" source and is passed unchanged to the
13761 output. The second input is used as a "reference" video for computing
13764 Both video inputs must have the same resolution and pixel format for
13765 this filter to work correctly. Also it assumes that both inputs
13766 have the same number of frames, which are compared one by one.
13768 The obtained average PSNR is printed through the logging system.
13770 The filter stores the accumulated MSE (mean squared error) of each
13771 frame, and at the end of the processing it is averaged across all frames
13772 equally, and the following formula is applied to obtain the PSNR:
13775 PSNR = 10*log10(MAX^2/MSE)
13778 Where MAX is the average of the maximum values of each component of the
13781 The description of the accepted parameters follows.
13784 @item stats_file, f
13785 If specified the filter will use the named file to save the PSNR of
13786 each individual frame. When filename equals "-" the data is sent to
13789 @item stats_version
13790 Specifies which version of the stats file format to use. Details of
13791 each format are written below.
13792 Default value is 1.
13794 @item stats_add_max
13795 Determines whether the max value is output to the stats log.
13796 Default value is 0.
13797 Requires stats_version >= 2. If this is set and stats_version < 2,
13798 the filter will return an error.
13801 This filter also supports the @ref{framesync} options.
13803 The file printed if @var{stats_file} is selected, contains a sequence of
13804 key/value pairs of the form @var{key}:@var{value} for each compared
13807 If a @var{stats_version} greater than 1 is specified, a header line precedes
13808 the list of per-frame-pair stats, with key value pairs following the frame
13809 format with the following parameters:
13812 @item psnr_log_version
13813 The version of the log file format. Will match @var{stats_version}.
13816 A comma separated list of the per-frame-pair parameters included in
13820 A description of each shown per-frame-pair parameter follows:
13824 sequential number of the input frame, starting from 1
13827 Mean Square Error pixel-by-pixel average difference of the compared
13828 frames, averaged over all the image components.
13830 @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
13831 Mean Square Error pixel-by-pixel average difference of the compared
13832 frames for the component specified by the suffix.
13834 @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
13835 Peak Signal to Noise ratio of the compared frames for the component
13836 specified by the suffix.
13838 @item max_avg, max_y, max_u, max_v
13839 Maximum allowed value for each channel, and average over all
13845 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
13846 [main][ref] psnr="stats_file=stats.log" [out]
13849 On this example the input file being processed is compared with the
13850 reference file @file{ref_movie.mpg}. The PSNR of each individual frame
13851 is stored in @file{stats.log}.
13856 Pulldown reversal (inverse telecine) filter, capable of handling mixed
13857 hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
13860 The pullup filter is designed to take advantage of future context in making
13861 its decisions. This filter is stateless in the sense that it does not lock
13862 onto a pattern to follow, but it instead looks forward to the following
13863 fields in order to identify matches and rebuild progressive frames.
13865 To produce content with an even framerate, insert the fps filter after
13866 pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
13867 @code{fps=24} for 30fps and the (rare) telecined 25fps input.
13869 The filter accepts the following options:
13876 These options set the amount of "junk" to ignore at the left, right, top, and
13877 bottom of the image, respectively. Left and right are in units of 8 pixels,
13878 while top and bottom are in units of 2 lines.
13879 The default is 8 pixels on each side.
13882 Set the strict breaks. Setting this option to 1 will reduce the chances of
13883 filter generating an occasional mismatched frame, but it may also cause an
13884 excessive number of frames to be dropped during high motion sequences.
13885 Conversely, setting it to -1 will make filter match fields more easily.
13886 This may help processing of video where there is slight blurring between
13887 the fields, but may also cause there to be interlaced frames in the output.
13888 Default value is @code{0}.
13891 Set the metric plane to use. It accepts the following values:
13897 Use chroma blue plane.
13900 Use chroma red plane.
13903 This option may be set to use chroma plane instead of the default luma plane
13904 for doing filter's computations. This may improve accuracy on very clean
13905 source material, but more likely will decrease accuracy, especially if there
13906 is chroma noise (rainbow effect) or any grayscale video.
13907 The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
13908 load and make pullup usable in realtime on slow machines.
13911 For best results (without duplicated frames in the output file) it is
13912 necessary to change the output frame rate. For example, to inverse
13913 telecine NTSC input:
13915 ffmpeg -i input -vf pullup -r 24000/1001 ...
13920 Change video quantization parameters (QP).
13922 The filter accepts the following option:
13926 Set expression for quantization parameter.
13929 The expression is evaluated through the eval API and can contain, among others,
13930 the following constants:
13934 1 if index is not 129, 0 otherwise.
13937 Sequential index starting from -129 to 128.
13940 @subsection Examples
13944 Some equation like:
13952 Flush video frames from internal cache of frames into a random order.
13953 No frame is discarded.
13954 Inspired by @ref{frei0r} nervous filter.
13958 Set size in number of frames of internal cache, in range from @code{2} to
13959 @code{512}. Default is @code{30}.
13962 Set seed for random number generator, must be an integer included between
13963 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
13964 less than @code{0}, the filter will try to use a good random seed on a
13968 @section readeia608
13970 Read closed captioning (EIA-608) information from the top lines of a video frame.
13972 This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and
13973 @code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line
13974 with EIA-608 data (starting from 0). A description of each metadata value follows:
13977 @item lavfi.readeia608.X.cc
13978 The two bytes stored as EIA-608 data (printed in hexadecimal).
13980 @item lavfi.readeia608.X.line
13981 The number of the line on which the EIA-608 data was identified and read.
13984 This filter accepts the following options:
13988 Set the line to start scanning for EIA-608 data. Default is @code{0}.
13991 Set the line to end scanning for EIA-608 data. Default is @code{29}.
13994 Set minimal acceptable amplitude change for sync codes detection.
13995 Default is @code{0.2}. Allowed range is @code{[0.001 - 1]}.
13998 Set the ratio of width reserved for sync code detection.
13999 Default is @code{0.27}. Allowed range is @code{[0.01 - 0.7]}.
14002 Set the max peaks height difference for sync code detection.
14003 Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
14006 Set max peaks period difference for sync code detection.
14007 Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
14010 Set the first two max start code bits differences.
14011 Default is @code{0.02}. Allowed range is @code{[0.0 - 0.5]}.
14014 Set the minimum ratio of bits height compared to 3rd start code bit.
14015 Default is @code{0.75}. Allowed range is @code{[0.01 - 1]}.
14018 Set the white color threshold. Default is @code{0.35}. Allowed range is @code{[0.1 - 1]}.
14021 Set the black color threshold. Default is @code{0.15}. Allowed range is @code{[0.0 - 0.5]}.
14024 Enable checking the parity bit. In the event of a parity error, the filter will output
14025 @code{0x00} for that character. Default is false.
14028 @subsection Examples
14032 Output a csv with presentation time and the first two lines of identified EIA-608 captioning data.
14034 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
14040 Read vertical interval timecode (VITC) information from the top lines of a
14043 The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
14044 timecode value, if a valid timecode has been detected. Further metadata key
14045 @code{lavfi.readvitc.found} is set to 0/1 depending on whether
14046 timecode data has been found or not.
14048 This filter accepts the following options:
14052 Set the maximum number of lines to scan for VITC data. If the value is set to
14053 @code{-1} the full video frame is scanned. Default is @code{45}.
14056 Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
14057 default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
14060 Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
14061 default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
14064 @subsection Examples
14068 Detect and draw VITC data onto the video frame; if no valid VITC is detected,
14069 draw @code{--:--:--:--} as a placeholder:
14071 ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
14077 Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
14079 Destination pixel at position (X, Y) will be picked from source (x, y) position
14080 where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
14081 value for pixel will be used for destination pixel.
14083 Xmap and Ymap input video streams must be of same dimensions. Output video stream
14084 will have Xmap/Ymap video stream dimensions.
14085 Xmap and Ymap input video streams are 16bit depth, single channel.
14087 @section removegrain
14089 The removegrain filter is a spatial denoiser for progressive video.
14093 Set mode for the first plane.
14096 Set mode for the second plane.
14099 Set mode for the third plane.
14102 Set mode for the fourth plane.
14105 Range of mode is from 0 to 24. Description of each mode follows:
14109 Leave input plane unchanged. Default.
14112 Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
14115 Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
14118 Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
14121 Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
14122 This is equivalent to a median filter.
14125 Line-sensitive clipping giving the minimal change.
14128 Line-sensitive clipping, intermediate.
14131 Line-sensitive clipping, intermediate.
14134 Line-sensitive clipping, intermediate.
14137 Line-sensitive clipping on a line where the neighbours pixels are the closest.
14140 Replaces the target pixel with the closest neighbour.
14143 [1 2 1] horizontal and vertical kernel blur.
14149 Bob mode, interpolates top field from the line where the neighbours
14150 pixels are the closest.
14153 Bob mode, interpolates bottom field from the line where the neighbours
14154 pixels are the closest.
14157 Bob mode, interpolates top field. Same as 13 but with a more complicated
14158 interpolation formula.
14161 Bob mode, interpolates bottom field. Same as 14 but with a more complicated
14162 interpolation formula.
14165 Clips the pixel with the minimum and maximum of respectively the maximum and
14166 minimum of each pair of opposite neighbour pixels.
14169 Line-sensitive clipping using opposite neighbours whose greatest distance from
14170 the current pixel is minimal.
14173 Replaces the pixel with the average of its 8 neighbours.
14176 Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
14179 Clips pixels using the averages of opposite neighbour.
14182 Same as mode 21 but simpler and faster.
14185 Small edge and halo removal, but reputed useless.
14191 @section removelogo
14193 Suppress a TV station logo, using an image file to determine which
14194 pixels comprise the logo. It works by filling in the pixels that
14195 comprise the logo with neighboring pixels.
14197 The filter accepts the following options:
14201 Set the filter bitmap file, which can be any image format supported by
14202 libavformat. The width and height of the image file must match those of the
14203 video stream being processed.
14206 Pixels in the provided bitmap image with a value of zero are not
14207 considered part of the logo, non-zero pixels are considered part of
14208 the logo. If you use white (255) for the logo and black (0) for the
14209 rest, you will be safe. For making the filter bitmap, it is
14210 recommended to take a screen capture of a black frame with the logo
14211 visible, and then using a threshold filter followed by the erode
14212 filter once or twice.
14214 If needed, little splotches can be fixed manually. Remember that if
14215 logo pixels are not covered, the filter quality will be much
14216 reduced. Marking too many pixels as part of the logo does not hurt as
14217 much, but it will increase the amount of blurring needed to cover over
14218 the image and will destroy more information than necessary, and extra
14219 pixels will slow things down on a large logo.
14221 @section repeatfields
14223 This filter uses the repeat_field flag from the Video ES headers and hard repeats
14224 fields based on its value.
14228 Reverse a video clip.
14230 Warning: This filter requires memory to buffer the entire clip, so trimming
14233 @subsection Examples
14237 Take the first 5 seconds of a clip, and reverse it.
14244 Apply roberts cross operator to input video stream.
14246 The filter accepts the following option:
14250 Set which planes will be processed, unprocessed planes will be copied.
14251 By default value 0xf, all planes will be processed.
14254 Set value which will be multiplied with filtered result.
14257 Set value which will be added to filtered result.
14262 Rotate video by an arbitrary angle expressed in radians.
14264 The filter accepts the following options:
14266 A description of the optional parameters follows.
14269 Set an expression for the angle by which to rotate the input video
14270 clockwise, expressed as a number of radians. A negative value will
14271 result in a counter-clockwise rotation. By default it is set to "0".
14273 This expression is evaluated for each frame.
14276 Set the output width expression, default value is "iw".
14277 This expression is evaluated just once during configuration.
14280 Set the output height expression, default value is "ih".
14281 This expression is evaluated just once during configuration.
14284 Enable bilinear interpolation if set to 1, a value of 0 disables
14285 it. Default value is 1.
14288 Set the color used to fill the output area not covered by the rotated
14289 image. For the general syntax of this option, check the
14290 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
14291 If the special value "none" is selected then no
14292 background is printed (useful for example if the background is never shown).
14294 Default value is "black".
14297 The expressions for the angle and the output size can contain the
14298 following constants and functions:
14302 sequential number of the input frame, starting from 0. It is always NAN
14303 before the first frame is filtered.
14306 time in seconds of the input frame, it is set to 0 when the filter is
14307 configured. It is always NAN before the first frame is filtered.
14311 horizontal and vertical chroma subsample values. For example for the
14312 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14316 the input video width and height
14320 the output width and height, that is the size of the padded area as
14321 specified by the @var{width} and @var{height} expressions
14325 the minimal width/height required for completely containing the input
14326 video rotated by @var{a} radians.
14328 These are only available when computing the @option{out_w} and
14329 @option{out_h} expressions.
14332 @subsection Examples
14336 Rotate the input by PI/6 radians clockwise:
14342 Rotate the input by PI/6 radians counter-clockwise:
14348 Rotate the input by 45 degrees clockwise:
14354 Apply a constant rotation with period T, starting from an angle of PI/3:
14356 rotate=PI/3+2*PI*t/T
14360 Make the input video rotation oscillating with a period of T
14361 seconds and an amplitude of A radians:
14363 rotate=A*sin(2*PI/T*t)
14367 Rotate the video, output size is chosen so that the whole rotating
14368 input video is always completely contained in the output:
14370 rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
14374 Rotate the video, reduce the output size so that no background is ever
14377 rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
14381 @subsection Commands
14383 The filter supports the following commands:
14387 Set the angle expression.
14388 The command accepts the same syntax of the corresponding option.
14390 If the specified expression is not valid, it is kept at its current
14396 Apply Shape Adaptive Blur.
14398 The filter accepts the following options:
14401 @item luma_radius, lr
14402 Set luma blur filter strength, must be a value in range 0.1-4.0, default
14403 value is 1.0. A greater value will result in a more blurred image, and
14404 in slower processing.
14406 @item luma_pre_filter_radius, lpfr
14407 Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
14410 @item luma_strength, ls
14411 Set luma maximum difference between pixels to still be considered, must
14412 be a value in the 0.1-100.0 range, default value is 1.0.
14414 @item chroma_radius, cr
14415 Set chroma blur filter strength, must be a value in range -0.9-4.0. A
14416 greater value will result in a more blurred image, and in slower
14419 @item chroma_pre_filter_radius, cpfr
14420 Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
14422 @item chroma_strength, cs
14423 Set chroma maximum difference between pixels to still be considered,
14424 must be a value in the -0.9-100.0 range.
14427 Each chroma option value, if not explicitly specified, is set to the
14428 corresponding luma option value.
14433 Scale (resize) the input video, using the libswscale library.
14435 The scale filter forces the output display aspect ratio to be the same
14436 of the input, by changing the output sample aspect ratio.
14438 If the input image format is different from the format requested by
14439 the next filter, the scale filter will convert the input to the
14442 @subsection Options
14443 The filter accepts the following options, or any of the options
14444 supported by the libswscale scaler.
14446 See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
14447 the complete list of scaler options.
14452 Set the output video dimension expression. Default value is the input
14455 If the @var{width} or @var{w} value is 0, the input width is used for
14456 the output. If the @var{height} or @var{h} value is 0, the input height
14457 is used for the output.
14459 If one and only one of the values is -n with n >= 1, the scale filter
14460 will use a value that maintains the aspect ratio of the input image,
14461 calculated from the other specified dimension. After that it will,
14462 however, make sure that the calculated dimension is divisible by n and
14463 adjust the value if necessary.
14465 If both values are -n with n >= 1, the behavior will be identical to
14466 both values being set to 0 as previously detailed.
14468 See below for the list of accepted constants for use in the dimension
14472 Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
14476 Only evaluate expressions once during the filter initialization or when a command is processed.
14479 Evaluate expressions for each incoming frame.
14483 Default value is @samp{init}.
14487 Set the interlacing mode. It accepts the following values:
14491 Force interlaced aware scaling.
14494 Do not apply interlaced scaling.
14497 Select interlaced aware scaling depending on whether the source frames
14498 are flagged as interlaced or not.
14501 Default value is @samp{0}.
14504 Set libswscale scaling flags. See
14505 @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
14506 complete list of values. If not explicitly specified the filter applies
14510 @item param0, param1
14511 Set libswscale input parameters for scaling algorithms that need them. See
14512 @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
14513 complete documentation. If not explicitly specified the filter applies
14519 Set the video size. For the syntax of this option, check the
14520 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
14522 @item in_color_matrix
14523 @item out_color_matrix
14524 Set in/output YCbCr color space type.
14526 This allows the autodetected value to be overridden as well as allows forcing
14527 a specific value used for the output and encoder.
14529 If not specified, the color space type depends on the pixel format.
14535 Choose automatically.
14538 Format conforming to International Telecommunication Union (ITU)
14539 Recommendation BT.709.
14542 Set color space conforming to the United States Federal Communications
14543 Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
14546 Set color space conforming to:
14550 ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
14553 ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
14556 Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
14561 Set color space conforming to SMPTE ST 240:1999.
14566 Set in/output YCbCr sample range.
14568 This allows the autodetected value to be overridden as well as allows forcing
14569 a specific value used for the output and encoder. If not specified, the
14570 range depends on the pixel format. Possible values:
14574 Choose automatically.
14577 Set full range (0-255 in case of 8-bit luma).
14579 @item mpeg/limited/tv
14580 Set "MPEG" range (16-235 in case of 8-bit luma).
14583 @item force_original_aspect_ratio
14584 Enable decreasing or increasing output video width or height if necessary to
14585 keep the original aspect ratio. Possible values:
14589 Scale the video as specified and disable this feature.
14592 The output video dimensions will automatically be decreased if needed.
14595 The output video dimensions will automatically be increased if needed.
14599 One useful instance of this option is that when you know a specific device's
14600 maximum allowed resolution, you can use this to limit the output video to
14601 that, while retaining the aspect ratio. For example, device A allows
14602 1280x720 playback, and your video is 1920x800. Using this option (set it to
14603 decrease) and specifying 1280x720 to the command line makes the output
14606 Please note that this is a different thing than specifying -1 for @option{w}
14607 or @option{h}, you still need to specify the output resolution for this option
14612 The values of the @option{w} and @option{h} options are expressions
14613 containing the following constants:
14618 The input width and height
14622 These are the same as @var{in_w} and @var{in_h}.
14626 The output (scaled) width and height
14630 These are the same as @var{out_w} and @var{out_h}
14633 The same as @var{iw} / @var{ih}
14636 input sample aspect ratio
14639 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
14643 horizontal and vertical input chroma subsample values. For example for the
14644 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14648 horizontal and vertical output chroma subsample values. For example for the
14649 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14652 @subsection Examples
14656 Scale the input video to a size of 200x100
14661 This is equivalent to:
14672 Specify a size abbreviation for the output size:
14677 which can also be written as:
14683 Scale the input to 2x:
14685 scale=w=2*iw:h=2*ih
14689 The above is the same as:
14691 scale=2*in_w:2*in_h
14695 Scale the input to 2x with forced interlaced scaling:
14697 scale=2*iw:2*ih:interl=1
14701 Scale the input to half size:
14703 scale=w=iw/2:h=ih/2
14707 Increase the width, and set the height to the same size:
14713 Seek Greek harmony:
14720 Increase the height, and set the width to 3/2 of the height:
14722 scale=w=3/2*oh:h=3/5*ih
14726 Increase the size, making the size a multiple of the chroma
14729 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
14733 Increase the width to a maximum of 500 pixels,
14734 keeping the same aspect ratio as the input:
14736 scale=w='min(500\, iw*3/2):h=-1'
14740 Make pixels square by combining scale and setsar:
14742 scale='trunc(ih*dar):ih',setsar=1/1
14746 Make pixels square by combining scale and setsar,
14747 making sure the resulting resolution is even (required by some codecs):
14749 scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1
14753 @subsection Commands
14755 This filter supports the following commands:
14759 Set the output video dimension expression.
14760 The command accepts the same syntax of the corresponding option.
14762 If the specified expression is not valid, it is kept at its current
14768 Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
14769 format conversion on CUDA video frames. Setting the output width and height
14770 works in the same way as for the @var{scale} filter.
14772 The following additional options are accepted:
14775 The pixel format of the output CUDA frames. If set to the string "same" (the
14776 default), the input format will be kept. Note that automatic format negotiation
14777 and conversion is not yet supported for hardware frames
14780 The interpolation algorithm used for resizing. One of the following:
14787 @item cubic2p_bspline
14788 2-parameter cubic (B=1, C=0)
14790 @item cubic2p_catmullrom
14791 2-parameter cubic (B=0, C=1/2)
14793 @item cubic2p_b05c03
14794 2-parameter cubic (B=1/2, C=3/10)
14806 Scale (resize) the input video, based on a reference video.
14808 See the scale filter for available options, scale2ref supports the same but
14809 uses the reference video instead of the main input as basis. scale2ref also
14810 supports the following additional constants for the @option{w} and
14811 @option{h} options:
14816 The main input video's width and height
14819 The same as @var{main_w} / @var{main_h}
14822 The main input video's sample aspect ratio
14824 @item main_dar, mdar
14825 The main input video's display aspect ratio. Calculated from
14826 @code{(main_w / main_h) * main_sar}.
14830 The main input video's horizontal and vertical chroma subsample values.
14831 For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub}
14835 @subsection Examples
14839 Scale a subtitle stream (b) to match the main video (a) in size before overlaying
14841 'scale2ref[b][a];[a][b]overlay'
14845 @anchor{selectivecolor}
14846 @section selectivecolor
14848 Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
14849 as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
14850 by the "purity" of the color (that is, how saturated it already is).
14852 This filter is similar to the Adobe Photoshop Selective Color tool.
14854 The filter accepts the following options:
14857 @item correction_method
14858 Select color correction method.
14860 Available values are:
14863 Specified adjustments are applied "as-is" (added/subtracted to original pixel
14866 Specified adjustments are relative to the original component value.
14868 Default is @code{absolute}.
14870 Adjustments for red pixels (pixels where the red component is the maximum)
14872 Adjustments for yellow pixels (pixels where the blue component is the minimum)
14874 Adjustments for green pixels (pixels where the green component is the maximum)
14876 Adjustments for cyan pixels (pixels where the red component is the minimum)
14878 Adjustments for blue pixels (pixels where the blue component is the maximum)
14880 Adjustments for magenta pixels (pixels where the green component is the minimum)
14882 Adjustments for white pixels (pixels where all components are greater than 128)
14884 Adjustments for all pixels except pure black and pure white
14886 Adjustments for black pixels (pixels where all components are lesser than 128)
14888 Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
14891 All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
14892 4 space separated floating point adjustment values in the [-1,1] range,
14893 respectively to adjust the amount of cyan, magenta, yellow and black for the
14894 pixels of its range.
14896 @subsection Examples
14900 Increase cyan by 50% and reduce yellow by 33% in every green areas, and
14901 increase magenta by 27% in blue areas:
14903 selectivecolor=greens=.5 0 -.33 0:blues=0 .27
14907 Use a Photoshop selective color preset:
14909 selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
14913 @anchor{separatefields}
14914 @section separatefields
14916 The @code{separatefields} takes a frame-based video input and splits
14917 each frame into its components fields, producing a new half height clip
14918 with twice the frame rate and twice the frame count.
14920 This filter use field-dominance information in frame to decide which
14921 of each pair of fields to place first in the output.
14922 If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
14924 @section setdar, setsar
14926 The @code{setdar} filter sets the Display Aspect Ratio for the filter
14929 This is done by changing the specified Sample (aka Pixel) Aspect
14930 Ratio, according to the following equation:
14932 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
14935 Keep in mind that the @code{setdar} filter does not modify the pixel
14936 dimensions of the video frame. Also, the display aspect ratio set by
14937 this filter may be changed by later filters in the filterchain,
14938 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
14941 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
14942 the filter output video.
14944 Note that as a consequence of the application of this filter, the
14945 output display aspect ratio will change according to the equation
14948 Keep in mind that the sample aspect ratio set by the @code{setsar}
14949 filter may be changed by later filters in the filterchain, e.g. if
14950 another "setsar" or a "setdar" filter is applied.
14952 It accepts the following parameters:
14955 @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
14956 Set the aspect ratio used by the filter.
14958 The parameter can be a floating point number string, an expression, or
14959 a string of the form @var{num}:@var{den}, where @var{num} and
14960 @var{den} are the numerator and denominator of the aspect ratio. If
14961 the parameter is not specified, it is assumed the value "0".
14962 In case the form "@var{num}:@var{den}" is used, the @code{:} character
14966 Set the maximum integer value to use for expressing numerator and
14967 denominator when reducing the expressed aspect ratio to a rational.
14968 Default value is @code{100}.
14972 The parameter @var{sar} is an expression containing
14973 the following constants:
14977 These are approximated values for the mathematical constants e
14978 (Euler's number), pi (Greek pi), and phi (the golden ratio).
14981 The input width and height.
14984 These are the same as @var{w} / @var{h}.
14987 The input sample aspect ratio.
14990 The input display aspect ratio. It is the same as
14991 (@var{w} / @var{h}) * @var{sar}.
14994 Horizontal and vertical chroma subsample values. For example, for the
14995 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14998 @subsection Examples
15003 To change the display aspect ratio to 16:9, specify one of the following:
15010 To change the sample aspect ratio to 10:11, specify:
15016 To set a display aspect ratio of 16:9, and specify a maximum integer value of
15017 1000 in the aspect ratio reduction, use the command:
15019 setdar=ratio=16/9:max=1000
15027 Force field for the output video frame.
15029 The @code{setfield} filter marks the interlace type field for the
15030 output frames. It does not change the input frame, but only sets the
15031 corresponding property, which affects how the frame is treated by
15032 following filters (e.g. @code{fieldorder} or @code{yadif}).
15034 The filter accepts the following options:
15039 Available values are:
15043 Keep the same field property.
15046 Mark the frame as bottom-field-first.
15049 Mark the frame as top-field-first.
15052 Mark the frame as progressive.
15059 Force frame parameter for the output video frame.
15061 The @code{setparams} filter marks interlace and color range for the
15062 output frames. It does not change the input frame, but only sets the
15063 corresponding property, which affects how the frame is treated by
15068 Available values are:
15072 Keep the same field property (default).
15075 Mark the frame as bottom-field-first.
15078 Mark the frame as top-field-first.
15081 Mark the frame as progressive.
15085 Available values are:
15089 Keep the same color range property (default).
15091 @item unspecified, unknown
15092 Mark the frame as unspecified color range.
15094 @item limited, tv, mpeg
15095 Mark the frame as limited range.
15097 @item full, pc, jpeg
15098 Mark the frame as full range.
15101 @item color_primaries
15102 Set the color primaries.
15103 Available values are:
15107 Keep the same color primaries property (default).
15124 Set the color transfert.
15125 Available values are:
15129 Keep the same color trc property (default).
15151 Set the colorspace.
15152 Available values are:
15156 Keep the same colorspace property (default).
15169 @item chroma-derived-nc
15170 @item chroma-derived-c
15177 Show a line containing various information for each input video frame.
15178 The input video is not modified.
15180 The shown line contains a sequence of key/value pairs of the form
15181 @var{key}:@var{value}.
15183 The following values are shown in the output:
15187 The (sequential) number of the input frame, starting from 0.
15190 The Presentation TimeStamp of the input frame, expressed as a number of
15191 time base units. The time base unit depends on the filter input pad.
15194 The Presentation TimeStamp of the input frame, expressed as a number of
15198 The position of the frame in the input stream, or -1 if this information is
15199 unavailable and/or meaningless (for example in case of synthetic video).
15202 The pixel format name.
15205 The sample aspect ratio of the input frame, expressed in the form
15206 @var{num}/@var{den}.
15209 The size of the input frame. For the syntax of this option, check the
15210 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15213 The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
15214 for bottom field first).
15217 This is 1 if the frame is a key frame, 0 otherwise.
15220 The picture type of the input frame ("I" for an I-frame, "P" for a
15221 P-frame, "B" for a B-frame, or "?" for an unknown type).
15222 Also refer to the documentation of the @code{AVPictureType} enum and of
15223 the @code{av_get_picture_type_char} function defined in
15224 @file{libavutil/avutil.h}.
15227 The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
15229 @item plane_checksum
15230 The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
15231 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
15234 @section showpalette
15236 Displays the 256 colors palette of each frame. This filter is only relevant for
15237 @var{pal8} pixel format frames.
15239 It accepts the following option:
15243 Set the size of the box used to represent one palette color entry. Default is
15244 @code{30} (for a @code{30x30} pixel box).
15247 @section shuffleframes
15249 Reorder and/or duplicate and/or drop video frames.
15251 It accepts the following parameters:
15255 Set the destination indexes of input frames.
15256 This is space or '|' separated list of indexes that maps input frames to output
15257 frames. Number of indexes also sets maximal value that each index may have.
15258 '-1' index have special meaning and that is to drop frame.
15261 The first frame has the index 0. The default is to keep the input unchanged.
15263 @subsection Examples
15267 Swap second and third frame of every three frames of the input:
15269 ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
15273 Swap 10th and 1st frame of every ten frames of the input:
15275 ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
15279 @section shuffleplanes
15281 Reorder and/or duplicate video planes.
15283 It accepts the following parameters:
15288 The index of the input plane to be used as the first output plane.
15291 The index of the input plane to be used as the second output plane.
15294 The index of the input plane to be used as the third output plane.
15297 The index of the input plane to be used as the fourth output plane.
15301 The first plane has the index 0. The default is to keep the input unchanged.
15303 @subsection Examples
15307 Swap the second and third planes of the input:
15309 ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
15313 @anchor{signalstats}
15314 @section signalstats
15315 Evaluate various visual metrics that assist in determining issues associated
15316 with the digitization of analog video media.
15318 By default the filter will log these metadata values:
15322 Display the minimal Y value contained within the input frame. Expressed in
15326 Display the Y value at the 10% percentile within the input frame. Expressed in
15330 Display the average Y value within the input frame. Expressed in range of
15334 Display the Y value at the 90% percentile within the input frame. Expressed in
15338 Display the maximum Y value contained within the input frame. Expressed in
15342 Display the minimal U value contained within the input frame. Expressed in
15346 Display the U value at the 10% percentile within the input frame. Expressed in
15350 Display the average U value within the input frame. Expressed in range of
15354 Display the U value at the 90% percentile within the input frame. Expressed in
15358 Display the maximum U value contained within the input frame. Expressed in
15362 Display the minimal V value contained within the input frame. Expressed in
15366 Display the V value at the 10% percentile within the input frame. Expressed in
15370 Display the average V value within the input frame. Expressed in range of
15374 Display the V value at the 90% percentile within the input frame. Expressed in
15378 Display the maximum V value contained within the input frame. Expressed in
15382 Display the minimal saturation value contained within the input frame.
15383 Expressed in range of [0-~181.02].
15386 Display the saturation value at the 10% percentile within the input frame.
15387 Expressed in range of [0-~181.02].
15390 Display the average saturation value within the input frame. Expressed in range
15394 Display the saturation value at the 90% percentile within the input frame.
15395 Expressed in range of [0-~181.02].
15398 Display the maximum saturation value contained within the input frame.
15399 Expressed in range of [0-~181.02].
15402 Display the median value for hue within the input frame. Expressed in range of
15406 Display the average value for hue within the input frame. Expressed in range of
15410 Display the average of sample value difference between all values of the Y
15411 plane in the current frame and corresponding values of the previous input frame.
15412 Expressed in range of [0-255].
15415 Display the average of sample value difference between all values of the U
15416 plane in the current frame and corresponding values of the previous input frame.
15417 Expressed in range of [0-255].
15420 Display the average of sample value difference between all values of the V
15421 plane in the current frame and corresponding values of the previous input frame.
15422 Expressed in range of [0-255].
15425 Display bit depth of Y plane in current frame.
15426 Expressed in range of [0-16].
15429 Display bit depth of U plane in current frame.
15430 Expressed in range of [0-16].
15433 Display bit depth of V plane in current frame.
15434 Expressed in range of [0-16].
15437 The filter accepts the following options:
15443 @option{stat} specify an additional form of image analysis.
15444 @option{out} output video with the specified type of pixel highlighted.
15446 Both options accept the following values:
15450 Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
15451 unlike the neighboring pixels of the same field. Examples of temporal outliers
15452 include the results of video dropouts, head clogs, or tape tracking issues.
15455 Identify @var{vertical line repetition}. Vertical line repetition includes
15456 similar rows of pixels within a frame. In born-digital video vertical line
15457 repetition is common, but this pattern is uncommon in video digitized from an
15458 analog source. When it occurs in video that results from the digitization of an
15459 analog source it can indicate concealment from a dropout compensator.
15462 Identify pixels that fall outside of legal broadcast range.
15466 Set the highlight color for the @option{out} option. The default color is
15470 @subsection Examples
15474 Output data of various video metrics:
15476 ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
15480 Output specific data about the minimum and maximum values of the Y plane per frame:
15482 ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
15486 Playback video while highlighting pixels that are outside of broadcast range in red.
15488 ffplay example.mov -vf signalstats="out=brng:color=red"
15492 Playback video with signalstats metadata drawn over the frame.
15494 ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
15497 The contents of signalstat_drawtext.txt used in the command are:
15500 Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
15501 U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
15502 V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
15503 saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
15511 Calculates the MPEG-7 Video Signature. The filter can handle more than one
15512 input. In this case the matching between the inputs can be calculated additionally.
15513 The filter always passes through the first input. The signature of each stream can
15514 be written into a file.
15516 It accepts the following options:
15520 Enable or disable the matching process.
15522 Available values are:
15526 Disable the calculation of a matching (default).
15528 Calculate the matching for the whole video and output whether the whole video
15529 matches or only parts.
15531 Calculate only until a matching is found or the video ends. Should be faster in
15536 Set the number of inputs. The option value must be a non negative integer.
15537 Default value is 1.
15540 Set the path to which the output is written. If there is more than one input,
15541 the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive
15542 integer), that will be replaced with the input number. If no filename is
15543 specified, no output will be written. This is the default.
15546 Choose the output format.
15548 Available values are:
15552 Use the specified binary representation (default).
15554 Use the specified xml representation.
15558 Set threshold to detect one word as similar. The option value must be an integer
15559 greater than zero. The default value is 9000.
15562 Set threshold to detect all words as similar. The option value must be an integer
15563 greater than zero. The default value is 60000.
15566 Set threshold to detect frames as similar. The option value must be an integer
15567 greater than zero. The default value is 116.
15570 Set the minimum length of a sequence in frames to recognize it as matching
15571 sequence. The option value must be a non negative integer value.
15572 The default value is 0.
15575 Set the minimum relation, that matching frames to all frames must have.
15576 The option value must be a double value between 0 and 1. The default value is 0.5.
15579 @subsection Examples
15583 To calculate the signature of an input video and store it in signature.bin:
15585 ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
15589 To detect whether two videos match and store the signatures in XML format in
15590 signature0.xml and signature1.xml:
15592 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 -
15600 Blur the input video without impacting the outlines.
15602 It accepts the following options:
15605 @item luma_radius, lr
15606 Set the luma radius. The option value must be a float number in
15607 the range [0.1,5.0] that specifies the variance of the gaussian filter
15608 used to blur the image (slower if larger). Default value is 1.0.
15610 @item luma_strength, ls
15611 Set the luma strength. The option value must be a float number
15612 in the range [-1.0,1.0] that configures the blurring. A value included
15613 in [0.0,1.0] will blur the image whereas a value included in
15614 [-1.0,0.0] will sharpen the image. Default value is 1.0.
15616 @item luma_threshold, lt
15617 Set the luma threshold used as a coefficient to determine
15618 whether a pixel should be blurred or not. The option value must be an
15619 integer in the range [-30,30]. A value of 0 will filter all the image,
15620 a value included in [0,30] will filter flat areas and a value included
15621 in [-30,0] will filter edges. Default value is 0.
15623 @item chroma_radius, cr
15624 Set the chroma radius. The option value must be a float number in
15625 the range [0.1,5.0] that specifies the variance of the gaussian filter
15626 used to blur the image (slower if larger). Default value is @option{luma_radius}.
15628 @item chroma_strength, cs
15629 Set the chroma strength. The option value must be a float number
15630 in the range [-1.0,1.0] that configures the blurring. A value included
15631 in [0.0,1.0] will blur the image whereas a value included in
15632 [-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}.
15634 @item chroma_threshold, ct
15635 Set the chroma threshold used as a coefficient to determine
15636 whether a pixel should be blurred or not. The option value must be an
15637 integer in the range [-30,30]. A value of 0 will filter all the image,
15638 a value included in [0,30] will filter flat areas and a value included
15639 in [-30,0] will filter edges. Default value is @option{luma_threshold}.
15642 If a chroma option is not explicitly set, the corresponding luma value
15647 Obtain the SSIM (Structural SImilarity Metric) between two input videos.
15649 This filter takes in input two input videos, the first input is
15650 considered the "main" source and is passed unchanged to the
15651 output. The second input is used as a "reference" video for computing
15654 Both video inputs must have the same resolution and pixel format for
15655 this filter to work correctly. Also it assumes that both inputs
15656 have the same number of frames, which are compared one by one.
15658 The filter stores the calculated SSIM of each frame.
15660 The description of the accepted parameters follows.
15663 @item stats_file, f
15664 If specified the filter will use the named file to save the SSIM of
15665 each individual frame. When filename equals "-" the data is sent to
15669 The file printed if @var{stats_file} is selected, contains a sequence of
15670 key/value pairs of the form @var{key}:@var{value} for each compared
15673 A description of each shown parameter follows:
15677 sequential number of the input frame, starting from 1
15679 @item Y, U, V, R, G, B
15680 SSIM of the compared frames for the component specified by the suffix.
15683 SSIM of the compared frames for the whole frame.
15686 Same as above but in dB representation.
15689 This filter also supports the @ref{framesync} options.
15693 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
15694 [main][ref] ssim="stats_file=stats.log" [out]
15697 On this example the input file being processed is compared with the
15698 reference file @file{ref_movie.mpg}. The SSIM of each individual frame
15699 is stored in @file{stats.log}.
15701 Another example with both psnr and ssim at same time:
15703 ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
15708 Convert between different stereoscopic image formats.
15710 The filters accept the following options:
15714 Set stereoscopic image format of input.
15716 Available values for input image formats are:
15719 side by side parallel (left eye left, right eye right)
15722 side by side crosseye (right eye left, left eye right)
15725 side by side parallel with half width resolution
15726 (left eye left, right eye right)
15729 side by side crosseye with half width resolution
15730 (right eye left, left eye right)
15733 above-below (left eye above, right eye below)
15736 above-below (right eye above, left eye below)
15739 above-below with half height resolution
15740 (left eye above, right eye below)
15743 above-below with half height resolution
15744 (right eye above, left eye below)
15747 alternating frames (left eye first, right eye second)
15750 alternating frames (right eye first, left eye second)
15753 interleaved rows (left eye has top row, right eye starts on next row)
15756 interleaved rows (right eye has top row, left eye starts on next row)
15759 interleaved columns, left eye first
15762 interleaved columns, right eye first
15764 Default value is @samp{sbsl}.
15768 Set stereoscopic image format of output.
15772 side by side parallel (left eye left, right eye right)
15775 side by side crosseye (right eye left, left eye right)
15778 side by side parallel with half width resolution
15779 (left eye left, right eye right)
15782 side by side crosseye with half width resolution
15783 (right eye left, left eye right)
15786 above-below (left eye above, right eye below)
15789 above-below (right eye above, left eye below)
15792 above-below with half height resolution
15793 (left eye above, right eye below)
15796 above-below with half height resolution
15797 (right eye above, left eye below)
15800 alternating frames (left eye first, right eye second)
15803 alternating frames (right eye first, left eye second)
15806 interleaved rows (left eye has top row, right eye starts on next row)
15809 interleaved rows (right eye has top row, left eye starts on next row)
15812 anaglyph red/blue gray
15813 (red filter on left eye, blue filter on right eye)
15816 anaglyph red/green gray
15817 (red filter on left eye, green filter on right eye)
15820 anaglyph red/cyan gray
15821 (red filter on left eye, cyan filter on right eye)
15824 anaglyph red/cyan half colored
15825 (red filter on left eye, cyan filter on right eye)
15828 anaglyph red/cyan color
15829 (red filter on left eye, cyan filter on right eye)
15832 anaglyph red/cyan color optimized with the least squares projection of dubois
15833 (red filter on left eye, cyan filter on right eye)
15836 anaglyph green/magenta gray
15837 (green filter on left eye, magenta filter on right eye)
15840 anaglyph green/magenta half colored
15841 (green filter on left eye, magenta filter on right eye)
15844 anaglyph green/magenta colored
15845 (green filter on left eye, magenta filter on right eye)
15848 anaglyph green/magenta color optimized with the least squares projection of dubois
15849 (green filter on left eye, magenta filter on right eye)
15852 anaglyph yellow/blue gray
15853 (yellow filter on left eye, blue filter on right eye)
15856 anaglyph yellow/blue half colored
15857 (yellow filter on left eye, blue filter on right eye)
15860 anaglyph yellow/blue colored
15861 (yellow filter on left eye, blue filter on right eye)
15864 anaglyph yellow/blue color optimized with the least squares projection of dubois
15865 (yellow filter on left eye, blue filter on right eye)
15868 mono output (left eye only)
15871 mono output (right eye only)
15874 checkerboard, left eye first
15877 checkerboard, right eye first
15880 interleaved columns, left eye first
15883 interleaved columns, right eye first
15889 Default value is @samp{arcd}.
15892 @subsection Examples
15896 Convert input video from side by side parallel to anaglyph yellow/blue dubois:
15902 Convert input video from above below (left eye above, right eye below) to side by side crosseye.
15908 @section streamselect, astreamselect
15909 Select video or audio streams.
15911 The filter accepts the following options:
15915 Set number of inputs. Default is 2.
15918 Set input indexes to remap to outputs.
15921 @subsection Commands
15923 The @code{streamselect} and @code{astreamselect} filter supports the following
15928 Set input indexes to remap to outputs.
15931 @subsection Examples
15935 Select first 5 seconds 1st stream and rest of time 2nd stream:
15937 sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
15941 Same as above, but for audio:
15943 asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
15948 Apply sobel operator to input video stream.
15950 The filter accepts the following option:
15954 Set which planes will be processed, unprocessed planes will be copied.
15955 By default value 0xf, all planes will be processed.
15958 Set value which will be multiplied with filtered result.
15961 Set value which will be added to filtered result.
15967 Apply a simple postprocessing filter that compresses and decompresses the image
15968 at several (or - in the case of @option{quality} level @code{6} - all) shifts
15969 and average the results.
15971 The filter accepts the following options:
15975 Set quality. This option defines the number of levels for averaging. It accepts
15976 an integer in the range 0-6. If set to @code{0}, the filter will have no
15977 effect. A value of @code{6} means the higher quality. For each increment of
15978 that value the speed drops by a factor of approximately 2. Default value is
15982 Force a constant quantization parameter. If not set, the filter will use the QP
15983 from the video stream (if available).
15986 Set thresholding mode. Available modes are:
15990 Set hard thresholding (default).
15992 Set soft thresholding (better de-ringing effect, but likely blurrier).
15995 @item use_bframe_qp
15996 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
15997 option may cause flicker since the B-Frames have often larger QP. Default is
15998 @code{0} (not enabled).
16003 Scale the input by applying one of the super-resolution methods based on
16004 convolutional neural networks. Supported models:
16008 Super-Resolution Convolutional Neural Network model (SRCNN).
16009 See @url{https://arxiv.org/abs/1501.00092}.
16012 Efficient Sub-Pixel Convolutional Neural Network model (ESPCN).
16013 See @url{https://arxiv.org/abs/1609.05158}.
16016 Training scripts as well as scripts for model generation are provided in
16017 the repository at @url{https://github.com/HighVoltageRocknRoll/sr.git}.
16019 The filter accepts the following options:
16023 Specify which DNN backend to use for model loading and execution. This option accepts
16024 the following values:
16028 Native implementation of DNN loading and execution.
16031 TensorFlow backend. To enable this backend you
16032 need to install the TensorFlow for C library (see
16033 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
16034 @code{--enable-libtensorflow}
16037 Default value is @samp{native}.
16040 Set path to model file specifying network architecture and its parameters.
16041 Note that different backends use different file formats. TensorFlow backend
16042 can load files for both formats, while native backend can load files for only
16046 Set scale factor for SRCNN model. Allowed values are @code{2}, @code{3} and @code{4}.
16047 Default value is @code{2}. Scale factor is necessary for SRCNN model, because it accepts
16048 input upscaled using bicubic upscaling with proper scale factor.
16054 Draw subtitles on top of input video using the libass library.
16056 To enable compilation of this filter you need to configure FFmpeg with
16057 @code{--enable-libass}. This filter also requires a build with libavcodec and
16058 libavformat to convert the passed subtitles file to ASS (Advanced Substation
16059 Alpha) subtitles format.
16061 The filter accepts the following options:
16065 Set the filename of the subtitle file to read. It must be specified.
16067 @item original_size
16068 Specify the size of the original video, the video for which the ASS file
16069 was composed. For the syntax of this option, check the
16070 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16071 Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
16072 correctly scale the fonts if the aspect ratio has been changed.
16075 Set a directory path containing fonts that can be used by the filter.
16076 These fonts will be used in addition to whatever the font provider uses.
16079 Process alpha channel, by default alpha channel is untouched.
16082 Set subtitles input character encoding. @code{subtitles} filter only. Only
16083 useful if not UTF-8.
16085 @item stream_index, si
16086 Set subtitles stream index. @code{subtitles} filter only.
16089 Override default style or script info parameters of the subtitles. It accepts a
16090 string containing ASS style format @code{KEY=VALUE} couples separated by ",".
16093 If the first key is not specified, it is assumed that the first value
16094 specifies the @option{filename}.
16096 For example, to render the file @file{sub.srt} on top of the input
16097 video, use the command:
16102 which is equivalent to:
16104 subtitles=filename=sub.srt
16107 To render the default subtitles stream from file @file{video.mkv}, use:
16109 subtitles=video.mkv
16112 To render the second subtitles stream from that file, use:
16114 subtitles=video.mkv:si=1
16117 To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue
16118 @code{DejaVu Serif}, use:
16120 subtitles=sub.srt:force_style='FontName=DejaVu Serif,PrimaryColour=&HCCFF0000'
16123 @section super2xsai
16125 Scale the input by 2x and smooth using the Super2xSaI (Scale and
16126 Interpolate) pixel art scaling algorithm.
16128 Useful for enlarging pixel art images without reducing sharpness.
16132 Swap two rectangular objects in video.
16134 This filter accepts the following options:
16144 Set 1st rect x coordinate.
16147 Set 1st rect y coordinate.
16150 Set 2nd rect x coordinate.
16153 Set 2nd rect y coordinate.
16155 All expressions are evaluated once for each frame.
16158 The all options are expressions containing the following constants:
16163 The input width and height.
16166 same as @var{w} / @var{h}
16169 input sample aspect ratio
16172 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
16175 The number of the input frame, starting from 0.
16178 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
16181 the position in the file of the input frame, NAN if unknown
16189 Apply telecine process to the video.
16191 This filter accepts the following options:
16200 The default value is @code{top}.
16204 A string of numbers representing the pulldown pattern you wish to apply.
16205 The default value is @code{23}.
16209 Some typical patterns:
16214 24p: 2332 (preferred)
16221 24p: 222222222223 ("Euro pulldown")
16228 Apply threshold effect to video stream.
16230 This filter needs four video streams to perform thresholding.
16231 First stream is stream we are filtering.
16232 Second stream is holding threshold values, third stream is holding min values,
16233 and last, fourth stream is holding max values.
16235 The filter accepts the following option:
16239 Set which planes will be processed, unprocessed planes will be copied.
16240 By default value 0xf, all planes will be processed.
16243 For example if first stream pixel's component value is less then threshold value
16244 of pixel component from 2nd threshold stream, third stream value will picked,
16245 otherwise fourth stream pixel component value will be picked.
16247 Using color source filter one can perform various types of thresholding:
16249 @subsection Examples
16253 Binary threshold, using gray color as threshold:
16255 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
16259 Inverted binary threshold, using gray color as threshold:
16261 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
16265 Truncate binary threshold, using gray color as threshold:
16267 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
16271 Threshold to zero, using gray color as threshold:
16273 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
16277 Inverted threshold to zero, using gray color as threshold:
16279 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
16284 Select the most representative frame in a given sequence of consecutive frames.
16286 The filter accepts the following options:
16290 Set the frames batch size to analyze; in a set of @var{n} frames, the filter
16291 will pick one of them, and then handle the next batch of @var{n} frames until
16292 the end. Default is @code{100}.
16295 Since the filter keeps track of the whole frames sequence, a bigger @var{n}
16296 value will result in a higher memory usage, so a high value is not recommended.
16298 @subsection Examples
16302 Extract one picture each 50 frames:
16308 Complete example of a thumbnail creation with @command{ffmpeg}:
16310 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
16316 Tile several successive frames together.
16318 The filter accepts the following options:
16323 Set the grid size (i.e. the number of lines and columns). For the syntax of
16324 this option, check the
16325 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16328 Set the maximum number of frames to render in the given area. It must be less
16329 than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
16330 the area will be used.
16333 Set the outer border margin in pixels.
16336 Set the inner border thickness (i.e. the number of pixels between frames). For
16337 more advanced padding options (such as having different values for the edges),
16338 refer to the pad video filter.
16341 Specify the color of the unused area. For the syntax of this option, check the
16342 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
16343 The default value of @var{color} is "black".
16346 Set the number of frames to overlap when tiling several successive frames together.
16347 The value must be between @code{0} and @var{nb_frames - 1}.
16350 Set the number of frames to initially be empty before displaying first output frame.
16351 This controls how soon will one get first output frame.
16352 The value must be between @code{0} and @var{nb_frames - 1}.
16355 @subsection Examples
16359 Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
16361 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
16363 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
16364 duplicating each output frame to accommodate the originally detected frame
16368 Display @code{5} pictures in an area of @code{3x2} frames,
16369 with @code{7} pixels between them, and @code{2} pixels of initial margin, using
16370 mixed flat and named options:
16372 tile=3x2:nb_frames=5:padding=7:margin=2
16376 @section tinterlace
16378 Perform various types of temporal field interlacing.
16380 Frames are counted starting from 1, so the first input frame is
16383 The filter accepts the following options:
16388 Specify the mode of the interlacing. This option can also be specified
16389 as a value alone. See below for a list of values for this option.
16391 Available values are:
16395 Move odd frames into the upper field, even into the lower field,
16396 generating a double height frame at half frame rate.
16400 Frame 1 Frame 2 Frame 3 Frame 4
16402 11111 22222 33333 44444
16403 11111 22222 33333 44444
16404 11111 22222 33333 44444
16405 11111 22222 33333 44444
16419 Only output odd frames, even frames are dropped, generating a frame with
16420 unchanged height at half frame rate.
16425 Frame 1 Frame 2 Frame 3 Frame 4
16427 11111 22222 33333 44444
16428 11111 22222 33333 44444
16429 11111 22222 33333 44444
16430 11111 22222 33333 44444
16440 Only output even frames, odd frames are dropped, generating a frame with
16441 unchanged height at half frame rate.
16446 Frame 1 Frame 2 Frame 3 Frame 4
16448 11111 22222 33333 44444
16449 11111 22222 33333 44444
16450 11111 22222 33333 44444
16451 11111 22222 33333 44444
16461 Expand each frame to full height, but pad alternate lines with black,
16462 generating a frame with double height at the same input frame rate.
16467 Frame 1 Frame 2 Frame 3 Frame 4
16469 11111 22222 33333 44444
16470 11111 22222 33333 44444
16471 11111 22222 33333 44444
16472 11111 22222 33333 44444
16475 11111 ..... 33333 .....
16476 ..... 22222 ..... 44444
16477 11111 ..... 33333 .....
16478 ..... 22222 ..... 44444
16479 11111 ..... 33333 .....
16480 ..... 22222 ..... 44444
16481 11111 ..... 33333 .....
16482 ..... 22222 ..... 44444
16486 @item interleave_top, 4
16487 Interleave the upper field from odd frames with the lower field from
16488 even frames, generating a frame with unchanged height at half frame rate.
16493 Frame 1 Frame 2 Frame 3 Frame 4
16495 11111<- 22222 33333<- 44444
16496 11111 22222<- 33333 44444<-
16497 11111<- 22222 33333<- 44444
16498 11111 22222<- 33333 44444<-
16508 @item interleave_bottom, 5
16509 Interleave the lower field from odd frames with the upper field from
16510 even frames, generating a frame with unchanged height at half frame rate.
16515 Frame 1 Frame 2 Frame 3 Frame 4
16517 11111 22222<- 33333 44444<-
16518 11111<- 22222 33333<- 44444
16519 11111 22222<- 33333 44444<-
16520 11111<- 22222 33333<- 44444
16530 @item interlacex2, 6
16531 Double frame rate with unchanged height. Frames are inserted each
16532 containing the second temporal field from the previous input frame and
16533 the first temporal field from the next input frame. This mode relies on
16534 the top_field_first flag. Useful for interlaced video displays with no
16535 field synchronisation.
16540 Frame 1 Frame 2 Frame 3 Frame 4
16542 11111 22222 33333 44444
16543 11111 22222 33333 44444
16544 11111 22222 33333 44444
16545 11111 22222 33333 44444
16548 11111 22222 22222 33333 33333 44444 44444
16549 11111 11111 22222 22222 33333 33333 44444
16550 11111 22222 22222 33333 33333 44444 44444
16551 11111 11111 22222 22222 33333 33333 44444
16556 Move odd frames into the upper field, even into the lower field,
16557 generating a double height frame at same frame rate.
16562 Frame 1 Frame 2 Frame 3 Frame 4
16564 11111 22222 33333 44444
16565 11111 22222 33333 44444
16566 11111 22222 33333 44444
16567 11111 22222 33333 44444
16570 11111 33333 33333 55555
16571 22222 22222 44444 44444
16572 11111 33333 33333 55555
16573 22222 22222 44444 44444
16574 11111 33333 33333 55555
16575 22222 22222 44444 44444
16576 11111 33333 33333 55555
16577 22222 22222 44444 44444
16582 Numeric values are deprecated but are accepted for backward
16583 compatibility reasons.
16585 Default mode is @code{merge}.
16588 Specify flags influencing the filter process.
16590 Available value for @var{flags} is:
16593 @item low_pass_filter, vlfp
16594 Enable linear vertical low-pass filtering in the filter.
16595 Vertical low-pass filtering is required when creating an interlaced
16596 destination from a progressive source which contains high-frequency
16597 vertical detail. Filtering will reduce interlace 'twitter' and Moire
16600 @item complex_filter, cvlfp
16601 Enable complex vertical low-pass filtering.
16602 This will slightly less reduce interlace 'twitter' and Moire
16603 patterning but better retain detail and subjective sharpness impression.
16607 Vertical low-pass filtering can only be enabled for @option{mode}
16608 @var{interleave_top} and @var{interleave_bottom}.
16614 Mix successive video frames.
16616 A description of the accepted options follows.
16620 The number of successive frames to mix. If unspecified, it defaults to 3.
16623 Specify weight of each input video frame.
16624 Each weight is separated by space. If number of weights is smaller than
16625 number of @var{frames} last specified weight will be used for all remaining
16629 Specify scale, if it is set it will be multiplied with sum
16630 of each weight multiplied with pixel values to give final destination
16631 pixel value. By default @var{scale} is auto scaled to sum of weights.
16634 @subsection Examples
16638 Average 7 successive frames:
16640 tmix=frames=7:weights="1 1 1 1 1 1 1"
16644 Apply simple temporal convolution:
16646 tmix=frames=3:weights="-1 3 -1"
16650 Similar as above but only showing temporal differences:
16652 tmix=frames=3:weights="-1 2 -1":scale=1
16658 Tone map colors from different dynamic ranges.
16660 This filter expects data in single precision floating point, as it needs to
16661 operate on (and can output) out-of-range values. Another filter, such as
16662 @ref{zscale}, is needed to convert the resulting frame to a usable format.
16664 The tonemapping algorithms implemented only work on linear light, so input
16665 data should be linearized beforehand (and possibly correctly tagged).
16668 ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
16671 @subsection Options
16672 The filter accepts the following options.
16676 Set the tone map algorithm to use.
16678 Possible values are:
16681 Do not apply any tone map, only desaturate overbright pixels.
16684 Hard-clip any out-of-range values. Use it for perfect color accuracy for
16685 in-range values, while distorting out-of-range values.
16688 Stretch the entire reference gamut to a linear multiple of the display.
16691 Fit a logarithmic transfer between the tone curves.
16694 Preserve overall image brightness with a simple curve, using nonlinear
16695 contrast, which results in flattening details and degrading color accuracy.
16698 Preserve both dark and bright details better than @var{reinhard}, at the cost
16699 of slightly darkening everything. Use it when detail preservation is more
16700 important than color and brightness accuracy.
16703 Smoothly map out-of-range values, while retaining contrast and colors for
16704 in-range material as much as possible. Use it when color accuracy is more
16705 important than detail preservation.
16711 Tune the tone mapping algorithm.
16713 This affects the following algorithms:
16719 Specifies the scale factor to use while stretching.
16723 Specifies the exponent of the function.
16727 Specify an extra linear coefficient to multiply into the signal before clipping.
16731 Specify the local contrast coefficient at the display peak.
16732 Default to 0.5, which means that in-gamut values will be about half as bright
16739 Specify the transition point from linear to mobius transform. Every value
16740 below this point is guaranteed to be mapped 1:1. The higher the value, the
16741 more accurate the result will be, at the cost of losing bright details.
16742 Default to 0.3, which due to the steep initial slope still preserves in-range
16743 colors fairly accurately.
16747 Apply desaturation for highlights that exceed this level of brightness. The
16748 higher the parameter, the more color information will be preserved. This
16749 setting helps prevent unnaturally blown-out colors for super-highlights, by
16750 (smoothly) turning into white instead. This makes images feel more natural,
16751 at the cost of reducing information about out-of-range colors.
16753 The default of 2.0 is somewhat conservative and will mostly just apply to
16754 skies or directly sunlit surfaces. A setting of 0.0 disables this option.
16756 This option works only if the input frame has a supported color tag.
16759 Override signal/nominal/reference peak with this value. Useful when the
16760 embedded peak information in display metadata is not reliable or when tone
16761 mapping from a lower range to a higher range.
16766 Temporarily pad video frames.
16768 The filter accepts the following options:
16772 Specify number of delay frames before input video stream.
16775 Specify number of padding frames after input video stream.
16776 Set to -1 to pad indefinitely.
16779 Set kind of frames added to beginning of stream.
16780 Can be either @var{add} or @var{clone}.
16781 With @var{add} frames of solid-color are added.
16782 With @var{clone} frames are clones of first frame.
16785 Set kind of frames added to end of stream.
16786 Can be either @var{add} or @var{clone}.
16787 With @var{add} frames of solid-color are added.
16788 With @var{clone} frames are clones of last frame.
16790 @item start_duration, stop_duration
16791 Specify the duration of the start/stop delay. See
16792 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
16793 for the accepted syntax.
16794 These options override @var{start} and @var{stop}.
16797 Specify the color of the padded area. For the syntax of this option,
16798 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
16799 manual,ffmpeg-utils}.
16801 The default value of @var{color} is "black".
16807 Transpose rows with columns in the input video and optionally flip it.
16809 It accepts the following parameters:
16814 Specify the transposition direction.
16816 Can assume the following values:
16818 @item 0, 4, cclock_flip
16819 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
16827 Rotate by 90 degrees clockwise, that is:
16835 Rotate by 90 degrees counterclockwise, that is:
16842 @item 3, 7, clock_flip
16843 Rotate by 90 degrees clockwise and vertically flip, that is:
16851 For values between 4-7, the transposition is only done if the input
16852 video geometry is portrait and not landscape. These values are
16853 deprecated, the @code{passthrough} option should be used instead.
16855 Numerical values are deprecated, and should be dropped in favor of
16856 symbolic constants.
16859 Do not apply the transposition if the input geometry matches the one
16860 specified by the specified value. It accepts the following values:
16863 Always apply transposition.
16865 Preserve portrait geometry (when @var{height} >= @var{width}).
16867 Preserve landscape geometry (when @var{width} >= @var{height}).
16870 Default value is @code{none}.
16873 For example to rotate by 90 degrees clockwise and preserve portrait
16876 transpose=dir=1:passthrough=portrait
16879 The command above can also be specified as:
16881 transpose=1:portrait
16884 @section transpose_npp
16886 Transpose rows with columns in the input video and optionally flip it.
16887 For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options.
16889 It accepts the following parameters:
16894 Specify the transposition direction.
16896 Can assume the following values:
16899 Rotate by 90 degrees counterclockwise and vertically flip. (default)
16902 Rotate by 90 degrees clockwise.
16905 Rotate by 90 degrees counterclockwise.
16908 Rotate by 90 degrees clockwise and vertically flip.
16912 Do not apply the transposition if the input geometry matches the one
16913 specified by the specified value. It accepts the following values:
16916 Always apply transposition. (default)
16918 Preserve portrait geometry (when @var{height} >= @var{width}).
16920 Preserve landscape geometry (when @var{width} >= @var{height}).
16926 Trim the input so that the output contains one continuous subpart of the input.
16928 It accepts the following parameters:
16931 Specify the time of the start of the kept section, i.e. the frame with the
16932 timestamp @var{start} will be the first frame in the output.
16935 Specify the time of the first frame that will be dropped, i.e. the frame
16936 immediately preceding the one with the timestamp @var{end} will be the last
16937 frame in the output.
16940 This is the same as @var{start}, except this option sets the start timestamp
16941 in timebase units instead of seconds.
16944 This is the same as @var{end}, except this option sets the end timestamp
16945 in timebase units instead of seconds.
16948 The maximum duration of the output in seconds.
16951 The number of the first frame that should be passed to the output.
16954 The number of the first frame that should be dropped.
16957 @option{start}, @option{end}, and @option{duration} are expressed as time
16958 duration specifications; see
16959 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
16960 for the accepted syntax.
16962 Note that the first two sets of the start/end options and the @option{duration}
16963 option look at the frame timestamp, while the _frame variants simply count the
16964 frames that pass through the filter. Also note that this filter does not modify
16965 the timestamps. If you wish for the output timestamps to start at zero, insert a
16966 setpts filter after the trim filter.
16968 If multiple start or end options are set, this filter tries to be greedy and
16969 keep all the frames that match at least one of the specified constraints. To keep
16970 only the part that matches all the constraints at once, chain multiple trim
16973 The defaults are such that all the input is kept. So it is possible to set e.g.
16974 just the end values to keep everything before the specified time.
16979 Drop everything except the second minute of input:
16981 ffmpeg -i INPUT -vf trim=60:120
16985 Keep only the first second:
16987 ffmpeg -i INPUT -vf trim=duration=1
16992 @section unpremultiply
16993 Apply alpha unpremultiply effect to input video stream using first plane
16994 of second stream as alpha.
16996 Both streams must have same dimensions and same pixel format.
16998 The filter accepts the following option:
17002 Set which planes will be processed, unprocessed planes will be copied.
17003 By default value 0xf, all planes will be processed.
17005 If the format has 1 or 2 components, then luma is bit 0.
17006 If the format has 3 or 4 components:
17007 for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red;
17008 for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V.
17009 If present, the alpha channel is always the last bit.
17012 Do not require 2nd input for processing, instead use alpha plane from input stream.
17018 Sharpen or blur the input video.
17020 It accepts the following parameters:
17023 @item luma_msize_x, lx
17024 Set the luma matrix horizontal size. It must be an odd integer between
17025 3 and 23. The default value is 5.
17027 @item luma_msize_y, ly
17028 Set the luma matrix vertical size. It must be an odd integer between 3
17029 and 23. The default value is 5.
17031 @item luma_amount, la
17032 Set the luma effect strength. It must be a floating point number, reasonable
17033 values lay between -1.5 and 1.5.
17035 Negative values will blur the input video, while positive values will
17036 sharpen it, a value of zero will disable the effect.
17038 Default value is 1.0.
17040 @item chroma_msize_x, cx
17041 Set the chroma matrix horizontal size. It must be an odd integer
17042 between 3 and 23. The default value is 5.
17044 @item chroma_msize_y, cy
17045 Set the chroma matrix vertical size. It must be an odd integer
17046 between 3 and 23. The default value is 5.
17048 @item chroma_amount, ca
17049 Set the chroma effect strength. It must be a floating point number, reasonable
17050 values lay between -1.5 and 1.5.
17052 Negative values will blur the input video, while positive values will
17053 sharpen it, a value of zero will disable the effect.
17055 Default value is 0.0.
17059 All parameters are optional and default to the equivalent of the
17060 string '5:5:1.0:5:5:0.0'.
17062 @subsection Examples
17066 Apply strong luma sharpen effect:
17068 unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
17072 Apply a strong blur of both luma and chroma parameters:
17074 unsharp=7:7:-2:7:7:-2
17080 Apply ultra slow/simple postprocessing filter that compresses and decompresses
17081 the image at several (or - in the case of @option{quality} level @code{8} - all)
17082 shifts and average the results.
17084 The way this differs from the behavior of spp is that uspp actually encodes &
17085 decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
17086 DCT similar to MJPEG.
17088 The filter accepts the following options:
17092 Set quality. This option defines the number of levels for averaging. It accepts
17093 an integer in the range 0-8. If set to @code{0}, the filter will have no
17094 effect. A value of @code{8} means the higher quality. For each increment of
17095 that value the speed drops by a factor of approximately 2. Default value is
17099 Force a constant quantization parameter. If not set, the filter will use the QP
17100 from the video stream (if available).
17103 @section vaguedenoiser
17105 Apply a wavelet based denoiser.
17107 It transforms each frame from the video input into the wavelet domain,
17108 using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
17109 the obtained coefficients. It does an inverse wavelet transform after.
17110 Due to wavelet properties, it should give a nice smoothed result, and
17111 reduced noise, without blurring picture features.
17113 This filter accepts the following options:
17117 The filtering strength. The higher, the more filtered the video will be.
17118 Hard thresholding can use a higher threshold than soft thresholding
17119 before the video looks overfiltered. Default value is 2.
17122 The filtering method the filter will use.
17124 It accepts the following values:
17127 All values under the threshold will be zeroed.
17130 All values under the threshold will be zeroed. All values above will be
17131 reduced by the threshold.
17134 Scales or nullifies coefficients - intermediary between (more) soft and
17135 (less) hard thresholding.
17138 Default is garrote.
17141 Number of times, the wavelet will decompose the picture. Picture can't
17142 be decomposed beyond a particular point (typically, 8 for a 640x480
17143 frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6.
17146 Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85.
17149 A list of the planes to process. By default all planes are processed.
17152 @section vectorscope
17154 Display 2 color component values in the two dimensional graph (which is called
17157 This filter accepts the following options:
17161 Set vectorscope mode.
17163 It accepts the following values:
17166 Gray values are displayed on graph, higher brightness means more pixels have
17167 same component color value on location in graph. This is the default mode.
17170 Gray values are displayed on graph. Surrounding pixels values which are not
17171 present in video frame are drawn in gradient of 2 color components which are
17172 set by option @code{x} and @code{y}. The 3rd color component is static.
17175 Actual color components values present in video frame are displayed on graph.
17178 Similar as color2 but higher frequency of same values @code{x} and @code{y}
17179 on graph increases value of another color component, which is luminance by
17180 default values of @code{x} and @code{y}.
17183 Actual colors present in video frame are displayed on graph. If two different
17184 colors map to same position on graph then color with higher value of component
17185 not present in graph is picked.
17188 Gray values are displayed on graph. Similar to @code{color} but with 3rd color
17189 component picked from radial gradient.
17193 Set which color component will be represented on X-axis. Default is @code{1}.
17196 Set which color component will be represented on Y-axis. Default is @code{2}.
17199 Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
17200 of color component which represents frequency of (X, Y) location in graph.
17205 No envelope, this is default.
17208 Instant envelope, even darkest single pixel will be clearly highlighted.
17211 Hold maximum and minimum values presented in graph over time. This way you
17212 can still spot out of range values without constantly looking at vectorscope.
17215 Peak and instant envelope combined together.
17219 Set what kind of graticule to draw.
17227 Set graticule opacity.
17230 Set graticule flags.
17234 Draw graticule for white point.
17237 Draw graticule for black point.
17240 Draw color points short names.
17244 Set background opacity.
17246 @item lthreshold, l
17247 Set low threshold for color component not represented on X or Y axis.
17248 Values lower than this value will be ignored. Default is 0.
17249 Note this value is multiplied with actual max possible value one pixel component
17250 can have. So for 8-bit input and low threshold value of 0.1 actual threshold
17253 @item hthreshold, h
17254 Set high threshold for color component not represented on X or Y axis.
17255 Values higher than this value will be ignored. Default is 1.
17256 Note this value is multiplied with actual max possible value one pixel component
17257 can have. So for 8-bit input and high threshold value of 0.9 actual threshold
17258 is 0.9 * 255 = 230.
17260 @item colorspace, c
17261 Set what kind of colorspace to use when drawing graticule.
17270 @anchor{vidstabdetect}
17271 @section vidstabdetect
17273 Analyze video stabilization/deshaking. Perform pass 1 of 2, see
17274 @ref{vidstabtransform} for pass 2.
17276 This filter generates a file with relative translation and rotation
17277 transform information about subsequent frames, which is then used by
17278 the @ref{vidstabtransform} filter.
17280 To enable compilation of this filter you need to configure FFmpeg with
17281 @code{--enable-libvidstab}.
17283 This filter accepts the following options:
17287 Set the path to the file used to write the transforms information.
17288 Default value is @file{transforms.trf}.
17291 Set how shaky the video is and how quick the camera is. It accepts an
17292 integer in the range 1-10, a value of 1 means little shakiness, a
17293 value of 10 means strong shakiness. Default value is 5.
17296 Set the accuracy of the detection process. It must be a value in the
17297 range 1-15. A value of 1 means low accuracy, a value of 15 means high
17298 accuracy. Default value is 15.
17301 Set stepsize of the search process. The region around minimum is
17302 scanned with 1 pixel resolution. Default value is 6.
17305 Set minimum contrast. Below this value a local measurement field is
17306 discarded. Must be a floating point value in the range 0-1. Default
17310 Set reference frame number for tripod mode.
17312 If enabled, the motion of the frames is compared to a reference frame
17313 in the filtered stream, identified by the specified number. The idea
17314 is to compensate all movements in a more-or-less static scene and keep
17315 the camera view absolutely still.
17317 If set to 0, it is disabled. The frames are counted starting from 1.
17320 Show fields and transforms in the resulting frames. It accepts an
17321 integer in the range 0-2. Default value is 0, which disables any
17325 @subsection Examples
17329 Use default values:
17335 Analyze strongly shaky movie and put the results in file
17336 @file{mytransforms.trf}:
17338 vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
17342 Visualize the result of internal transformations in the resulting
17345 vidstabdetect=show=1
17349 Analyze a video with medium shakiness using @command{ffmpeg}:
17351 ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
17355 @anchor{vidstabtransform}
17356 @section vidstabtransform
17358 Video stabilization/deshaking: pass 2 of 2,
17359 see @ref{vidstabdetect} for pass 1.
17361 Read a file with transform information for each frame and
17362 apply/compensate them. Together with the @ref{vidstabdetect}
17363 filter this can be used to deshake videos. See also
17364 @url{http://public.hronopik.de/vid.stab}. It is important to also use
17365 the @ref{unsharp} filter, see below.
17367 To enable compilation of this filter you need to configure FFmpeg with
17368 @code{--enable-libvidstab}.
17370 @subsection Options
17374 Set path to the file used to read the transforms. Default value is
17375 @file{transforms.trf}.
17378 Set the number of frames (value*2 + 1) used for lowpass filtering the
17379 camera movements. Default value is 10.
17381 For example a number of 10 means that 21 frames are used (10 in the
17382 past and 10 in the future) to smoothen the motion in the video. A
17383 larger value leads to a smoother video, but limits the acceleration of
17384 the camera (pan/tilt movements). 0 is a special case where a static
17385 camera is simulated.
17388 Set the camera path optimization algorithm.
17390 Accepted values are:
17393 gaussian kernel low-pass filter on camera motion (default)
17395 averaging on transformations
17399 Set maximal number of pixels to translate frames. Default value is -1,
17403 Set maximal angle in radians (degree*PI/180) to rotate frames. Default
17404 value is -1, meaning no limit.
17407 Specify how to deal with borders that may be visible due to movement
17410 Available values are:
17413 keep image information from previous frame (default)
17415 fill the border black
17419 Invert transforms if set to 1. Default value is 0.
17422 Consider transforms as relative to previous frame if set to 1,
17423 absolute if set to 0. Default value is 0.
17426 Set percentage to zoom. A positive value will result in a zoom-in
17427 effect, a negative value in a zoom-out effect. Default value is 0 (no
17431 Set optimal zooming to avoid borders.
17433 Accepted values are:
17438 optimal static zoom value is determined (only very strong movements
17439 will lead to visible borders) (default)
17441 optimal adaptive zoom value is determined (no borders will be
17442 visible), see @option{zoomspeed}
17445 Note that the value given at zoom is added to the one calculated here.
17448 Set percent to zoom maximally each frame (enabled when
17449 @option{optzoom} is set to 2). Range is from 0 to 5, default value is
17453 Specify type of interpolation.
17455 Available values are:
17460 linear only horizontal
17462 linear in both directions (default)
17464 cubic in both directions (slow)
17468 Enable virtual tripod mode if set to 1, which is equivalent to
17469 @code{relative=0:smoothing=0}. Default value is 0.
17471 Use also @code{tripod} option of @ref{vidstabdetect}.
17474 Increase log verbosity if set to 1. Also the detected global motions
17475 are written to the temporary file @file{global_motions.trf}. Default
17479 @subsection Examples
17483 Use @command{ffmpeg} for a typical stabilization with default values:
17485 ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
17488 Note the use of the @ref{unsharp} filter which is always recommended.
17491 Zoom in a bit more and load transform data from a given file:
17493 vidstabtransform=zoom=5:input="mytransforms.trf"
17497 Smoothen the video even more:
17499 vidstabtransform=smoothing=30
17505 Flip the input video vertically.
17507 For example, to vertically flip a video with @command{ffmpeg}:
17509 ffmpeg -i in.avi -vf "vflip" out.avi
17514 Detect variable frame rate video.
17516 This filter tries to detect if the input is variable or constant frame rate.
17518 At end it will output number of frames detected as having variable delta pts,
17519 and ones with constant delta pts.
17520 If there was frames with variable delta, than it will also show min and max delta
17525 Boost or alter saturation.
17527 The filter accepts the following options:
17530 Set strength of boost if positive value or strength of alter if negative value.
17531 Default is 0. Allowed range is from -2 to 2.
17534 Set the red balance. Default is 1. Allowed range is from -10 to 10.
17537 Set the green balance. Default is 1. Allowed range is from -10 to 10.
17540 Set the blue balance. Default is 1. Allowed range is from -10 to 10.
17543 Set the red luma coefficient.
17546 Set the green luma coefficient.
17549 Set the blue luma coefficient.
17555 Make or reverse a natural vignetting effect.
17557 The filter accepts the following options:
17561 Set lens angle expression as a number of radians.
17563 The value is clipped in the @code{[0,PI/2]} range.
17565 Default value: @code{"PI/5"}
17569 Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
17573 Set forward/backward mode.
17575 Available modes are:
17578 The larger the distance from the central point, the darker the image becomes.
17581 The larger the distance from the central point, the brighter the image becomes.
17582 This can be used to reverse a vignette effect, though there is no automatic
17583 detection to extract the lens @option{angle} and other settings (yet). It can
17584 also be used to create a burning effect.
17587 Default value is @samp{forward}.
17590 Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
17592 It accepts the following values:
17595 Evaluate expressions only once during the filter initialization.
17598 Evaluate expressions for each incoming frame. This is way slower than the
17599 @samp{init} mode since it requires all the scalers to be re-computed, but it
17600 allows advanced dynamic expressions.
17603 Default value is @samp{init}.
17606 Set dithering to reduce the circular banding effects. Default is @code{1}
17610 Set vignette aspect. This setting allows one to adjust the shape of the vignette.
17611 Setting this value to the SAR of the input will make a rectangular vignetting
17612 following the dimensions of the video.
17614 Default is @code{1/1}.
17617 @subsection Expressions
17619 The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
17620 following parameters.
17625 input width and height
17628 the number of input frame, starting from 0
17631 the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
17632 @var{TB} units, NAN if undefined
17635 frame rate of the input video, NAN if the input frame rate is unknown
17638 the PTS (Presentation TimeStamp) of the filtered video frame,
17639 expressed in seconds, NAN if undefined
17642 time base of the input video
17646 @subsection Examples
17650 Apply simple strong vignetting effect:
17656 Make a flickering vignetting:
17658 vignette='PI/4+random(1)*PI/50':eval=frame
17663 @section vmafmotion
17665 Obtain the average vmaf motion score of a video.
17666 It is one of the component filters of VMAF.
17668 The obtained average motion score is printed through the logging system.
17670 In the below example the input file @file{ref.mpg} is being processed and score
17674 ffmpeg -i ref.mpg -lavfi vmafmotion -f null -
17678 Stack input videos vertically.
17680 All streams must be of same pixel format and of same width.
17682 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
17683 to create same output.
17685 The filter accept the following option:
17689 Set number of input streams. Default is 2.
17692 If set to 1, force the output to terminate when the shortest input
17693 terminates. Default value is 0.
17698 Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
17699 Deinterlacing Filter").
17701 Based on the process described by Martin Weston for BBC R&D, and
17702 implemented based on the de-interlace algorithm written by Jim
17703 Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
17704 uses filter coefficients calculated by BBC R&D.
17706 There are two sets of filter coefficients, so called "simple":
17707 and "complex". Which set of filter coefficients is used can
17708 be set by passing an optional parameter:
17712 Set the interlacing filter coefficients. Accepts one of the following values:
17716 Simple filter coefficient set.
17718 More-complex filter coefficient set.
17720 Default value is @samp{complex}.
17723 Specify which frames to deinterlace. Accept one of the following values:
17727 Deinterlace all frames,
17729 Only deinterlace frames marked as interlaced.
17732 Default value is @samp{all}.
17736 Video waveform monitor.
17738 The waveform monitor plots color component intensity. By default luminance
17739 only. Each column of the waveform corresponds to a column of pixels in the
17742 It accepts the following options:
17746 Can be either @code{row}, or @code{column}. Default is @code{column}.
17747 In row mode, the graph on the left side represents color component value 0 and
17748 the right side represents value = 255. In column mode, the top side represents
17749 color component value = 0 and bottom side represents value = 255.
17752 Set intensity. Smaller values are useful to find out how many values of the same
17753 luminance are distributed across input rows/columns.
17754 Default value is @code{0.04}. Allowed range is [0, 1].
17757 Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
17758 In mirrored mode, higher values will be represented on the left
17759 side for @code{row} mode and at the top for @code{column} mode. Default is
17760 @code{1} (mirrored).
17764 It accepts the following values:
17767 Presents information identical to that in the @code{parade}, except
17768 that the graphs representing color components are superimposed directly
17771 This display mode makes it easier to spot relative differences or similarities
17772 in overlapping areas of the color components that are supposed to be identical,
17773 such as neutral whites, grays, or blacks.
17776 Display separate graph for the color components side by side in
17777 @code{row} mode or one below the other in @code{column} mode.
17780 Display separate graph for the color components side by side in
17781 @code{column} mode or one below the other in @code{row} mode.
17783 Using this display mode makes it easy to spot color casts in the highlights
17784 and shadows of an image, by comparing the contours of the top and the bottom
17785 graphs of each waveform. Since whites, grays, and blacks are characterized
17786 by exactly equal amounts of red, green, and blue, neutral areas of the picture
17787 should display three waveforms of roughly equal width/height. If not, the
17788 correction is easy to perform by making level adjustments the three waveforms.
17790 Default is @code{stack}.
17792 @item components, c
17793 Set which color components to display. Default is 1, which means only luminance
17794 or red color component if input is in RGB colorspace. If is set for example to
17795 7 it will display all 3 (if) available color components.
17800 No envelope, this is default.
17803 Instant envelope, minimum and maximum values presented in graph will be easily
17804 visible even with small @code{step} value.
17807 Hold minimum and maximum values presented in graph across time. This way you
17808 can still spot out of range values without constantly looking at waveforms.
17811 Peak and instant envelope combined together.
17817 No filtering, this is default.
17820 Luma and chroma combined together.
17823 Similar as above, but shows difference between blue and red chroma.
17826 Similar as above, but use different colors.
17829 Displays only chroma.
17832 Displays actual color value on waveform.
17835 Similar as above, but with luma showing frequency of chroma values.
17839 Set which graticule to display.
17843 Do not display graticule.
17846 Display green graticule showing legal broadcast ranges.
17849 Display orange graticule showing legal broadcast ranges.
17853 Set graticule opacity.
17856 Set graticule flags.
17860 Draw numbers above lines. By default enabled.
17863 Draw dots instead of lines.
17867 Set scale used for displaying graticule.
17874 Default is digital.
17877 Set background opacity.
17880 @section weave, doubleweave
17882 The @code{weave} takes a field-based video input and join
17883 each two sequential fields into single frame, producing a new double
17884 height clip with half the frame rate and half the frame count.
17886 The @code{doubleweave} works same as @code{weave} but without
17887 halving frame rate and frame count.
17889 It accepts the following option:
17893 Set first field. Available values are:
17897 Set the frame as top-field-first.
17900 Set the frame as bottom-field-first.
17904 @subsection Examples
17908 Interlace video using @ref{select} and @ref{separatefields} filter:
17910 separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
17915 Apply the xBR high-quality magnification filter which is designed for pixel
17916 art. It follows a set of edge-detection rules, see
17917 @url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}.
17919 It accepts the following option:
17923 Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
17924 @code{3xBR} and @code{4} for @code{4xBR}.
17925 Default is @code{3}.
17929 Stack video inputs into custom layout.
17931 All streams must be of same pixel format.
17933 The filter accept the following option:
17937 Set number of input streams. Default is 2.
17940 Specify layout of inputs.
17941 This option requires the desired layout configuration to be explicitly set by the user.
17942 This sets position of each video input in output. Each input
17943 is separated by '|'.
17944 The first number represents the column, and the second number represents the row.
17945 Numbers start at 0 and are separated by '_'. Optionally one can use wX and hX,
17946 where X is video input from which to take width or height.
17947 Multiple values can be used when separated by '+'. In such
17948 case values are summed together.
17951 If set to 1, force the output to terminate when the shortest input
17952 terminates. Default value is 0.
17955 @subsection Examples
17959 Display 4 inputs into 2x2 grid,
17960 note that if inputs are of different sizes unused gaps might appear,
17961 as not all of output video is used.
17963 xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
17967 Display 4 inputs into 1x4 grid,
17968 note that if inputs are of different sizes unused gaps might appear,
17969 as not all of output video is used.
17971 xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
17975 Display 9 inputs into 3x3 grid,
17976 note that if inputs are of different sizes unused gaps might appear,
17977 as not all of output video is used.
17979 xstack=inputs=9:layout=w3_0|w3_h0+h2|w3_h0|0_h4|0_0|w3+w1_0|0_h1+h2|w3+w1_h0|w3+w1_h1+h2
17986 Deinterlace the input video ("yadif" means "yet another deinterlacing
17989 It accepts the following parameters:
17995 The interlacing mode to adopt. It accepts one of the following values:
17998 @item 0, send_frame
17999 Output one frame for each frame.
18000 @item 1, send_field
18001 Output one frame for each field.
18002 @item 2, send_frame_nospatial
18003 Like @code{send_frame}, but it skips the spatial interlacing check.
18004 @item 3, send_field_nospatial
18005 Like @code{send_field}, but it skips the spatial interlacing check.
18008 The default value is @code{send_frame}.
18011 The picture field parity assumed for the input interlaced video. It accepts one
18012 of the following values:
18016 Assume the top field is first.
18018 Assume the bottom field is first.
18020 Enable automatic detection of field parity.
18023 The default value is @code{auto}.
18024 If the interlacing is unknown or the decoder does not export this information,
18025 top field first will be assumed.
18028 Specify which frames to deinterlace. Accept one of the following
18033 Deinterlace all frames.
18034 @item 1, interlaced
18035 Only deinterlace frames marked as interlaced.
18038 The default value is @code{all}.
18041 @section yadif_cuda
18043 Deinterlace the input video using the @ref{yadif} algorithm, but implemented
18044 in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec
18047 It accepts the following parameters:
18053 The interlacing mode to adopt. It accepts one of the following values:
18056 @item 0, send_frame
18057 Output one frame for each frame.
18058 @item 1, send_field
18059 Output one frame for each field.
18060 @item 2, send_frame_nospatial
18061 Like @code{send_frame}, but it skips the spatial interlacing check.
18062 @item 3, send_field_nospatial
18063 Like @code{send_field}, but it skips the spatial interlacing check.
18066 The default value is @code{send_frame}.
18069 The picture field parity assumed for the input interlaced video. It accepts one
18070 of the following values:
18074 Assume the top field is first.
18076 Assume the bottom field is first.
18078 Enable automatic detection of field parity.
18081 The default value is @code{auto}.
18082 If the interlacing is unknown or the decoder does not export this information,
18083 top field first will be assumed.
18086 Specify which frames to deinterlace. Accept one of the following
18091 Deinterlace all frames.
18092 @item 1, interlaced
18093 Only deinterlace frames marked as interlaced.
18096 The default value is @code{all}.
18101 Apply Zoom & Pan effect.
18103 This filter accepts the following options:
18107 Set the zoom expression. Default is 1.
18111 Set the x and y expression. Default is 0.
18114 Set the duration expression in number of frames.
18115 This sets for how many number of frames effect will last for
18116 single input image.
18119 Set the output image size, default is 'hd720'.
18122 Set the output frame rate, default is '25'.
18125 Each expression can contain the following constants:
18144 Output frame count.
18148 Last calculated 'x' and 'y' position from 'x' and 'y' expression
18149 for current input frame.
18153 'x' and 'y' of last output frame of previous input frame or 0 when there was
18154 not yet such frame (first input frame).
18157 Last calculated zoom from 'z' expression for current input frame.
18160 Last calculated zoom of last output frame of previous input frame.
18163 Number of output frames for current input frame. Calculated from 'd' expression
18164 for each input frame.
18167 number of output frames created for previous input frame
18170 Rational number: input width / input height
18173 sample aspect ratio
18176 display aspect ratio
18180 @subsection Examples
18184 Zoom-in up to 1.5 and pan at same time to some spot near center of picture:
18186 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
18190 Zoom-in up to 1.5 and pan always at center of picture:
18192 zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
18196 Same as above but without pausing:
18198 zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
18204 Scale (resize) the input video, using the z.lib library:
18205 @url{https://github.com/sekrit-twc/zimg}. To enable compilation of this
18206 filter, you need to configure FFmpeg with @code{--enable-libzimg}.
18208 The zscale filter forces the output display aspect ratio to be the same
18209 as the input, by changing the output sample aspect ratio.
18211 If the input image format is different from the format requested by
18212 the next filter, the zscale filter will convert the input to the
18215 @subsection Options
18216 The filter accepts the following options.
18221 Set the output video dimension expression. Default value is the input
18224 If the @var{width} or @var{w} value is 0, the input width is used for
18225 the output. If the @var{height} or @var{h} value is 0, the input height
18226 is used for the output.
18228 If one and only one of the values is -n with n >= 1, the zscale filter
18229 will use a value that maintains the aspect ratio of the input image,
18230 calculated from the other specified dimension. After that it will,
18231 however, make sure that the calculated dimension is divisible by n and
18232 adjust the value if necessary.
18234 If both values are -n with n >= 1, the behavior will be identical to
18235 both values being set to 0 as previously detailed.
18237 See below for the list of accepted constants for use in the dimension
18241 Set the video size. For the syntax of this option, check the
18242 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18245 Set the dither type.
18247 Possible values are:
18252 @item error_diffusion
18258 Set the resize filter type.
18260 Possible values are:
18270 Default is bilinear.
18273 Set the color range.
18275 Possible values are:
18282 Default is same as input.
18285 Set the color primaries.
18287 Possible values are:
18297 Default is same as input.
18300 Set the transfer characteristics.
18302 Possible values are:
18316 Default is same as input.
18319 Set the colorspace matrix.
18321 Possible value are:
18332 Default is same as input.
18335 Set the input color range.
18337 Possible values are:
18344 Default is same as input.
18346 @item primariesin, pin
18347 Set the input color primaries.
18349 Possible values are:
18359 Default is same as input.
18361 @item transferin, tin
18362 Set the input transfer characteristics.
18364 Possible values are:
18375 Default is same as input.
18377 @item matrixin, min
18378 Set the input colorspace matrix.
18380 Possible value are:
18392 Set the output chroma location.
18394 Possible values are:
18405 @item chromalin, cin
18406 Set the input chroma location.
18408 Possible values are:
18420 Set the nominal peak luminance.
18423 The values of the @option{w} and @option{h} options are expressions
18424 containing the following constants:
18429 The input width and height
18433 These are the same as @var{in_w} and @var{in_h}.
18437 The output (scaled) width and height
18441 These are the same as @var{out_w} and @var{out_h}
18444 The same as @var{iw} / @var{ih}
18447 input sample aspect ratio
18450 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
18454 horizontal and vertical input chroma subsample values. For example for the
18455 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
18459 horizontal and vertical output chroma subsample values. For example for the
18460 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
18466 @c man end VIDEO FILTERS
18468 @chapter OpenCL Video Filters
18469 @c man begin OPENCL VIDEO FILTERS
18471 Below is a description of the currently available OpenCL video filters.
18473 To enable compilation of these filters you need to configure FFmpeg with
18474 @code{--enable-opencl}.
18476 Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph.
18479 @item -init_hw_device opencl[=@var{name}][:@var{device}[,@var{key=value}...]]
18480 Initialise a new hardware device of type @var{opencl} called @var{name}, using the
18481 given device parameters.
18483 @item -filter_hw_device @var{name}
18484 Pass the hardware device called @var{name} to all filters in any filter graph.
18488 For more detailed information see @url{https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options}
18492 Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it.
18494 -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
18498 Since OpenCL filters are not able to access frame data in normal memory, all frame data needs to be uploaded(@ref{hwupload}) to hardware surfaces connected to the appropriate device before being used and then downloaded(@ref{hwdownload}) back to normal memory. Note that @ref{hwupload} will upload to a surface with the same layout as the software frame, so it may be necessary to add a @ref{format} filter immediately before to get the input into the right format and @ref{hwdownload} does not support all formats on the output - it may be necessary to insert an additional @ref{format} filter immediately following in the graph to get the output in a supported format.
18500 @section avgblur_opencl
18502 Apply average blur filter.
18504 The filter accepts the following options:
18508 Set horizontal radius size.
18509 Range is @code{[1, 1024]} and default value is @code{1}.
18512 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
18515 Set vertical radius size. Range is @code{[1, 1024]} and default value is @code{0}. If zero, @code{sizeX} value will be used.
18518 @subsection Example
18522 Apply average blur filter with horizontal and vertical size of 3, setting each pixel of the output to the average value of the 7x7 region centered on it in the input. For pixels on the edges of the image, the region does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations.
18524 -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
18528 @section boxblur_opencl
18530 Apply a boxblur algorithm to the input video.
18532 It accepts the following parameters:
18536 @item luma_radius, lr
18537 @item luma_power, lp
18538 @item chroma_radius, cr
18539 @item chroma_power, cp
18540 @item alpha_radius, ar
18541 @item alpha_power, ap
18545 A description of the accepted options follows.
18548 @item luma_radius, lr
18549 @item chroma_radius, cr
18550 @item alpha_radius, ar
18551 Set an expression for the box radius in pixels used for blurring the
18552 corresponding input plane.
18554 The radius value must be a non-negative number, and must not be
18555 greater than the value of the expression @code{min(w,h)/2} for the
18556 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
18559 Default value for @option{luma_radius} is "2". If not specified,
18560 @option{chroma_radius} and @option{alpha_radius} default to the
18561 corresponding value set for @option{luma_radius}.
18563 The expressions can contain the following constants:
18567 The input width and height in pixels.
18571 The input chroma image width and height in pixels.
18575 The horizontal and vertical chroma subsample values. For example, for the
18576 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
18579 @item luma_power, lp
18580 @item chroma_power, cp
18581 @item alpha_power, ap
18582 Specify how many times the boxblur filter is applied to the
18583 corresponding plane.
18585 Default value for @option{luma_power} is 2. If not specified,
18586 @option{chroma_power} and @option{alpha_power} default to the
18587 corresponding value set for @option{luma_power}.
18589 A value of 0 will disable the effect.
18592 @subsection Examples
18594 Apply boxblur filter, setting each pixel of the output to the average value of box-radiuses @var{luma_radius}, @var{chroma_radius}, @var{alpha_radius} for each plane respectively. The filter will apply @var{luma_power}, @var{chroma_power}, @var{alpha_power} times onto the corresponding plane. For pixels on the edges of the image, the radius does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations.
18598 Apply a boxblur filter with the luma, chroma, and alpha radius
18599 set to 2 and luma, chroma, and alpha power set to 3. The filter will run 3 times with box-radius set to 2 for every plane of the image.
18601 -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
18602 -i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
18606 Apply a boxblur filter with luma radius set to 2, luma_power to 1, chroma_radius to 4, chroma_power to 5, alpha_radius to 3 and alpha_power to 7.
18608 For the luma plane, a 2x2 box radius will be run once.
18610 For the chroma plane, a 4x4 box radius will be run 5 times.
18612 For the alpha plane, a 3x3 box radius will be run 7 times.
18614 -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
18618 @section convolution_opencl
18620 Apply convolution of 3x3, 5x5, 7x7 matrix.
18622 The filter accepts the following options:
18629 Set matrix for each plane.
18630 Matrix is sequence of 9, 25 or 49 signed numbers.
18631 Default value for each plane is @code{0 0 0 0 1 0 0 0 0}.
18637 Set multiplier for calculated value for each plane.
18638 If unset or 0, it will be sum of all matrix elements.
18639 The option value must be an float number greater or equal to @code{0.0}. Default value is @code{1.0}.
18645 Set bias for each plane. This value is added to the result of the multiplication.
18646 Useful for making the overall image brighter or darker.
18647 The option value must be an float number greater or equal to @code{0.0}. Default value is @code{0.0}.
18651 @subsection Examples
18657 -i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT
18663 -i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT
18667 Apply edge enhance:
18669 -i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT
18675 -i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT
18679 Apply laplacian edge detector which includes diagonals:
18681 -i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT
18687 -i INPUT -vf "hwupload, convolution_opencl=-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, hwdownload" OUTPUT
18691 @section dilation_opencl
18693 Apply dilation effect to the video.
18695 This filter replaces the pixel by the local(3x3) maximum.
18697 It accepts the following options:
18704 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
18705 If @code{0}, plane will remain unchanged.
18708 Flag which specifies the pixel to refer to.
18709 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
18711 Flags to local 3x3 coordinates region centered on @code{x}:
18720 @subsection Example
18724 Apply dilation filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local maximum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local maximum is more then threshold of the corresponding plane, output pixel will be set to input pixel + threshold of corresponding plane.
18726 -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
18730 @section erosion_opencl
18732 Apply erosion effect to the video.
18734 This filter replaces the pixel by the local(3x3) minimum.
18736 It accepts the following options:
18743 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
18744 If @code{0}, plane will remain unchanged.
18747 Flag which specifies the pixel to refer to.
18748 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
18750 Flags to local 3x3 coordinates region centered on @code{x}:
18759 @subsection Example
18763 Apply erosion filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local minimum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local minimum is more then threshold of the corresponding plane, output pixel will be set to input pixel - threshold of corresponding plane.
18765 -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
18769 @section overlay_opencl
18771 Overlay one video on top of another.
18773 It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid.
18774 This filter requires same memory layout for all the inputs. So, format conversion may be needed.
18776 The filter accepts the following options:
18781 Set the x coordinate of the overlaid video on the main video.
18782 Default value is @code{0}.
18785 Set the x coordinate of the overlaid video on the main video.
18786 Default value is @code{0}.
18790 @subsection Examples
18794 Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format.
18796 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
18799 The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p.
18801 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
18806 @section prewitt_opencl
18808 Apply the Prewitt operator (@url{https://en.wikipedia.org/wiki/Prewitt_operator}) to input video stream.
18810 The filter accepts the following option:
18814 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
18817 Set value which will be multiplied with filtered result.
18818 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
18821 Set value which will be added to filtered result.
18822 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
18825 @subsection Example
18829 Apply the Prewitt operator with scale set to 2 and delta set to 10.
18831 -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
18835 @section roberts_opencl
18836 Apply the Roberts cross operator (@url{https://en.wikipedia.org/wiki/Roberts_cross}) to input video stream.
18838 The filter accepts the following option:
18842 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
18845 Set value which will be multiplied with filtered result.
18846 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
18849 Set value which will be added to filtered result.
18850 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
18853 @subsection Example
18857 Apply the Roberts cross operator with scale set to 2 and delta set to 10
18859 -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
18863 @section sobel_opencl
18865 Apply the Sobel operator (@url{https://en.wikipedia.org/wiki/Sobel_operator}) to input video stream.
18867 The filter accepts the following option:
18871 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
18874 Set value which will be multiplied with filtered result.
18875 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
18878 Set value which will be added to filtered result.
18879 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
18882 @subsection Example
18886 Apply sobel operator with scale set to 2 and delta set to 10
18888 -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
18892 @section tonemap_opencl
18894 Perform HDR(PQ/HLG) to SDR conversion with tone-mapping.
18896 It accepts the following parameters:
18900 Specify the tone-mapping operator to be used. Same as tonemap option in @ref{tonemap}.
18903 Tune the tone mapping algorithm. same as param option in @ref{tonemap}.
18906 Apply desaturation for highlights that exceed this level of brightness. The
18907 higher the parameter, the more color information will be preserved. This
18908 setting helps prevent unnaturally blown-out colors for super-highlights, by
18909 (smoothly) turning into white instead. This makes images feel more natural,
18910 at the cost of reducing information about out-of-range colors.
18912 The default value is 0.5, and the algorithm here is a little different from
18913 the cpu version tonemap currently. A setting of 0.0 disables this option.
18916 The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold
18917 is used to detect whether the scene has changed or not. If the distance beween
18918 the current frame average brightness and the current running average exceeds
18919 a threshold value, we would re-calculate scene average and peak brightness.
18920 The default value is 0.2.
18923 Specify the output pixel format.
18925 Currently supported formats are:
18932 Set the output color range.
18934 Possible values are:
18940 Default is same as input.
18943 Set the output color primaries.
18945 Possible values are:
18951 Default is same as input.
18954 Set the output transfer characteristics.
18956 Possible values are:
18965 Set the output colorspace matrix.
18967 Possible value are:
18973 Default is same as input.
18977 @subsection Example
18981 Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator.
18983 -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
18987 @section unsharp_opencl
18989 Sharpen or blur the input video.
18991 It accepts the following parameters:
18994 @item luma_msize_x, lx
18995 Set the luma matrix horizontal size.
18996 Range is @code{[1, 23]} and default value is @code{5}.
18998 @item luma_msize_y, ly
18999 Set the luma matrix vertical size.
19000 Range is @code{[1, 23]} and default value is @code{5}.
19002 @item luma_amount, la
19003 Set the luma effect strength.
19004 Range is @code{[-10, 10]} and default value is @code{1.0}.
19006 Negative values will blur the input video, while positive values will
19007 sharpen it, a value of zero will disable the effect.
19009 @item chroma_msize_x, cx
19010 Set the chroma matrix horizontal size.
19011 Range is @code{[1, 23]} and default value is @code{5}.
19013 @item chroma_msize_y, cy
19014 Set the chroma matrix vertical size.
19015 Range is @code{[1, 23]} and default value is @code{5}.
19017 @item chroma_amount, ca
19018 Set the chroma effect strength.
19019 Range is @code{[-10, 10]} and default value is @code{0.0}.
19021 Negative values will blur the input video, while positive values will
19022 sharpen it, a value of zero will disable the effect.
19026 All parameters are optional and default to the equivalent of the
19027 string '5:5:1.0:5:5:0.0'.
19029 @subsection Examples
19033 Apply strong luma sharpen effect:
19035 -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
19039 Apply a strong blur of both luma and chroma parameters:
19041 -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
19045 @c man end OPENCL VIDEO FILTERS
19047 @chapter Video Sources
19048 @c man begin VIDEO SOURCES
19050 Below is a description of the currently available video sources.
19054 Buffer video frames, and make them available to the filter chain.
19056 This source is mainly intended for a programmatic use, in particular
19057 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
19059 It accepts the following parameters:
19064 Specify the size (width and height) of the buffered video frames. For the
19065 syntax of this option, check the
19066 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19069 The input video width.
19072 The input video height.
19075 A string representing the pixel format of the buffered video frames.
19076 It may be a number corresponding to a pixel format, or a pixel format
19080 Specify the timebase assumed by the timestamps of the buffered frames.
19083 Specify the frame rate expected for the video stream.
19085 @item pixel_aspect, sar
19086 The sample (pixel) aspect ratio of the input video.
19089 Specify the optional parameters to be used for the scale filter which
19090 is automatically inserted when an input change is detected in the
19091 input size or format.
19093 @item hw_frames_ctx
19094 When using a hardware pixel format, this should be a reference to an
19095 AVHWFramesContext describing input frames.
19100 buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
19103 will instruct the source to accept video frames with size 320x240 and
19104 with format "yuv410p", assuming 1/24 as the timestamps timebase and
19105 square pixels (1:1 sample aspect ratio).
19106 Since the pixel format with name "yuv410p" corresponds to the number 6
19107 (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
19108 this example corresponds to:
19110 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
19113 Alternatively, the options can be specified as a flat string, but this
19114 syntax is deprecated:
19116 @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}]
19120 Create a pattern generated by an elementary cellular automaton.
19122 The initial state of the cellular automaton can be defined through the
19123 @option{filename} and @option{pattern} options. If such options are
19124 not specified an initial state is created randomly.
19126 At each new frame a new row in the video is filled with the result of
19127 the cellular automaton next generation. The behavior when the whole
19128 frame is filled is defined by the @option{scroll} option.
19130 This source accepts the following options:
19134 Read the initial cellular automaton state, i.e. the starting row, from
19135 the specified file.
19136 In the file, each non-whitespace character is considered an alive
19137 cell, a newline will terminate the row, and further characters in the
19138 file will be ignored.
19141 Read the initial cellular automaton state, i.e. the starting row, from
19142 the specified string.
19144 Each non-whitespace character in the string is considered an alive
19145 cell, a newline will terminate the row, and further characters in the
19146 string will be ignored.
19149 Set the video rate, that is the number of frames generated per second.
19152 @item random_fill_ratio, ratio
19153 Set the random fill ratio for the initial cellular automaton row. It
19154 is a floating point number value ranging from 0 to 1, defaults to
19157 This option is ignored when a file or a pattern is specified.
19159 @item random_seed, seed
19160 Set the seed for filling randomly the initial row, must be an integer
19161 included between 0 and UINT32_MAX. If not specified, or if explicitly
19162 set to -1, the filter will try to use a good random seed on a best
19166 Set the cellular automaton rule, it is a number ranging from 0 to 255.
19167 Default value is 110.
19170 Set the size of the output video. For the syntax of this option, check the
19171 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19173 If @option{filename} or @option{pattern} is specified, the size is set
19174 by default to the width of the specified initial state row, and the
19175 height is set to @var{width} * PHI.
19177 If @option{size} is set, it must contain the width of the specified
19178 pattern string, and the specified pattern will be centered in the
19181 If a filename or a pattern string is not specified, the size value
19182 defaults to "320x518" (used for a randomly generated initial state).
19185 If set to 1, scroll the output upward when all the rows in the output
19186 have been already filled. If set to 0, the new generated row will be
19187 written over the top row just after the bottom row is filled.
19190 @item start_full, full
19191 If set to 1, completely fill the output with generated rows before
19192 outputting the first frame.
19193 This is the default behavior, for disabling set the value to 0.
19196 If set to 1, stitch the left and right row edges together.
19197 This is the default behavior, for disabling set the value to 0.
19200 @subsection Examples
19204 Read the initial state from @file{pattern}, and specify an output of
19207 cellauto=f=pattern:s=200x400
19211 Generate a random initial row with a width of 200 cells, with a fill
19214 cellauto=ratio=2/3:s=200x200
19218 Create a pattern generated by rule 18 starting by a single alive cell
19219 centered on an initial row with width 100:
19221 cellauto=p=@@:s=100x400:full=0:rule=18
19225 Specify a more elaborated initial pattern:
19227 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
19232 @anchor{coreimagesrc}
19233 @section coreimagesrc
19234 Video source generated on GPU using Apple's CoreImage API on OSX.
19236 This video source is a specialized version of the @ref{coreimage} video filter.
19237 Use a core image generator at the beginning of the applied filterchain to
19238 generate the content.
19240 The coreimagesrc video source accepts the following options:
19242 @item list_generators
19243 List all available generators along with all their respective options as well as
19244 possible minimum and maximum values along with the default values.
19246 list_generators=true
19250 Specify the size of the sourced video. For the syntax of this option, check the
19251 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19252 The default value is @code{320x240}.
19255 Specify the frame rate of the sourced video, as the number of frames
19256 generated per second. It has to be a string in the format
19257 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
19258 number or a valid video frame rate abbreviation. The default value is
19262 Set the sample aspect ratio of the sourced video.
19265 Set the duration of the sourced video. See
19266 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
19267 for the accepted syntax.
19269 If not specified, or the expressed duration is negative, the video is
19270 supposed to be generated forever.
19273 Additionally, all options of the @ref{coreimage} video filter are accepted.
19274 A complete filterchain can be used for further processing of the
19275 generated input without CPU-HOST transfer. See @ref{coreimage} documentation
19276 and examples for details.
19278 @subsection Examples
19283 Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
19284 given as complete and escaped command-line for Apple's standard bash shell:
19286 ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
19288 This example is equivalent to the QRCode example of @ref{coreimage} without the
19289 need for a nullsrc video source.
19293 @section mandelbrot
19295 Generate a Mandelbrot set fractal, and progressively zoom towards the
19296 point specified with @var{start_x} and @var{start_y}.
19298 This source accepts the following options:
19303 Set the terminal pts value. Default value is 400.
19306 Set the terminal scale value.
19307 Must be a floating point value. Default value is 0.3.
19310 Set the inner coloring mode, that is the algorithm used to draw the
19311 Mandelbrot fractal internal region.
19313 It shall assume one of the following values:
19318 Show time until convergence.
19320 Set color based on point closest to the origin of the iterations.
19325 Default value is @var{mincol}.
19328 Set the bailout value. Default value is 10.0.
19331 Set the maximum of iterations performed by the rendering
19332 algorithm. Default value is 7189.
19335 Set outer coloring mode.
19336 It shall assume one of following values:
19338 @item iteration_count
19339 Set iteration cound mode.
19340 @item normalized_iteration_count
19341 set normalized iteration count mode.
19343 Default value is @var{normalized_iteration_count}.
19346 Set frame rate, expressed as number of frames per second. Default
19350 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
19351 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
19354 Set the initial scale value. Default value is 3.0.
19357 Set the initial x position. Must be a floating point value between
19358 -100 and 100. Default value is -0.743643887037158704752191506114774.
19361 Set the initial y position. Must be a floating point value between
19362 -100 and 100. Default value is -0.131825904205311970493132056385139.
19367 Generate various test patterns, as generated by the MPlayer test filter.
19369 The size of the generated video is fixed, and is 256x256.
19370 This source is useful in particular for testing encoding features.
19372 This source accepts the following options:
19377 Specify the frame rate of the sourced video, as the number of frames
19378 generated per second. It has to be a string in the format
19379 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
19380 number or a valid video frame rate abbreviation. The default value is
19384 Set the duration of the sourced video. See
19385 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
19386 for the accepted syntax.
19388 If not specified, or the expressed duration is negative, the video is
19389 supposed to be generated forever.
19393 Set the number or the name of the test to perform. Supported tests are:
19409 Default value is "all", which will cycle through the list of all tests.
19414 mptestsrc=t=dc_luma
19417 will generate a "dc_luma" test pattern.
19419 @section frei0r_src
19421 Provide a frei0r source.
19423 To enable compilation of this filter you need to install the frei0r
19424 header and configure FFmpeg with @code{--enable-frei0r}.
19426 This source accepts the following parameters:
19431 The size of the video to generate. For the syntax of this option, check the
19432 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19435 The framerate of the generated video. It may be a string of the form
19436 @var{num}/@var{den} or a frame rate abbreviation.
19439 The name to the frei0r source to load. For more information regarding frei0r and
19440 how to set the parameters, read the @ref{frei0r} section in the video filters
19443 @item filter_params
19444 A '|'-separated list of parameters to pass to the frei0r source.
19448 For example, to generate a frei0r partik0l source with size 200x200
19449 and frame rate 10 which is overlaid on the overlay filter main input:
19451 frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
19456 Generate a life pattern.
19458 This source is based on a generalization of John Conway's life game.
19460 The sourced input represents a life grid, each pixel represents a cell
19461 which can be in one of two possible states, alive or dead. Every cell
19462 interacts with its eight neighbours, which are the cells that are
19463 horizontally, vertically, or diagonally adjacent.
19465 At each interaction the grid evolves according to the adopted rule,
19466 which specifies the number of neighbor alive cells which will make a
19467 cell stay alive or born. The @option{rule} option allows one to specify
19470 This source accepts the following options:
19474 Set the file from which to read the initial grid state. In the file,
19475 each non-whitespace character is considered an alive cell, and newline
19476 is used to delimit the end of each row.
19478 If this option is not specified, the initial grid is generated
19482 Set the video rate, that is the number of frames generated per second.
19485 @item random_fill_ratio, ratio
19486 Set the random fill ratio for the initial random grid. It is a
19487 floating point number value ranging from 0 to 1, defaults to 1/PHI.
19488 It is ignored when a file is specified.
19490 @item random_seed, seed
19491 Set the seed for filling the initial random grid, must be an integer
19492 included between 0 and UINT32_MAX. If not specified, or if explicitly
19493 set to -1, the filter will try to use a good random seed on a best
19499 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
19500 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
19501 @var{NS} specifies the number of alive neighbor cells which make a
19502 live cell stay alive, and @var{NB} the number of alive neighbor cells
19503 which make a dead cell to become alive (i.e. to "born").
19504 "s" and "b" can be used in place of "S" and "B", respectively.
19506 Alternatively a rule can be specified by an 18-bits integer. The 9
19507 high order bits are used to encode the next cell state if it is alive
19508 for each number of neighbor alive cells, the low order bits specify
19509 the rule for "borning" new cells. Higher order bits encode for an
19510 higher number of neighbor cells.
19511 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
19512 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
19514 Default value is "S23/B3", which is the original Conway's game of life
19515 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
19516 cells, and will born a new cell if there are three alive cells around
19520 Set the size of the output video. For the syntax of this option, check the
19521 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19523 If @option{filename} is specified, the size is set by default to the
19524 same size of the input file. If @option{size} is set, it must contain
19525 the size specified in the input file, and the initial grid defined in
19526 that file is centered in the larger resulting area.
19528 If a filename is not specified, the size value defaults to "320x240"
19529 (used for a randomly generated initial grid).
19532 If set to 1, stitch the left and right grid edges together, and the
19533 top and bottom edges also. Defaults to 1.
19536 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
19537 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
19538 value from 0 to 255.
19541 Set the color of living (or new born) cells.
19544 Set the color of dead cells. If @option{mold} is set, this is the first color
19545 used to represent a dead cell.
19548 Set mold color, for definitely dead and moldy cells.
19550 For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the
19551 ffmpeg-utils manual,ffmpeg-utils}.
19554 @subsection Examples
19558 Read a grid from @file{pattern}, and center it on a grid of size
19561 life=f=pattern:s=300x300
19565 Generate a random grid of size 200x200, with a fill ratio of 2/3:
19567 life=ratio=2/3:s=200x200
19571 Specify a custom rule for evolving a randomly generated grid:
19577 Full example with slow death effect (mold) using @command{ffplay}:
19579 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
19586 @anchor{haldclutsrc}
19589 @anchor{pal100bars}
19590 @anchor{rgbtestsrc}
19592 @anchor{smptehdbars}
19595 @anchor{yuvtestsrc}
19596 @section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
19598 The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
19600 The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
19602 The @code{color} source provides an uniformly colored input.
19604 The @code{haldclutsrc} source provides an identity Hald CLUT. See also
19605 @ref{haldclut} filter.
19607 The @code{nullsrc} source returns unprocessed video frames. It is
19608 mainly useful to be employed in analysis / debugging tools, or as the
19609 source for filters which ignore the input data.
19611 The @code{pal75bars} source generates a color bars pattern, based on
19612 EBU PAL recommendations with 75% color levels.
19614 The @code{pal100bars} source generates a color bars pattern, based on
19615 EBU PAL recommendations with 100% color levels.
19617 The @code{rgbtestsrc} source generates an RGB test pattern useful for
19618 detecting RGB vs BGR issues. You should see a red, green and blue
19619 stripe from top to bottom.
19621 The @code{smptebars} source generates a color bars pattern, based on
19622 the SMPTE Engineering Guideline EG 1-1990.
19624 The @code{smptehdbars} source generates a color bars pattern, based on
19625 the SMPTE RP 219-2002.
19627 The @code{testsrc} source generates a test video pattern, showing a
19628 color pattern, a scrolling gradient and a timestamp. This is mainly
19629 intended for testing purposes.
19631 The @code{testsrc2} source is similar to testsrc, but supports more
19632 pixel formats instead of just @code{rgb24}. This allows using it as an
19633 input for other tests without requiring a format conversion.
19635 The @code{yuvtestsrc} source generates an YUV test pattern. You should
19636 see a y, cb and cr stripe from top to bottom.
19638 The sources accept the following parameters:
19643 Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
19644 source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
19645 pixels to be used as identity matrix for 3D lookup tables. Each component is
19646 coded on a @code{1/(N*N)} scale.
19649 Specify the color of the source, only available in the @code{color}
19650 source. For the syntax of this option, check the
19651 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
19654 Specify the size of the sourced video. For the syntax of this option, check the
19655 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19656 The default value is @code{320x240}.
19658 This option is not available with the @code{allrgb}, @code{allyuv}, and
19659 @code{haldclutsrc} filters.
19662 Specify the frame rate of the sourced video, as the number of frames
19663 generated per second. It has to be a string in the format
19664 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
19665 number or a valid video frame rate abbreviation. The default value is
19669 Set the duration of the sourced video. See
19670 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
19671 for the accepted syntax.
19673 If not specified, or the expressed duration is negative, the video is
19674 supposed to be generated forever.
19677 Set the sample aspect ratio of the sourced video.
19680 Specify the alpha (opacity) of the background, only available in the
19681 @code{testsrc2} source. The value must be between 0 (fully transparent) and
19682 255 (fully opaque, the default).
19685 Set the number of decimals to show in the timestamp, only available in the
19686 @code{testsrc} source.
19688 The displayed timestamp value will correspond to the original
19689 timestamp value multiplied by the power of 10 of the specified
19690 value. Default value is 0.
19693 @subsection Examples
19697 Generate a video with a duration of 5.3 seconds, with size
19698 176x144 and a frame rate of 10 frames per second:
19700 testsrc=duration=5.3:size=qcif:rate=10
19704 The following graph description will generate a red source
19705 with an opacity of 0.2, with size "qcif" and a frame rate of 10
19708 color=c=red@@0.2:s=qcif:r=10
19712 If the input content is to be ignored, @code{nullsrc} can be used. The
19713 following command generates noise in the luminance plane by employing
19714 the @code{geq} filter:
19716 nullsrc=s=256x256, geq=random(1)*255:128:128
19720 @subsection Commands
19722 The @code{color} source supports the following commands:
19726 Set the color of the created image. Accepts the same syntax of the
19727 corresponding @option{color} option.
19732 Generate video using an OpenCL program.
19737 OpenCL program source file.
19740 Kernel name in program.
19743 Size of frames to generate. This must be set.
19746 Pixel format to use for the generated frames. This must be set.
19749 Number of frames generated every second. Default value is '25'.
19753 For details of how the program loading works, see the @ref{program_opencl}
19760 Generate a colour ramp by setting pixel values from the position of the pixel
19761 in the output image. (Note that this will work with all pixel formats, but
19762 the generated output will not be the same.)
19764 __kernel void ramp(__write_only image2d_t dst,
19765 unsigned int index)
19767 int2 loc = (int2)(get_global_id(0), get_global_id(1));
19770 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
19772 write_imagef(dst, loc, val);
19777 Generate a Sierpinski carpet pattern, panning by a single pixel each frame.
19779 __kernel void sierpinski_carpet(__write_only image2d_t dst,
19780 unsigned int index)
19782 int2 loc = (int2)(get_global_id(0), get_global_id(1));
19784 float4 value = 0.0f;
19785 int x = loc.x + index;
19786 int y = loc.y + index;
19787 while (x > 0 || y > 0) {
19788 if (x % 3 == 1 && y % 3 == 1) {
19796 write_imagef(dst, loc, value);
19802 @c man end VIDEO SOURCES
19804 @chapter Video Sinks
19805 @c man begin VIDEO SINKS
19807 Below is a description of the currently available video sinks.
19809 @section buffersink
19811 Buffer video frames, and make them available to the end of the filter
19814 This sink is mainly intended for programmatic use, in particular
19815 through the interface defined in @file{libavfilter/buffersink.h}
19816 or the options system.
19818 It accepts a pointer to an AVBufferSinkContext structure, which
19819 defines the incoming buffers' formats, to be passed as the opaque
19820 parameter to @code{avfilter_init_filter} for initialization.
19824 Null video sink: do absolutely nothing with the input video. It is
19825 mainly useful as a template and for use in analysis / debugging
19828 @c man end VIDEO SINKS
19830 @chapter Multimedia Filters
19831 @c man begin MULTIMEDIA FILTERS
19833 Below is a description of the currently available multimedia filters.
19837 Convert input audio to a video output, displaying the audio bit scope.
19839 The filter accepts the following options:
19843 Set frame rate, expressed as number of frames per second. Default
19847 Specify the video size for the output. For the syntax of this option, check the
19848 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19849 Default value is @code{1024x256}.
19852 Specify list of colors separated by space or by '|' which will be used to
19853 draw channels. Unrecognized or missing colors will be replaced
19857 @section ahistogram
19859 Convert input audio to a video output, displaying the volume histogram.
19861 The filter accepts the following options:
19865 Specify how histogram is calculated.
19867 It accepts the following values:
19870 Use single histogram for all channels.
19872 Use separate histogram for each channel.
19874 Default is @code{single}.
19877 Set frame rate, expressed as number of frames per second. Default
19881 Specify the video size for the output. For the syntax of this option, check the
19882 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19883 Default value is @code{hd720}.
19888 It accepts the following values:
19899 reverse logarithmic
19901 Default is @code{log}.
19904 Set amplitude scale.
19906 It accepts the following values:
19913 Default is @code{log}.
19916 Set how much frames to accumulate in histogram.
19917 Defauls is 1. Setting this to -1 accumulates all frames.
19920 Set histogram ratio of window height.
19923 Set sonogram sliding.
19925 It accepts the following values:
19928 replace old rows with new ones.
19930 scroll from top to bottom.
19932 Default is @code{replace}.
19935 @section aphasemeter
19937 Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase},
19938 representing mean phase of current audio frame. A video output can also be produced and is
19939 enabled by default. The audio is passed through as first output.
19941 Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in
19942 range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase
19943 and @code{1} means channels are in phase.
19945 The filter accepts the following options, all related to its video output:
19949 Set the output frame rate. Default value is @code{25}.
19952 Set the video size for the output. For the syntax of this option, check the
19953 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19954 Default value is @code{800x400}.
19959 Specify the red, green, blue contrast. Default values are @code{2},
19960 @code{7} and @code{1}.
19961 Allowed range is @code{[0, 255]}.
19964 Set color which will be used for drawing median phase. If color is
19965 @code{none} which is default, no median phase value will be drawn.
19968 Enable video output. Default is enabled.
19971 @section avectorscope
19973 Convert input audio to a video output, representing the audio vector
19976 The filter is used to measure the difference between channels of stereo
19977 audio stream. A monoaural signal, consisting of identical left and right
19978 signal, results in straight vertical line. Any stereo separation is visible
19979 as a deviation from this line, creating a Lissajous figure.
19980 If the straight (or deviation from it) but horizontal line appears this
19981 indicates that the left and right channels are out of phase.
19983 The filter accepts the following options:
19987 Set the vectorscope mode.
19989 Available values are:
19992 Lissajous rotated by 45 degrees.
19995 Same as above but not rotated.
19998 Shape resembling half of circle.
20001 Default value is @samp{lissajous}.
20004 Set the video size for the output. For the syntax of this option, check the
20005 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20006 Default value is @code{400x400}.
20009 Set the output frame rate. Default value is @code{25}.
20015 Specify the red, green, blue and alpha contrast. Default values are @code{40},
20016 @code{160}, @code{80} and @code{255}.
20017 Allowed range is @code{[0, 255]}.
20023 Specify the red, green, blue and alpha fade. Default values are @code{15},
20024 @code{10}, @code{5} and @code{5}.
20025 Allowed range is @code{[0, 255]}.
20028 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}.
20029 Values lower than @var{1} will auto adjust zoom factor to maximal possible value.
20032 Set the vectorscope drawing mode.
20034 Available values are:
20037 Draw dot for each sample.
20040 Draw line between previous and current sample.
20043 Default value is @samp{dot}.
20046 Specify amplitude scale of audio samples.
20048 Available values are:
20064 Swap left channel axis with right channel axis.
20074 Mirror only x axis.
20077 Mirror only y axis.
20085 @subsection Examples
20089 Complete example using @command{ffplay}:
20091 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
20092 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
20096 @section bench, abench
20098 Benchmark part of a filtergraph.
20100 The filter accepts the following options:
20104 Start or stop a timer.
20106 Available values are:
20109 Get the current time, set it as frame metadata (using the key
20110 @code{lavfi.bench.start_time}), and forward the frame to the next filter.
20113 Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
20114 the input frame metadata to get the time difference. Time difference, average,
20115 maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
20116 @code{min}) are then printed. The timestamps are expressed in seconds.
20120 @subsection Examples
20124 Benchmark @ref{selectivecolor} filter:
20126 bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
20132 Concatenate audio and video streams, joining them together one after the
20135 The filter works on segments of synchronized video and audio streams. All
20136 segments must have the same number of streams of each type, and that will
20137 also be the number of streams at output.
20139 The filter accepts the following options:
20144 Set the number of segments. Default is 2.
20147 Set the number of output video streams, that is also the number of video
20148 streams in each segment. Default is 1.
20151 Set the number of output audio streams, that is also the number of audio
20152 streams in each segment. Default is 0.
20155 Activate unsafe mode: do not fail if segments have a different format.
20159 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
20160 @var{a} audio outputs.
20162 There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
20163 segment, in the same order as the outputs, then the inputs for the second
20166 Related streams do not always have exactly the same duration, for various
20167 reasons including codec frame size or sloppy authoring. For that reason,
20168 related synchronized streams (e.g. a video and its audio track) should be
20169 concatenated at once. The concat filter will use the duration of the longest
20170 stream in each segment (except the last one), and if necessary pad shorter
20171 audio streams with silence.
20173 For this filter to work correctly, all segments must start at timestamp 0.
20175 All corresponding streams must have the same parameters in all segments; the
20176 filtering system will automatically select a common pixel format for video
20177 streams, and a common sample format, sample rate and channel layout for
20178 audio streams, but other settings, such as resolution, must be converted
20179 explicitly by the user.
20181 Different frame rates are acceptable but will result in variable frame rate
20182 at output; be sure to configure the output file to handle it.
20184 @subsection Examples
20188 Concatenate an opening, an episode and an ending, all in bilingual version
20189 (video in stream 0, audio in streams 1 and 2):
20191 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
20192 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
20193 concat=n=3:v=1:a=2 [v] [a1] [a2]' \
20194 -map '[v]' -map '[a1]' -map '[a2]' output.mkv
20198 Concatenate two parts, handling audio and video separately, using the
20199 (a)movie sources, and adjusting the resolution:
20201 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
20202 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
20203 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
20205 Note that a desync will happen at the stitch if the audio and video streams
20206 do not have exactly the same duration in the first file.
20210 @subsection Commands
20212 This filter supports the following commands:
20215 Close the current segment and step to the next one
20218 @section drawgraph, adrawgraph
20220 Draw a graph using input video or audio metadata.
20222 It accepts the following parameters:
20226 Set 1st frame metadata key from which metadata values will be used to draw a graph.
20229 Set 1st foreground color expression.
20232 Set 2nd frame metadata key from which metadata values will be used to draw a graph.
20235 Set 2nd foreground color expression.
20238 Set 3rd frame metadata key from which metadata values will be used to draw a graph.
20241 Set 3rd foreground color expression.
20244 Set 4th frame metadata key from which metadata values will be used to draw a graph.
20247 Set 4th foreground color expression.
20250 Set minimal value of metadata value.
20253 Set maximal value of metadata value.
20256 Set graph background color. Default is white.
20261 Available values for mode is:
20268 Default is @code{line}.
20273 Available values for slide is:
20276 Draw new frame when right border is reached.
20279 Replace old columns with new ones.
20282 Scroll from right to left.
20285 Scroll from left to right.
20288 Draw single picture.
20291 Default is @code{frame}.
20294 Set size of graph video. For the syntax of this option, check the
20295 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20296 The default value is @code{900x256}.
20298 The foreground color expressions can use the following variables:
20301 Minimal value of metadata value.
20304 Maximal value of metadata value.
20307 Current metadata key value.
20310 The color is defined as 0xAABBGGRR.
20313 Example using metadata from @ref{signalstats} filter:
20315 signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
20318 Example using metadata from @ref{ebur128} filter:
20320 ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
20326 EBU R128 scanner filter. This filter takes an audio stream as input and outputs
20327 it unchanged. By default, it logs a message at a frequency of 10Hz with the
20328 Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
20329 Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
20331 The filter also has a video output (see the @var{video} option) with a real
20332 time graph to observe the loudness evolution. The graphic contains the logged
20333 message mentioned above, so it is not printed anymore when this option is set,
20334 unless the verbose logging is set. The main graphing area contains the
20335 short-term loudness (3 seconds of analysis), and the gauge on the right is for
20336 the momentary loudness (400 milliseconds), but can optionally be configured
20337 to instead display short-term loudness (see @var{gauge}).
20339 The green area marks a +/- 1LU target range around the target loudness
20340 (-23LUFS by default, unless modified through @var{target}).
20342 More information about the Loudness Recommendation EBU R128 on
20343 @url{http://tech.ebu.ch/loudness}.
20345 The filter accepts the following options:
20350 Activate the video output. The audio stream is passed unchanged whether this
20351 option is set or no. The video stream will be the first output stream if
20352 activated. Default is @code{0}.
20355 Set the video size. This option is for video only. For the syntax of this
20357 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20358 Default and minimum resolution is @code{640x480}.
20361 Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
20362 @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
20363 other integer value between this range is allowed.
20366 Set metadata injection. If set to @code{1}, the audio input will be segmented
20367 into 100ms output frames, each of them containing various loudness information
20368 in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
20370 Default is @code{0}.
20373 Force the frame logging level.
20375 Available values are:
20378 information logging level
20380 verbose logging level
20383 By default, the logging level is set to @var{info}. If the @option{video} or
20384 the @option{metadata} options are set, it switches to @var{verbose}.
20389 Available modes can be cumulated (the option is a @code{flag} type). Possible
20393 Disable any peak mode (default).
20395 Enable sample-peak mode.
20397 Simple peak mode looking for the higher sample value. It logs a message
20398 for sample-peak (identified by @code{SPK}).
20400 Enable true-peak mode.
20402 If enabled, the peak lookup is done on an over-sampled version of the input
20403 stream for better peak accuracy. It logs a message for true-peak.
20404 (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
20405 This mode requires a build with @code{libswresample}.
20409 Treat mono input files as "dual mono". If a mono file is intended for playback
20410 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
20411 If set to @code{true}, this option will compensate for this effect.
20412 Multi-channel input files are not affected by this option.
20415 Set a specific pan law to be used for the measurement of dual mono files.
20416 This parameter is optional, and has a default value of -3.01dB.
20419 Set a specific target level (in LUFS) used as relative zero in the visualization.
20420 This parameter is optional and has a default value of -23LUFS as specified
20421 by EBU R128. However, material published online may prefer a level of -16LUFS
20422 (e.g. for use with podcasts or video platforms).
20425 Set the value displayed by the gauge. Valid values are @code{momentary} and s
20426 @code{shortterm}. By default the momentary value will be used, but in certain
20427 scenarios it may be more useful to observe the short term value instead (e.g.
20431 Sets the display scale for the loudness. Valid parameters are @code{absolute}
20432 (in LUFS) or @code{relative} (LU) relative to the target. This only affects the
20433 video output, not the summary or continuous log output.
20436 @subsection Examples
20440 Real-time graph using @command{ffplay}, with a EBU scale meter +18:
20442 ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
20446 Run an analysis with @command{ffmpeg}:
20448 ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
20452 @section interleave, ainterleave
20454 Temporally interleave frames from several inputs.
20456 @code{interleave} works with video inputs, @code{ainterleave} with audio.
20458 These filters read frames from several inputs and send the oldest
20459 queued frame to the output.
20461 Input streams must have well defined, monotonically increasing frame
20464 In order to submit one frame to output, these filters need to enqueue
20465 at least one frame for each input, so they cannot work in case one
20466 input is not yet terminated and will not receive incoming frames.
20468 For example consider the case when one input is a @code{select} filter
20469 which always drops input frames. The @code{interleave} filter will keep
20470 reading from that input, but it will never be able to send new frames
20471 to output until the input sends an end-of-stream signal.
20473 Also, depending on inputs synchronization, the filters will drop
20474 frames in case one input receives more frames than the other ones, and
20475 the queue is already filled.
20477 These filters accept the following options:
20481 Set the number of different inputs, it is 2 by default.
20484 @subsection Examples
20488 Interleave frames belonging to different streams using @command{ffmpeg}:
20490 ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
20494 Add flickering blur effect:
20496 select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
20500 @section metadata, ametadata
20502 Manipulate frame metadata.
20504 This filter accepts the following options:
20508 Set mode of operation of the filter.
20510 Can be one of the following:
20514 If both @code{value} and @code{key} is set, select frames
20515 which have such metadata. If only @code{key} is set, select
20516 every frame that has such key in metadata.
20519 Add new metadata @code{key} and @code{value}. If key is already available
20523 Modify value of already present key.
20526 If @code{value} is set, delete only keys that have such value.
20527 Otherwise, delete key. If @code{key} is not set, delete all metadata values in
20531 Print key and its value if metadata was found. If @code{key} is not set print all
20532 metadata values available in frame.
20536 Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}.
20539 Set metadata value which will be used. This option is mandatory for
20540 @code{modify} and @code{add} mode.
20543 Which function to use when comparing metadata value and @code{value}.
20545 Can be one of following:
20549 Values are interpreted as strings, returns true if metadata value is same as @code{value}.
20552 Values are interpreted as strings, returns true if metadata value starts with
20553 the @code{value} option string.
20556 Values are interpreted as floats, returns true if metadata value is less than @code{value}.
20559 Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
20562 Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
20565 Values are interpreted as floats, returns true if expression from option @code{expr}
20570 Set expression which is used when @code{function} is set to @code{expr}.
20571 The expression is evaluated through the eval API and can contain the following
20576 Float representation of @code{value} from metadata key.
20579 Float representation of @code{value} as supplied by user in @code{value} option.
20583 If specified in @code{print} mode, output is written to the named file. Instead of
20584 plain filename any writable url can be specified. Filename ``-'' is a shorthand
20585 for standard output. If @code{file} option is not set, output is written to the log
20586 with AV_LOG_INFO loglevel.
20590 @subsection Examples
20594 Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values
20597 signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
20600 Print silencedetect output to file @file{metadata.txt}.
20602 silencedetect,ametadata=mode=print:file=metadata.txt
20605 Direct all metadata to a pipe with file descriptor 4.
20607 metadata=mode=print:file='pipe\:4'
20611 @section perms, aperms
20613 Set read/write permissions for the output frames.
20615 These filters are mainly aimed at developers to test direct path in the
20616 following filter in the filtergraph.
20618 The filters accept the following options:
20622 Select the permissions mode.
20624 It accepts the following values:
20627 Do nothing. This is the default.
20629 Set all the output frames read-only.
20631 Set all the output frames directly writable.
20633 Make the frame read-only if writable, and writable if read-only.
20635 Set each output frame read-only or writable randomly.
20639 Set the seed for the @var{random} mode, must be an integer included between
20640 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
20641 @code{-1}, the filter will try to use a good random seed on a best effort
20645 Note: in case of auto-inserted filter between the permission filter and the
20646 following one, the permission might not be received as expected in that
20647 following filter. Inserting a @ref{format} or @ref{aformat} filter before the
20648 perms/aperms filter can avoid this problem.
20650 @section realtime, arealtime
20652 Slow down filtering to match real time approximately.
20654 These filters will pause the filtering for a variable amount of time to
20655 match the output rate with the input timestamps.
20656 They are similar to the @option{re} option to @code{ffmpeg}.
20658 They accept the following options:
20662 Time limit for the pauses. Any pause longer than that will be considered
20663 a timestamp discontinuity and reset the timer. Default is 2 seconds.
20667 @section select, aselect
20669 Select frames to pass in output.
20671 This filter accepts the following options:
20676 Set expression, which is evaluated for each input frame.
20678 If the expression is evaluated to zero, the frame is discarded.
20680 If the evaluation result is negative or NaN, the frame is sent to the
20681 first output; otherwise it is sent to the output with index
20682 @code{ceil(val)-1}, assuming that the input index starts from 0.
20684 For example a value of @code{1.2} corresponds to the output with index
20685 @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
20688 Set the number of outputs. The output to which to send the selected
20689 frame is based on the result of the evaluation. Default value is 1.
20692 The expression can contain the following constants:
20696 The (sequential) number of the filtered frame, starting from 0.
20699 The (sequential) number of the selected frame, starting from 0.
20701 @item prev_selected_n
20702 The sequential number of the last selected frame. It's NAN if undefined.
20705 The timebase of the input timestamps.
20708 The PTS (Presentation TimeStamp) of the filtered video frame,
20709 expressed in @var{TB} units. It's NAN if undefined.
20712 The PTS of the filtered video frame,
20713 expressed in seconds. It's NAN if undefined.
20716 The PTS of the previously filtered video frame. It's NAN if undefined.
20718 @item prev_selected_pts
20719 The PTS of the last previously filtered video frame. It's NAN if undefined.
20721 @item prev_selected_t
20722 The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined.
20725 The PTS of the first video frame in the video. It's NAN if undefined.
20728 The time of the first video frame in the video. It's NAN if undefined.
20730 @item pict_type @emph{(video only)}
20731 The type of the filtered frame. It can assume one of the following
20743 @item interlace_type @emph{(video only)}
20744 The frame interlace type. It can assume one of the following values:
20747 The frame is progressive (not interlaced).
20749 The frame is top-field-first.
20751 The frame is bottom-field-first.
20754 @item consumed_sample_n @emph{(audio only)}
20755 the number of selected samples before the current frame
20757 @item samples_n @emph{(audio only)}
20758 the number of samples in the current frame
20760 @item sample_rate @emph{(audio only)}
20761 the input sample rate
20764 This is 1 if the filtered frame is a key-frame, 0 otherwise.
20767 the position in the file of the filtered frame, -1 if the information
20768 is not available (e.g. for synthetic video)
20770 @item scene @emph{(video only)}
20771 value between 0 and 1 to indicate a new scene; a low value reflects a low
20772 probability for the current frame to introduce a new scene, while a higher
20773 value means the current frame is more likely to be one (see the example below)
20775 @item concatdec_select
20776 The concat demuxer can select only part of a concat input file by setting an
20777 inpoint and an outpoint, but the output packets may not be entirely contained
20778 in the selected interval. By using this variable, it is possible to skip frames
20779 generated by the concat demuxer which are not exactly contained in the selected
20782 This works by comparing the frame pts against the @var{lavf.concat.start_time}
20783 and the @var{lavf.concat.duration} packet metadata values which are also
20784 present in the decoded frames.
20786 The @var{concatdec_select} variable is -1 if the frame pts is at least
20787 start_time and either the duration metadata is missing or the frame pts is less
20788 than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
20791 That basically means that an input frame is selected if its pts is within the
20792 interval set by the concat demuxer.
20796 The default value of the select expression is "1".
20798 @subsection Examples
20802 Select all frames in input:
20807 The example above is the same as:
20819 Select only I-frames:
20821 select='eq(pict_type\,I)'
20825 Select one frame every 100:
20827 select='not(mod(n\,100))'
20831 Select only frames contained in the 10-20 time interval:
20833 select=between(t\,10\,20)
20837 Select only I-frames contained in the 10-20 time interval:
20839 select=between(t\,10\,20)*eq(pict_type\,I)
20843 Select frames with a minimum distance of 10 seconds:
20845 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
20849 Use aselect to select only audio frames with samples number > 100:
20851 aselect='gt(samples_n\,100)'
20855 Create a mosaic of the first scenes:
20857 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
20860 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
20864 Send even and odd frames to separate outputs, and compose them:
20866 select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
20870 Select useful frames from an ffconcat file which is using inpoints and
20871 outpoints but where the source files are not intra frame only.
20873 ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
20877 @section sendcmd, asendcmd
20879 Send commands to filters in the filtergraph.
20881 These filters read commands to be sent to other filters in the
20884 @code{sendcmd} must be inserted between two video filters,
20885 @code{asendcmd} must be inserted between two audio filters, but apart
20886 from that they act the same way.
20888 The specification of commands can be provided in the filter arguments
20889 with the @var{commands} option, or in a file specified by the
20890 @var{filename} option.
20892 These filters accept the following options:
20895 Set the commands to be read and sent to the other filters.
20897 Set the filename of the commands to be read and sent to the other
20901 @subsection Commands syntax
20903 A commands description consists of a sequence of interval
20904 specifications, comprising a list of commands to be executed when a
20905 particular event related to that interval occurs. The occurring event
20906 is typically the current frame time entering or leaving a given time
20909 An interval is specified by the following syntax:
20911 @var{START}[-@var{END}] @var{COMMANDS};
20914 The time interval is specified by the @var{START} and @var{END} times.
20915 @var{END} is optional and defaults to the maximum time.
20917 The current frame time is considered within the specified interval if
20918 it is included in the interval [@var{START}, @var{END}), that is when
20919 the time is greater or equal to @var{START} and is lesser than
20922 @var{COMMANDS} consists of a sequence of one or more command
20923 specifications, separated by ",", relating to that interval. The
20924 syntax of a command specification is given by:
20926 [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
20929 @var{FLAGS} is optional and specifies the type of events relating to
20930 the time interval which enable sending the specified command, and must
20931 be a non-null sequence of identifier flags separated by "+" or "|" and
20932 enclosed between "[" and "]".
20934 The following flags are recognized:
20937 The command is sent when the current frame timestamp enters the
20938 specified interval. In other words, the command is sent when the
20939 previous frame timestamp was not in the given interval, and the
20943 The command is sent when the current frame timestamp leaves the
20944 specified interval. In other words, the command is sent when the
20945 previous frame timestamp was in the given interval, and the
20949 If @var{FLAGS} is not specified, a default value of @code{[enter]} is
20952 @var{TARGET} specifies the target of the command, usually the name of
20953 the filter class or a specific filter instance name.
20955 @var{COMMAND} specifies the name of the command for the target filter.
20957 @var{ARG} is optional and specifies the optional list of argument for
20958 the given @var{COMMAND}.
20960 Between one interval specification and another, whitespaces, or
20961 sequences of characters starting with @code{#} until the end of line,
20962 are ignored and can be used to annotate comments.
20964 A simplified BNF description of the commands specification syntax
20967 @var{COMMAND_FLAG} ::= "enter" | "leave"
20968 @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
20969 @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
20970 @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
20971 @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
20972 @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
20975 @subsection Examples
20979 Specify audio tempo change at second 4:
20981 asendcmd=c='4.0 atempo tempo 1.5',atempo
20985 Target a specific filter instance:
20987 asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my
20991 Specify a list of drawtext and hue commands in a file.
20993 # show text in the interval 5-10
20994 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
20995 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
20997 # desaturate the image in the interval 15-20
20998 15.0-20.0 [enter] hue s 0,
20999 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
21001 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
21003 # apply an exponential saturation fade-out effect, starting from time 25
21004 25 [enter] hue s exp(25-t)
21007 A filtergraph allowing to read and process the above command list
21008 stored in a file @file{test.cmd}, can be specified with:
21010 sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
21015 @section setpts, asetpts
21017 Change the PTS (presentation timestamp) of the input frames.
21019 @code{setpts} works on video frames, @code{asetpts} on audio frames.
21021 This filter accepts the following options:
21026 The expression which is evaluated for each frame to construct its timestamp.
21030 The expression is evaluated through the eval API and can contain the following
21034 @item FRAME_RATE, FR
21035 frame rate, only defined for constant frame-rate video
21038 The presentation timestamp in input
21041 The count of the input frame for video or the number of consumed samples,
21042 not including the current frame for audio, starting from 0.
21044 @item NB_CONSUMED_SAMPLES
21045 The number of consumed samples, not including the current frame (only
21048 @item NB_SAMPLES, S
21049 The number of samples in the current frame (only audio)
21051 @item SAMPLE_RATE, SR
21052 The audio sample rate.
21055 The PTS of the first frame.
21058 the time in seconds of the first frame
21061 State whether the current frame is interlaced.
21064 the time in seconds of the current frame
21067 original position in the file of the frame, or undefined if undefined
21068 for the current frame
21071 The previous input PTS.
21074 previous input time in seconds
21077 The previous output PTS.
21080 previous output time in seconds
21083 The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
21087 The wallclock (RTC) time at the start of the movie in microseconds.
21090 The timebase of the input timestamps.
21094 @subsection Examples
21098 Start counting PTS from zero
21100 setpts=PTS-STARTPTS
21104 Apply fast motion effect:
21110 Apply slow motion effect:
21116 Set fixed rate of 25 frames per second:
21122 Set fixed rate 25 fps with some jitter:
21124 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
21128 Apply an offset of 10 seconds to the input PTS:
21134 Generate timestamps from a "live source" and rebase onto the current timebase:
21136 setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
21140 Generate timestamps by counting samples:
21149 Force color range for the output video frame.
21151 The @code{setrange} filter marks the color range property for the
21152 output frames. It does not change the input frame, but only sets the
21153 corresponding property, which affects how the frame is treated by
21156 The filter accepts the following options:
21161 Available values are:
21165 Keep the same color range property.
21167 @item unspecified, unknown
21168 Set the color range as unspecified.
21170 @item limited, tv, mpeg
21171 Set the color range as limited.
21173 @item full, pc, jpeg
21174 Set the color range as full.
21178 @section settb, asettb
21180 Set the timebase to use for the output frames timestamps.
21181 It is mainly useful for testing timebase configuration.
21183 It accepts the following parameters:
21188 The expression which is evaluated into the output timebase.
21192 The value for @option{tb} is an arithmetic expression representing a
21193 rational. The expression can contain the constants "AVTB" (the default
21194 timebase), "intb" (the input timebase) and "sr" (the sample rate,
21195 audio only). Default value is "intb".
21197 @subsection Examples
21201 Set the timebase to 1/25:
21207 Set the timebase to 1/10:
21213 Set the timebase to 1001/1000:
21219 Set the timebase to 2*intb:
21225 Set the default timebase value:
21232 Convert input audio to a video output representing frequency spectrum
21233 logarithmically using Brown-Puckette constant Q transform algorithm with
21234 direct frequency domain coefficient calculation (but the transform itself
21235 is not really constant Q, instead the Q factor is actually variable/clamped),
21236 with musical tone scale, from E0 to D#10.
21238 The filter accepts the following options:
21242 Specify the video size for the output. It must be even. For the syntax of this option,
21243 check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21244 Default value is @code{1920x1080}.
21247 Set the output frame rate. Default value is @code{25}.
21250 Set the bargraph height. It must be even. Default value is @code{-1} which
21251 computes the bargraph height automatically.
21254 Set the axis height. It must be even. Default value is @code{-1} which computes
21255 the axis height automatically.
21258 Set the sonogram height. It must be even. Default value is @code{-1} which
21259 computes the sonogram height automatically.
21262 Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
21263 instead. Default value is @code{1}.
21265 @item sono_v, volume
21266 Specify the sonogram volume expression. It can contain variables:
21269 the @var{bar_v} evaluated expression
21270 @item frequency, freq, f
21271 the frequency where it is evaluated
21272 @item timeclamp, tc
21273 the value of @var{timeclamp} option
21277 @item a_weighting(f)
21278 A-weighting of equal loudness
21279 @item b_weighting(f)
21280 B-weighting of equal loudness
21281 @item c_weighting(f)
21282 C-weighting of equal loudness.
21284 Default value is @code{16}.
21286 @item bar_v, volume2
21287 Specify the bargraph volume expression. It can contain variables:
21290 the @var{sono_v} evaluated expression
21291 @item frequency, freq, f
21292 the frequency where it is evaluated
21293 @item timeclamp, tc
21294 the value of @var{timeclamp} option
21298 @item a_weighting(f)
21299 A-weighting of equal loudness
21300 @item b_weighting(f)
21301 B-weighting of equal loudness
21302 @item c_weighting(f)
21303 C-weighting of equal loudness.
21305 Default value is @code{sono_v}.
21307 @item sono_g, gamma
21308 Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
21309 higher gamma makes the spectrum having more range. Default value is @code{3}.
21310 Acceptable range is @code{[1, 7]}.
21312 @item bar_g, gamma2
21313 Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
21317 Specify the bargraph transparency level. Lower value makes the bargraph sharper.
21318 Default value is @code{1}. Acceptable range is @code{[0, 1]}.
21320 @item timeclamp, tc
21321 Specify the transform timeclamp. At low frequency, there is trade-off between
21322 accuracy in time domain and frequency domain. If timeclamp is lower,
21323 event in time domain is represented more accurately (such as fast bass drum),
21324 otherwise event in frequency domain is represented more accurately
21325 (such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}.
21328 Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it
21329 limits future samples by applying asymmetric windowing in time domain, useful
21330 when low latency is required. Accepted range is @code{[0, 1]}.
21333 Specify the transform base frequency. Default value is @code{20.01523126408007475},
21334 which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
21337 Specify the transform end frequency. Default value is @code{20495.59681441799654},
21338 which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
21341 This option is deprecated and ignored.
21344 Specify the transform length in time domain. Use this option to control accuracy
21345 trade-off between time domain and frequency domain at every frequency sample.
21346 It can contain variables:
21348 @item frequency, freq, f
21349 the frequency where it is evaluated
21350 @item timeclamp, tc
21351 the value of @var{timeclamp} option.
21353 Default value is @code{384*tc/(384+tc*f)}.
21356 Specify the transform count for every video frame. Default value is @code{6}.
21357 Acceptable range is @code{[1, 30]}.
21360 Specify the transform count for every single pixel. Default value is @code{0},
21361 which makes it computed automatically. Acceptable range is @code{[0, 10]}.
21364 Specify font file for use with freetype to draw the axis. If not specified,
21365 use embedded font. Note that drawing with font file or embedded font is not
21366 implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
21370 Specify fontconfig pattern. This has lower priority than @var{fontfile}.
21371 The : in the pattern may be replaced by | to avoid unnecessary escaping.
21374 Specify font color expression. This is arithmetic expression that should return
21375 integer value 0xRRGGBB. It can contain variables:
21377 @item frequency, freq, f
21378 the frequency where it is evaluated
21379 @item timeclamp, tc
21380 the value of @var{timeclamp} option
21385 midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
21386 @item r(x), g(x), b(x)
21387 red, green, and blue value of intensity x.
21389 Default value is @code{st(0, (midi(f)-59.5)/12);
21390 st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
21391 r(1-ld(1)) + b(ld(1))}.
21394 Specify image file to draw the axis. This option override @var{fontfile} and
21395 @var{fontcolor} option.
21398 Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
21399 the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
21400 Default value is @code{1}.
21403 Set colorspace. The accepted values are:
21406 Unspecified (default)
21415 BT.470BG or BT.601-6 625
21418 SMPTE-170M or BT.601-6 525
21424 BT.2020 with non-constant luminance
21429 Set spectrogram color scheme. This is list of floating point values with format
21430 @code{left_r|left_g|left_b|right_r|right_g|right_b}.
21431 The default is @code{1|0.5|0|0|0.5|1}.
21435 @subsection Examples
21439 Playing audio while showing the spectrum:
21441 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
21445 Same as above, but with frame rate 30 fps:
21447 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
21451 Playing at 1280x720:
21453 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
21457 Disable sonogram display:
21463 A1 and its harmonics: A1, A2, (near)E3, A3:
21465 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),
21466 asplit[a][out1]; [a] showcqt [out0]'
21470 Same as above, but with more accuracy in frequency domain:
21472 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),
21473 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
21479 bar_v=10:sono_v=bar_v*a_weighting(f)
21483 Custom gamma, now spectrum is linear to the amplitude.
21489 Custom tlength equation:
21491 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)))'
21495 Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
21497 fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
21501 Custom font using fontconfig:
21503 font='Courier New,Monospace,mono|bold'
21507 Custom frequency range with custom axis using image file:
21509 axisfile=myaxis.png:basefreq=40:endfreq=10000
21515 Convert input audio to video output representing the audio power spectrum.
21516 Audio amplitude is on Y-axis while frequency is on X-axis.
21518 The filter accepts the following options:
21522 Specify size of video. For the syntax of this option, check the
21523 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21524 Default is @code{1024x512}.
21528 This set how each frequency bin will be represented.
21530 It accepts the following values:
21536 Default is @code{bar}.
21539 Set amplitude scale.
21541 It accepts the following values:
21555 Default is @code{log}.
21558 Set frequency scale.
21560 It accepts the following values:
21569 Reverse logarithmic scale.
21571 Default is @code{lin}.
21576 It accepts the following values:
21592 Default is @code{w2048}
21595 Set windowing function.
21597 It accepts the following values:
21620 Default is @code{hanning}.
21623 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
21624 which means optimal overlap for selected window function will be picked.
21627 Set time averaging. Setting this to 0 will display current maximal peaks.
21628 Default is @code{1}, which means time averaging is disabled.
21631 Specify list of colors separated by space or by '|' which will be used to
21632 draw channel frequencies. Unrecognized or missing colors will be replaced
21636 Set channel display mode.
21638 It accepts the following values:
21643 Default is @code{combined}.
21646 Set minimum amplitude used in @code{log} amplitude scaler.
21650 @anchor{showspectrum}
21651 @section showspectrum
21653 Convert input audio to a video output, representing the audio frequency
21656 The filter accepts the following options:
21660 Specify the video size for the output. For the syntax of this option, check the
21661 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21662 Default value is @code{640x512}.
21665 Specify how the spectrum should slide along the window.
21667 It accepts the following values:
21670 the samples start again on the left when they reach the right
21672 the samples scroll from right to left
21674 frames are only produced when the samples reach the right
21676 the samples scroll from left to right
21679 Default value is @code{replace}.
21682 Specify display mode.
21684 It accepts the following values:
21687 all channels are displayed in the same row
21689 all channels are displayed in separate rows
21692 Default value is @samp{combined}.
21695 Specify display color mode.
21697 It accepts the following values:
21700 each channel is displayed in a separate color
21702 each channel is displayed using the same color scheme
21704 each channel is displayed using the rainbow color scheme
21706 each channel is displayed using the moreland color scheme
21708 each channel is displayed using the nebulae color scheme
21710 each channel is displayed using the fire color scheme
21712 each channel is displayed using the fiery color scheme
21714 each channel is displayed using the fruit color scheme
21716 each channel is displayed using the cool color scheme
21718 each channel is displayed using the magma color scheme
21720 each channel is displayed using the green color scheme
21722 each channel is displayed using the viridis color scheme
21724 each channel is displayed using the plasma color scheme
21726 each channel is displayed using the cividis color scheme
21728 each channel is displayed using the terrain color scheme
21731 Default value is @samp{channel}.
21734 Specify scale used for calculating intensity color values.
21736 It accepts the following values:
21741 square root, default
21752 Default value is @samp{sqrt}.
21755 Set saturation modifier for displayed colors. Negative values provide
21756 alternative color scheme. @code{0} is no saturation at all.
21757 Saturation must be in [-10.0, 10.0] range.
21758 Default value is @code{1}.
21761 Set window function.
21763 It accepts the following values:
21788 Default value is @code{hann}.
21791 Set orientation of time vs frequency axis. Can be @code{vertical} or
21792 @code{horizontal}. Default is @code{vertical}.
21795 Set ratio of overlap window. Default value is @code{0}.
21796 When value is @code{1} overlap is set to recommended size for specific
21797 window function currently used.
21800 Set scale gain for calculating intensity color values.
21801 Default value is @code{1}.
21804 Set which data to display. Can be @code{magnitude}, default or @code{phase}.
21807 Set color rotation, must be in [-1.0, 1.0] range.
21808 Default value is @code{0}.
21811 Set start frequency from which to display spectrogram. Default is @code{0}.
21814 Set stop frequency to which to display spectrogram. Default is @code{0}.
21817 Set upper frame rate limit. Default is @code{auto}, unlimited.
21820 Draw time and frequency axes and legends. Default is disabled.
21823 The usage is very similar to the showwaves filter; see the examples in that
21826 @subsection Examples
21830 Large window with logarithmic color scaling:
21832 showspectrum=s=1280x480:scale=log
21836 Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
21838 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
21839 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
21843 @section showspectrumpic
21845 Convert input audio to a single video frame, representing the audio frequency
21848 The filter accepts the following options:
21852 Specify the video size for the output. For the syntax of this option, check the
21853 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21854 Default value is @code{4096x2048}.
21857 Specify display mode.
21859 It accepts the following values:
21862 all channels are displayed in the same row
21864 all channels are displayed in separate rows
21866 Default value is @samp{combined}.
21869 Specify display color mode.
21871 It accepts the following values:
21874 each channel is displayed in a separate color
21876 each channel is displayed using the same color scheme
21878 each channel is displayed using the rainbow color scheme
21880 each channel is displayed using the moreland color scheme
21882 each channel is displayed using the nebulae color scheme
21884 each channel is displayed using the fire color scheme
21886 each channel is displayed using the fiery color scheme
21888 each channel is displayed using the fruit color scheme
21890 each channel is displayed using the cool color scheme
21892 each channel is displayed using the magma color scheme
21894 each channel is displayed using the green color scheme
21896 each channel is displayed using the viridis color scheme
21898 each channel is displayed using the plasma color scheme
21900 each channel is displayed using the cividis color scheme
21902 each channel is displayed using the terrain color scheme
21904 Default value is @samp{intensity}.
21907 Specify scale used for calculating intensity color values.
21909 It accepts the following values:
21914 square root, default
21924 Default value is @samp{log}.
21927 Set saturation modifier for displayed colors. Negative values provide
21928 alternative color scheme. @code{0} is no saturation at all.
21929 Saturation must be in [-10.0, 10.0] range.
21930 Default value is @code{1}.
21933 Set window function.
21935 It accepts the following values:
21959 Default value is @code{hann}.
21962 Set orientation of time vs frequency axis. Can be @code{vertical} or
21963 @code{horizontal}. Default is @code{vertical}.
21966 Set scale gain for calculating intensity color values.
21967 Default value is @code{1}.
21970 Draw time and frequency axes and legends. Default is enabled.
21973 Set color rotation, must be in [-1.0, 1.0] range.
21974 Default value is @code{0}.
21977 Set start frequency from which to display spectrogram. Default is @code{0}.
21980 Set stop frequency to which to display spectrogram. Default is @code{0}.
21983 @subsection Examples
21987 Extract an audio spectrogram of a whole audio track
21988 in a 1024x1024 picture using @command{ffmpeg}:
21990 ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
21994 @section showvolume
21996 Convert input audio volume to a video output.
21998 The filter accepts the following options:
22005 Set border width, allowed range is [0, 5]. Default is 1.
22008 Set channel width, allowed range is [80, 8192]. Default is 400.
22011 Set channel height, allowed range is [1, 900]. Default is 20.
22014 Set fade, allowed range is [0, 1]. Default is 0.95.
22017 Set volume color expression.
22019 The expression can use the following variables:
22023 Current max volume of channel in dB.
22029 Current channel number, starting from 0.
22033 If set, displays channel names. Default is enabled.
22036 If set, displays volume values. Default is enabled.
22039 Set orientation, can be horizontal: @code{h} or vertical: @code{v},
22040 default is @code{h}.
22043 Set step size, allowed range is [0, 5]. Default is 0, which means
22047 Set background opacity, allowed range is [0, 1]. Default is 0.
22050 Set metering mode, can be peak: @code{p} or rms: @code{r},
22051 default is @code{p}.
22054 Set display scale, can be linear: @code{lin} or log: @code{log},
22055 default is @code{lin}.
22059 If set to > 0., display a line for the max level
22060 in the previous seconds.
22061 default is disabled: @code{0.}
22064 The color of the max line. Use when @code{dm} option is set to > 0.
22065 default is: @code{orange}
22070 Convert input audio to a video output, representing the samples waves.
22072 The filter accepts the following options:
22076 Specify the video size for the output. For the syntax of this option, check the
22077 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22078 Default value is @code{600x240}.
22083 Available values are:
22086 Draw a point for each sample.
22089 Draw a vertical line for each sample.
22092 Draw a point for each sample and a line between them.
22095 Draw a centered vertical line for each sample.
22098 Default value is @code{point}.
22101 Set the number of samples which are printed on the same column. A
22102 larger value will decrease the frame rate. Must be a positive
22103 integer. This option can be set only if the value for @var{rate}
22104 is not explicitly specified.
22107 Set the (approximate) output frame rate. This is done by setting the
22108 option @var{n}. Default value is "25".
22110 @item split_channels
22111 Set if channels should be drawn separately or overlap. Default value is 0.
22114 Set colors separated by '|' which are going to be used for drawing of each channel.
22117 Set amplitude scale.
22119 Available values are:
22137 Set the draw mode. This is mostly useful to set for high @var{n}.
22139 Available values are:
22142 Scale pixel values for each drawn sample.
22145 Draw every sample directly.
22148 Default value is @code{scale}.
22151 @subsection Examples
22155 Output the input file audio and the corresponding video representation
22158 amovie=a.mp3,asplit[out0],showwaves[out1]
22162 Create a synthetic signal and show it with showwaves, forcing a
22163 frame rate of 30 frames per second:
22165 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
22169 @section showwavespic
22171 Convert input audio to a single video frame, representing the samples waves.
22173 The filter accepts the following options:
22177 Specify the video size for the output. For the syntax of this option, check the
22178 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22179 Default value is @code{600x240}.
22181 @item split_channels
22182 Set if channels should be drawn separately or overlap. Default value is 0.
22185 Set colors separated by '|' which are going to be used for drawing of each channel.
22188 Set amplitude scale.
22190 Available values are:
22208 @subsection Examples
22212 Extract a channel split representation of the wave form of a whole audio track
22213 in a 1024x800 picture using @command{ffmpeg}:
22215 ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
22219 @section sidedata, asidedata
22221 Delete frame side data, or select frames based on it.
22223 This filter accepts the following options:
22227 Set mode of operation of the filter.
22229 Can be one of the following:
22233 Select every frame with side data of @code{type}.
22236 Delete side data of @code{type}. If @code{type} is not set, delete all side
22242 Set side data type used with all modes. Must be set for @code{select} mode. For
22243 the list of frame side data types, refer to the @code{AVFrameSideDataType} enum
22244 in @file{libavutil/frame.h}. For example, to choose
22245 @code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}.
22249 @section spectrumsynth
22251 Sythesize audio from 2 input video spectrums, first input stream represents
22252 magnitude across time and second represents phase across time.
22253 The filter will transform from frequency domain as displayed in videos back
22254 to time domain as presented in audio output.
22256 This filter is primarily created for reversing processed @ref{showspectrum}
22257 filter outputs, but can synthesize sound from other spectrograms too.
22258 But in such case results are going to be poor if the phase data is not
22259 available, because in such cases phase data need to be recreated, usually
22260 its just recreated from random noise.
22261 For best results use gray only output (@code{channel} color mode in
22262 @ref{showspectrum} filter) and @code{log} scale for magnitude video and
22263 @code{lin} scale for phase video. To produce phase, for 2nd video, use
22264 @code{data} option. Inputs videos should generally use @code{fullframe}
22265 slide mode as that saves resources needed for decoding video.
22267 The filter accepts the following options:
22271 Specify sample rate of output audio, the sample rate of audio from which
22272 spectrum was generated may differ.
22275 Set number of channels represented in input video spectrums.
22278 Set scale which was used when generating magnitude input spectrum.
22279 Can be @code{lin} or @code{log}. Default is @code{log}.
22282 Set slide which was used when generating inputs spectrums.
22283 Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
22284 Default is @code{fullframe}.
22287 Set window function used for resynthesis.
22290 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
22291 which means optimal overlap for selected window function will be picked.
22294 Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
22295 Default is @code{vertical}.
22298 @subsection Examples
22302 First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
22303 then resynthesize videos back to audio with spectrumsynth:
22305 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
22306 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
22307 ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
22311 @section split, asplit
22313 Split input into several identical outputs.
22315 @code{asplit} works with audio input, @code{split} with video.
22317 The filter accepts a single parameter which specifies the number of outputs. If
22318 unspecified, it defaults to 2.
22320 @subsection Examples
22324 Create two separate outputs from the same input:
22326 [in] split [out0][out1]
22330 To create 3 or more outputs, you need to specify the number of
22333 [in] asplit=3 [out0][out1][out2]
22337 Create two separate outputs from the same input, one cropped and
22340 [in] split [splitout1][splitout2];
22341 [splitout1] crop=100:100:0:0 [cropout];
22342 [splitout2] pad=200:200:100:100 [padout];
22346 Create 5 copies of the input audio with @command{ffmpeg}:
22348 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
22354 Receive commands sent through a libzmq client, and forward them to
22355 filters in the filtergraph.
22357 @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
22358 must be inserted between two video filters, @code{azmq} between two
22359 audio filters. Both are capable to send messages to any filter type.
22361 To enable these filters you need to install the libzmq library and
22362 headers and configure FFmpeg with @code{--enable-libzmq}.
22364 For more information about libzmq see:
22365 @url{http://www.zeromq.org/}
22367 The @code{zmq} and @code{azmq} filters work as a libzmq server, which
22368 receives messages sent through a network interface defined by the
22369 @option{bind_address} (or the abbreviation "@option{b}") option.
22370 Default value of this option is @file{tcp://localhost:5555}. You may
22371 want to alter this value to your needs, but do not forget to escape any
22372 ':' signs (see @ref{filtergraph escaping}).
22374 The received message must be in the form:
22376 @var{TARGET} @var{COMMAND} [@var{ARG}]
22379 @var{TARGET} specifies the target of the command, usually the name of
22380 the filter class or a specific filter instance name. The default
22381 filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>},
22382 but you can override this by using the @samp{filter_name@@id} syntax
22383 (see @ref{Filtergraph syntax}).
22385 @var{COMMAND} specifies the name of the command for the target filter.
22387 @var{ARG} is optional and specifies the optional argument list for the
22388 given @var{COMMAND}.
22390 Upon reception, the message is processed and the corresponding command
22391 is injected into the filtergraph. Depending on the result, the filter
22392 will send a reply to the client, adopting the format:
22394 @var{ERROR_CODE} @var{ERROR_REASON}
22398 @var{MESSAGE} is optional.
22400 @subsection Examples
22402 Look at @file{tools/zmqsend} for an example of a zmq client which can
22403 be used to send commands processed by these filters.
22405 Consider the following filtergraph generated by @command{ffplay}.
22406 In this example the last overlay filter has an instance name. All other
22407 filters will have default instance names.
22410 ffplay -dumpgraph 1 -f lavfi "
22411 color=s=100x100:c=red [l];
22412 color=s=100x100:c=blue [r];
22413 nullsrc=s=200x100, zmq [bg];
22414 [bg][l] overlay [bg+l];
22415 [bg+l][r] overlay@@my=x=100 "
22418 To change the color of the left side of the video, the following
22419 command can be used:
22421 echo Parsed_color_0 c yellow | tools/zmqsend
22424 To change the right side:
22426 echo Parsed_color_1 c pink | tools/zmqsend
22429 To change the position of the right side:
22431 echo overlay@@my x 150 | tools/zmqsend
22435 @c man end MULTIMEDIA FILTERS
22437 @chapter Multimedia Sources
22438 @c man begin MULTIMEDIA SOURCES
22440 Below is a description of the currently available multimedia sources.
22444 This is the same as @ref{movie} source, except it selects an audio
22450 Read audio and/or video stream(s) from a movie container.
22452 It accepts the following parameters:
22456 The name of the resource to read (not necessarily a file; it can also be a
22457 device or a stream accessed through some protocol).
22459 @item format_name, f
22460 Specifies the format assumed for the movie to read, and can be either
22461 the name of a container or an input device. If not specified, the
22462 format is guessed from @var{movie_name} or by probing.
22464 @item seek_point, sp
22465 Specifies the seek point in seconds. The frames will be output
22466 starting from this seek point. The parameter is evaluated with
22467 @code{av_strtod}, so the numerical value may be suffixed by an IS
22468 postfix. The default value is "0".
22471 Specifies the streams to read. Several streams can be specified,
22472 separated by "+". The source will then have as many outputs, in the
22473 same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers"
22474 section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify
22475 respectively the default (best suited) video and audio stream. Default
22476 is "dv", or "da" if the filter is called as "amovie".
22478 @item stream_index, si
22479 Specifies the index of the video stream to read. If the value is -1,
22480 the most suitable video stream will be automatically selected. The default
22481 value is "-1". Deprecated. If the filter is called "amovie", it will select
22482 audio instead of video.
22485 Specifies how many times to read the stream in sequence.
22486 If the value is 0, the stream will be looped infinitely.
22487 Default value is "1".
22489 Note that when the movie is looped the source timestamps are not
22490 changed, so it will generate non monotonically increasing timestamps.
22492 @item discontinuity
22493 Specifies the time difference between frames above which the point is
22494 considered a timestamp discontinuity which is removed by adjusting the later
22498 It allows overlaying a second video on top of the main input of
22499 a filtergraph, as shown in this graph:
22501 input -----------> deltapts0 --> overlay --> output
22504 movie --> scale--> deltapts1 -------+
22506 @subsection Examples
22510 Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
22511 on top of the input labelled "in":
22513 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
22514 [in] setpts=PTS-STARTPTS [main];
22515 [main][over] overlay=16:16 [out]
22519 Read from a video4linux2 device, and overlay it on top of the input
22522 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
22523 [in] setpts=PTS-STARTPTS [main];
22524 [main][over] overlay=16:16 [out]
22528 Read the first video stream and the audio stream with id 0x81 from
22529 dvd.vob; the video is connected to the pad named "video" and the audio is
22530 connected to the pad named "audio":
22532 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
22536 @subsection Commands
22538 Both movie and amovie support the following commands:
22541 Perform seek using "av_seek_frame".
22542 The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
22545 @var{stream_index}: If stream_index is -1, a default
22546 stream is selected, and @var{timestamp} is automatically converted
22547 from AV_TIME_BASE units to the stream specific time_base.
22549 @var{timestamp}: Timestamp in AVStream.time_base units
22550 or, if no stream is specified, in AV_TIME_BASE units.
22552 @var{flags}: Flags which select direction and seeking mode.
22556 Get movie duration in AV_TIME_BASE units.
22560 @c man end MULTIMEDIA SOURCES