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 Changing options at runtime with a command
318 Some options can be changed during the operation of the filter using
319 a command. These options are marked 'T' on the output of
320 @command{ffmpeg} @option{-h filter=<name of filter>}.
321 The name of the command is the name of the option and the argument is
325 @chapter Options for filters with several inputs (framesync)
326 @c man begin OPTIONS FOR FILTERS WITH SEVERAL INPUTS
328 Some filters with several inputs support a common set of options.
329 These options can only be set by name, not with the short notation.
333 The action to take when EOF is encountered on the secondary input; it accepts
334 one of the following values:
338 Repeat the last frame (the default).
342 Pass the main input through.
346 If set to 1, force the output to terminate when the shortest input
347 terminates. Default value is 0.
350 If set to 1, force the filter to extend the last frame of secondary streams
351 until the end of the primary stream. A value of 0 disables this behavior.
355 @c man end OPTIONS FOR FILTERS WITH SEVERAL INPUTS
357 @chapter Audio Filters
358 @c man begin AUDIO FILTERS
360 When you configure your FFmpeg build, you can disable any of the
361 existing filters using @code{--disable-filters}.
362 The configure output will show the audio filters included in your
365 Below is a description of the currently available audio filters.
369 A compressor is mainly used to reduce the dynamic range of a signal.
370 Especially modern music is mostly compressed at a high ratio to
371 improve the overall loudness. It's done to get the highest attention
372 of a listener, "fatten" the sound and bring more "power" to the track.
373 If a signal is compressed too much it may sound dull or "dead"
374 afterwards or it may start to "pump" (which could be a powerful effect
375 but can also destroy a track completely).
376 The right compression is the key to reach a professional sound and is
377 the high art of mixing and mastering. Because of its complex settings
378 it may take a long time to get the right feeling for this kind of effect.
380 Compression is done by detecting the volume above a chosen level
381 @code{threshold} and dividing it by the factor set with @code{ratio}.
382 So if you set the threshold to -12dB and your signal reaches -6dB a ratio
383 of 2:1 will result in a signal at -9dB. Because an exact manipulation of
384 the signal would cause distortion of the waveform the reduction can be
385 levelled over the time. This is done by setting "Attack" and "Release".
386 @code{attack} determines how long the signal has to rise above the threshold
387 before any reduction will occur and @code{release} sets the time the signal
388 has to fall below the threshold to reduce the reduction again. Shorter signals
389 than the chosen attack time will be left untouched.
390 The overall reduction of the signal can be made up afterwards with the
391 @code{makeup} setting. So compressing the peaks of a signal about 6dB and
392 raising the makeup to this level results in a signal twice as loud than the
393 source. To gain a softer entry in the compression the @code{knee} flattens the
394 hard edge at the threshold in the range of the chosen decibels.
396 The filter accepts the following options:
400 Set input gain. Default is 1. Range is between 0.015625 and 64.
403 Set mode of compressor operation. Can be @code{upward} or @code{downward}.
404 Default is @code{downward}.
407 If a signal of stream rises above this level it will affect the gain
409 By default it is 0.125. Range is between 0.00097563 and 1.
412 Set a ratio by which the signal is reduced. 1:2 means that if the level
413 rose 4dB above the threshold, it will be only 2dB above after the reduction.
414 Default is 2. Range is between 1 and 20.
417 Amount of milliseconds the signal has to rise above the threshold before gain
418 reduction starts. Default is 20. Range is between 0.01 and 2000.
421 Amount of milliseconds the signal has to fall below the threshold before
422 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
425 Set the amount by how much signal will be amplified after processing.
426 Default is 1. Range is from 1 to 64.
429 Curve the sharp knee around the threshold to enter gain reduction more softly.
430 Default is 2.82843. Range is between 1 and 8.
433 Choose if the @code{average} level between all channels of input stream
434 or the louder(@code{maximum}) channel of input stream affects the
435 reduction. Default is @code{average}.
438 Should the exact signal be taken in case of @code{peak} or an RMS one in case
439 of @code{rms}. Default is @code{rms} which is mostly smoother.
442 How much to use compressed signal in output. Default is 1.
443 Range is between 0 and 1.
448 This filter supports the all above options as @ref{commands}.
451 Simple audio dynamic range compression/expansion filter.
453 The filter accepts the following options:
457 Set contrast. Default is 33. Allowed range is between 0 and 100.
462 Copy the input audio source unchanged to the output. This is mainly useful for
467 Apply cross fade from one input audio stream to another input audio stream.
468 The cross fade is applied for specified duration near the end of first stream.
470 The filter accepts the following options:
474 Specify the number of samples for which the cross fade effect has to last.
475 At the end of the cross fade effect the first input audio will be completely
476 silent. Default is 44100.
479 Specify the duration of the cross fade effect. See
480 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
481 for the accepted syntax.
482 By default the duration is determined by @var{nb_samples}.
483 If set this option is used instead of @var{nb_samples}.
486 Should first stream end overlap with second stream start. Default is enabled.
489 Set curve for cross fade transition for first stream.
492 Set curve for cross fade transition for second stream.
494 For description of available curve types see @ref{afade} filter description.
501 Cross fade from one input to another:
503 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
507 Cross fade from one input to another but without overlapping:
509 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
514 Split audio stream into several bands.
516 This filter splits audio stream into two or more frequency ranges.
517 Summing all streams back will give flat output.
519 The filter accepts the following options:
523 Set split frequencies. Those must be positive and increasing.
526 Set filter order for each band split. This controls filter roll-off or steepness
527 of filter transfer function.
528 Available values are:
553 Default is @var{4th}.
556 Set input gain level. Allowed range is from 0 to 1. Default value is 1.
559 Set output gain for each band. Default value is 1 for all bands.
566 Split input audio stream into two bands (low and high) with split frequency of 1500 Hz,
567 each band will be in separate stream:
569 ffmpeg -i in.flac -filter_complex 'acrossover=split=1500[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav
573 Same as above, but with higher filter order:
575 ffmpeg -i in.flac -filter_complex 'acrossover=split=1500:order=8th[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav
579 Same as above, but also with additional middle band (frequencies between 1500 and 8000):
581 ffmpeg -i in.flac -filter_complex 'acrossover=split=1500 8000:order=8th[LOW][MID][HIGH]' -map '[LOW]' low.wav -map '[MID]' mid.wav -map '[HIGH]' high.wav
587 Reduce audio bit resolution.
589 This filter is bit crusher with enhanced functionality. A bit crusher
590 is used to audibly reduce number of bits an audio signal is sampled
591 with. This doesn't change the bit depth at all, it just produces the
592 effect. Material reduced in bit depth sounds more harsh and "digital".
593 This filter is able to even round to continuous values instead of discrete
595 Additionally it has a D/C offset which results in different crushing of
596 the lower and the upper half of the signal.
597 An Anti-Aliasing setting is able to produce "softer" crushing sounds.
599 Another feature of this filter is the logarithmic mode.
600 This setting switches from linear distances between bits to logarithmic ones.
601 The result is a much more "natural" sounding crusher which doesn't gate low
602 signals for example. The human ear has a logarithmic perception,
603 so this kind of crushing is much more pleasant.
604 Logarithmic crushing is also able to get anti-aliased.
606 The filter accepts the following options:
622 Can be linear: @code{lin} or logarithmic: @code{log}.
631 Set sample reduction.
634 Enable LFO. By default disabled.
645 Delay audio filtering until a given wallclock timestamp. See the @ref{cue}
649 Remove impulsive noise from input audio.
651 Samples detected as impulsive noise are replaced by interpolated samples using
652 autoregressive modelling.
656 Set window size, in milliseconds. Allowed range is from @code{10} to
657 @code{100}. Default value is @code{55} milliseconds.
658 This sets size of window which will be processed at once.
661 Set window overlap, in percentage of window size. Allowed range is from
662 @code{50} to @code{95}. Default value is @code{75} percent.
663 Setting this to a very high value increases impulsive noise removal but makes
664 whole process much slower.
667 Set autoregression order, in percentage of window size. Allowed range is from
668 @code{0} to @code{25}. Default value is @code{2} percent. This option also
669 controls quality of interpolated samples using neighbour good samples.
672 Set threshold value. Allowed range is from @code{1} to @code{100}.
673 Default value is @code{2}.
674 This controls the strength of impulsive noise which is going to be removed.
675 The lower value, the more samples will be detected as impulsive noise.
678 Set burst fusion, in percentage of window size. Allowed range is @code{0} to
679 @code{10}. Default value is @code{2}.
680 If any two samples detected as noise are spaced less than this value then any
681 sample between those two samples will be also detected as noise.
686 It accepts the following values:
689 Select overlap-add method. Even not interpolated samples are slightly
690 changed with this method.
693 Select overlap-save method. Not interpolated samples remain unchanged.
696 Default value is @code{a}.
700 Remove clipped samples from input audio.
702 Samples detected as clipped are replaced by interpolated samples using
703 autoregressive modelling.
707 Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}.
708 Default value is @code{55} milliseconds.
709 This sets size of window which will be processed at once.
712 Set window overlap, in percentage of window size. Allowed range is from @code{50}
713 to @code{95}. Default value is @code{75} percent.
716 Set autoregression order, in percentage of window size. Allowed range is from
717 @code{0} to @code{25}. Default value is @code{8} percent. This option also controls
718 quality of interpolated samples using neighbour good samples.
721 Set threshold value. Allowed range is from @code{1} to @code{100}.
722 Default value is @code{10}. Higher values make clip detection less aggressive.
725 Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}.
726 Default value is @code{1000}. Higher values make clip detection less aggressive.
731 It accepts the following values:
734 Select overlap-add method. Even not interpolated samples are slightly changed
738 Select overlap-save method. Not interpolated samples remain unchanged.
741 Default value is @code{a}.
746 Delay one or more audio channels.
748 Samples in delayed channel are filled with silence.
750 The filter accepts the following option:
754 Set list of delays in milliseconds for each channel separated by '|'.
755 Unused delays will be silently ignored. If number of given delays is
756 smaller than number of channels all remaining channels will not be delayed.
757 If you want to delay exact number of samples, append 'S' to number.
758 If you want instead to delay in seconds, append 's' to number.
761 Use last set delay for all remaining channels. By default is disabled.
762 This option if enabled changes how option @code{delays} is interpreted.
769 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
770 the second channel (and any other channels that may be present) unchanged.
776 Delay second channel by 500 samples, the third channel by 700 samples and leave
777 the first channel (and any other channels that may be present) unchanged.
783 Delay all channels by same number of samples:
785 adelay=delays=64S:all=1
790 Remedy denormals in audio by adding extremely low-level noise.
792 This filter shall be placed before any filter that can produce denormals.
794 A description of the accepted parameters follows.
798 Set level of added noise in dB. Default is @code{-351}.
799 Allowed range is from -451 to -90.
802 Set type of added noise.
815 Default is @code{dc}.
820 This filter supports the all above options as @ref{commands}.
822 @section aderivative, aintegral
824 Compute derivative/integral of audio stream.
826 Applying both filters one after another produces original audio.
830 Apply echoing to the input audio.
832 Echoes are reflected sound and can occur naturally amongst mountains
833 (and sometimes large buildings) when talking or shouting; digital echo
834 effects emulate this behaviour and are often used to help fill out the
835 sound of a single instrument or vocal. The time difference between the
836 original signal and the reflection is the @code{delay}, and the
837 loudness of the reflected signal is the @code{decay}.
838 Multiple echoes can have different delays and decays.
840 A description of the accepted parameters follows.
844 Set input gain of reflected signal. Default is @code{0.6}.
847 Set output gain of reflected signal. Default is @code{0.3}.
850 Set list of time intervals in milliseconds between original signal and reflections
851 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
852 Default is @code{1000}.
855 Set list of loudness of reflected signals separated by '|'.
856 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
857 Default is @code{0.5}.
864 Make it sound as if there are twice as many instruments as are actually playing:
866 aecho=0.8:0.88:60:0.4
870 If delay is very short, then it sounds like a (metallic) robot playing music:
876 A longer delay will sound like an open air concert in the mountains:
878 aecho=0.8:0.9:1000:0.3
882 Same as above but with one more mountain:
884 aecho=0.8:0.9:1000|1800:0.3|0.25
889 Audio emphasis filter creates or restores material directly taken from LPs or
890 emphased CDs with different filter curves. E.g. to store music on vinyl the
891 signal has to be altered by a filter first to even out the disadvantages of
892 this recording medium.
893 Once the material is played back the inverse filter has to be applied to
894 restore the distortion of the frequency response.
896 The filter accepts the following options:
906 Set filter mode. For restoring material use @code{reproduction} mode, otherwise
907 use @code{production} mode. Default is @code{reproduction} mode.
910 Set filter type. Selects medium. Can be one of the following:
922 select Compact Disc (CD).
928 select 50µs (FM-KF).
930 select 75µs (FM-KF).
936 This filter supports the all above options as @ref{commands}.
940 Modify an audio signal according to the specified expressions.
942 This filter accepts one or more expressions (one for each channel),
943 which are evaluated and used to modify a corresponding audio signal.
945 It accepts the following parameters:
949 Set the '|'-separated expressions list for each separate channel. If
950 the number of input channels is greater than the number of
951 expressions, the last specified expression is used for the remaining
954 @item channel_layout, c
955 Set output channel layout. If not specified, the channel layout is
956 specified by the number of expressions. If set to @samp{same}, it will
957 use by default the same input channel layout.
960 Each expression in @var{exprs} can contain the following constants and functions:
964 channel number of the current expression
967 number of the evaluated sample, starting from 0
973 time of the evaluated sample expressed in seconds
976 @item nb_out_channels
977 input and output number of channels
980 the value of input channel with number @var{CH}
983 Note: this filter is slow. For faster processing you should use a
992 aeval=val(ch)/2:c=same
996 Invert phase of the second channel:
1005 Apply fade-in/out effect to input audio.
1007 A description of the accepted parameters follows.
1011 Specify the effect type, can be either @code{in} for fade-in, or
1012 @code{out} for a fade-out effect. Default is @code{in}.
1014 @item start_sample, ss
1015 Specify the number of the start sample for starting to apply the fade
1016 effect. Default is 0.
1018 @item nb_samples, ns
1019 Specify the number of samples for which the fade effect has to last. At
1020 the end of the fade-in effect the output audio will have the same
1021 volume as the input audio, at the end of the fade-out transition
1022 the output audio will be silence. Default is 44100.
1024 @item start_time, st
1025 Specify the start time of the fade effect. Default is 0.
1026 The value must be specified as a time duration; see
1027 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1028 for the accepted syntax.
1029 If set this option is used instead of @var{start_sample}.
1032 Specify the duration of the fade effect. See
1033 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1034 for the accepted syntax.
1035 At the end of the fade-in effect the output audio will have the same
1036 volume as the input audio, at the end of the fade-out transition
1037 the output audio will be silence.
1038 By default the duration is determined by @var{nb_samples}.
1039 If set this option is used instead of @var{nb_samples}.
1042 Set curve for fade transition.
1044 It accepts the following values:
1047 select triangular, linear slope (default)
1049 select quarter of sine wave
1051 select half of sine wave
1053 select exponential sine wave
1057 select inverted parabola
1071 select inverted quarter of sine wave
1073 select inverted half of sine wave
1075 select double-exponential seat
1077 select double-exponential sigmoid
1079 select logistic sigmoid
1081 select sine cardinal function
1083 select inverted sine cardinal function
1089 @subsection Examples
1093 Fade in first 15 seconds of audio:
1095 afade=t=in:ss=0:d=15
1099 Fade out last 25 seconds of a 900 seconds audio:
1101 afade=t=out:st=875:d=25
1106 Denoise audio samples with FFT.
1108 A description of the accepted parameters follows.
1112 Set the noise reduction in dB, allowed range is 0.01 to 97.
1113 Default value is 12 dB.
1116 Set the noise floor in dB, allowed range is -80 to -20.
1117 Default value is -50 dB.
1122 It accepts the following values:
1131 Select shellac noise.
1134 Select custom noise, defined in @code{bn} option.
1136 Default value is white noise.
1140 Set custom band noise for every one of 15 bands.
1141 Bands are separated by ' ' or '|'.
1144 Set the residual floor in dB, allowed range is -80 to -20.
1145 Default value is -38 dB.
1148 Enable noise tracking. By default is disabled.
1149 With this enabled, noise floor is automatically adjusted.
1152 Enable residual tracking. By default is disabled.
1155 Set the output mode.
1157 It accepts the following values:
1160 Pass input unchanged.
1163 Pass noise filtered out.
1168 Default value is @var{o}.
1172 @subsection Commands
1174 This filter supports the following commands:
1176 @item sample_noise, sn
1177 Start or stop measuring noise profile.
1178 Syntax for the command is : "start" or "stop" string.
1179 After measuring noise profile is stopped it will be
1180 automatically applied in filtering.
1182 @item noise_reduction, nr
1183 Change noise reduction. Argument is single float number.
1184 Syntax for the command is : "@var{noise_reduction}"
1186 @item noise_floor, nf
1187 Change noise floor. Argument is single float number.
1188 Syntax for the command is : "@var{noise_floor}"
1190 @item output_mode, om
1191 Change output mode operation.
1192 Syntax for the command is : "i", "o" or "n" string.
1196 Apply arbitrary expressions to samples in frequency domain.
1200 Set frequency domain real expression for each separate channel separated
1201 by '|'. Default is "re".
1202 If the number of input channels is greater than the number of
1203 expressions, the last specified expression is used for the remaining
1207 Set frequency domain imaginary expression for each separate channel
1208 separated by '|'. Default is "im".
1210 Each expression in @var{real} and @var{imag} can contain the following
1211 constants and functions:
1218 current frequency bin number
1221 number of available bins
1224 channel number of the current expression
1233 current real part of frequency bin of current channel
1236 current imaginary part of frequency bin of current channel
1239 Return the value of real part of frequency bin at location (@var{bin},@var{channel})
1242 Return the value of imaginary part of frequency bin at location (@var{bin},@var{channel})
1246 Set window size. Allowed range is from 16 to 131072.
1247 Default is @code{4096}
1250 Set window function. Default is @code{hann}.
1253 Set window overlap. If set to 1, the recommended overlap for selected
1254 window function will be picked. Default is @code{0.75}.
1257 @subsection Examples
1261 Leave almost only low frequencies in audio:
1263 afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"
1267 Apply robotize effect:
1269 afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75"
1273 Apply whisper effect:
1275 afftfilt="real='hypot(re,im)*cos((random(0)*2-1)*2*3.14)':imag='hypot(re,im)*sin((random(1)*2-1)*2*3.14)':win_size=128:overlap=0.8"
1282 Apply an arbitrary Finite Impulse Response filter.
1284 This filter is designed for applying long FIR filters,
1285 up to 60 seconds long.
1287 It can be used as component for digital crossover filters,
1288 room equalization, cross talk cancellation, wavefield synthesis,
1289 auralization, ambiophonics, ambisonics and spatialization.
1291 This filter uses the streams higher than first one as FIR coefficients.
1292 If the non-first stream holds a single channel, it will be used
1293 for all input channels in the first stream, otherwise
1294 the number of channels in the non-first stream must be same as
1295 the number of channels in the first stream.
1297 It accepts the following parameters:
1301 Set dry gain. This sets input gain.
1304 Set wet gain. This sets final output gain.
1307 Set Impulse Response filter length. Default is 1, which means whole IR is processed.
1310 Enable applying gain measured from power of IR.
1312 Set which approach to use for auto gain measurement.
1316 Do not apply any gain.
1319 select peak gain, very conservative approach. This is default value.
1322 select DC gain, limited application.
1325 select gain to noise approach, this is most popular one.
1329 Set gain to be applied to IR coefficients before filtering.
1330 Allowed range is 0 to 1. This gain is applied after any gain applied with @var{gtype} option.
1333 Set format of IR stream. Can be @code{mono} or @code{input}.
1334 Default is @code{input}.
1337 Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds.
1338 Allowed range is 0.1 to 60 seconds.
1341 Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
1342 By default it is disabled.
1345 Set for which IR channel to display frequency response. By default is first channel
1346 displayed. This option is used only when @var{response} is enabled.
1349 Set video stream size. This option is used only when @var{response} is enabled.
1352 Set video stream frame rate. This option is used only when @var{response} is enabled.
1355 Set minimal partition size used for convolution. Default is @var{8192}.
1356 Allowed range is from @var{1} to @var{32768}.
1357 Lower values decreases latency at cost of higher CPU usage.
1360 Set maximal partition size used for convolution. Default is @var{8192}.
1361 Allowed range is from @var{8} to @var{32768}.
1362 Lower values may increase CPU usage.
1365 Set number of input impulse responses streams which will be switchable at runtime.
1366 Allowed range is from @var{1} to @var{32}. Default is @var{1}.
1369 Set IR stream which will be used for convolution, starting from @var{0}, should always be
1370 lower than supplied value by @code{nbirs} option. Default is @var{0}.
1371 This option can be changed at runtime via @ref{commands}.
1374 @subsection Examples
1378 Apply reverb to stream using mono IR file as second input, complete command using ffmpeg:
1380 ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
1387 Set output format constraints for the input audio. The framework will
1388 negotiate the most appropriate format to minimize conversions.
1390 It accepts the following parameters:
1393 @item sample_fmts, f
1394 A '|'-separated list of requested sample formats.
1396 @item sample_rates, r
1397 A '|'-separated list of requested sample rates.
1399 @item channel_layouts, cl
1400 A '|'-separated list of requested channel layouts.
1402 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1403 for the required syntax.
1406 If a parameter is omitted, all values are allowed.
1408 Force the output to either unsigned 8-bit or signed 16-bit stereo
1410 aformat=sample_fmts=u8|s16:channel_layouts=stereo
1414 Apply frequency shift to input audio samples.
1416 The filter accepts the following options:
1420 Specify frequency shift. Allowed range is -INT_MAX to INT_MAX.
1421 Default value is 0.0.
1424 @subsection Commands
1426 This filter supports the above option as @ref{commands}.
1430 A gate is mainly used to reduce lower parts of a signal. This kind of signal
1431 processing reduces disturbing noise between useful signals.
1433 Gating is done by detecting the volume below a chosen level @var{threshold}
1434 and dividing it by the factor set with @var{ratio}. The bottom of the noise
1435 floor is set via @var{range}. Because an exact manipulation of the signal
1436 would cause distortion of the waveform the reduction can be levelled over
1437 time. This is done by setting @var{attack} and @var{release}.
1439 @var{attack} determines how long the signal has to fall below the threshold
1440 before any reduction will occur and @var{release} sets the time the signal
1441 has to rise above the threshold to reduce the reduction again.
1442 Shorter signals than the chosen attack time will be left untouched.
1446 Set input level before filtering.
1447 Default is 1. Allowed range is from 0.015625 to 64.
1450 Set the mode of operation. Can be @code{upward} or @code{downward}.
1451 Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
1452 will be amplified, expanding dynamic range in upward direction.
1453 Otherwise, in case of @code{downward} lower parts of signal will be reduced.
1456 Set the level of gain reduction when the signal is below the threshold.
1457 Default is 0.06125. Allowed range is from 0 to 1.
1458 Setting this to 0 disables reduction and then filter behaves like expander.
1461 If a signal rises above this level the gain reduction is released.
1462 Default is 0.125. Allowed range is from 0 to 1.
1465 Set a ratio by which the signal is reduced.
1466 Default is 2. Allowed range is from 1 to 9000.
1469 Amount of milliseconds the signal has to rise above the threshold before gain
1471 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
1474 Amount of milliseconds the signal has to fall below the threshold before the
1475 reduction is increased again. Default is 250 milliseconds.
1476 Allowed range is from 0.01 to 9000.
1479 Set amount of amplification of signal after processing.
1480 Default is 1. Allowed range is from 1 to 64.
1483 Curve the sharp knee around the threshold to enter gain reduction more softly.
1484 Default is 2.828427125. Allowed range is from 1 to 8.
1487 Choose if exact signal should be taken for detection or an RMS like one.
1488 Default is @code{rms}. Can be @code{peak} or @code{rms}.
1491 Choose if the average level between all channels or the louder channel affects
1493 Default is @code{average}. Can be @code{average} or @code{maximum}.
1496 @subsection Commands
1498 This filter supports the all above options as @ref{commands}.
1502 Apply an arbitrary Infinite Impulse Response filter.
1504 It accepts the following parameters:
1508 Set B/numerator/zeros/reflection coefficients.
1511 Set A/denominator/poles/ladder coefficients.
1523 Set coefficients format.
1527 lattice-ladder function
1529 analog transfer function
1531 digital transfer function
1533 Z-plane zeros/poles, cartesian (default)
1535 Z-plane zeros/poles, polar radians
1537 Z-plane zeros/poles, polar degrees
1543 Set type of processing.
1555 Set filtering precision.
1559 double-precision floating-point (default)
1561 single-precision floating-point
1569 Normalize filter coefficients, by default is enabled.
1570 Enabling it will normalize magnitude response at DC to 0dB.
1573 How much to use filtered signal in output. Default is 1.
1574 Range is between 0 and 1.
1577 Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
1578 By default it is disabled.
1581 Set for which IR channel to display frequency response. By default is first channel
1582 displayed. This option is used only when @var{response} is enabled.
1585 Set video stream size. This option is used only when @var{response} is enabled.
1588 Coefficients in @code{tf} and @code{sf} format are separated by spaces and are in ascending
1591 Coefficients in @code{zp} format are separated by spaces and order of coefficients
1592 doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i}
1595 Different coefficients and gains can be provided for every channel, in such case
1596 use '|' to separate coefficients or gains. Last provided coefficients will be
1597 used for all remaining channels.
1599 @subsection Examples
1603 Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate:
1605 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
1609 Same as above but in @code{zp} format:
1611 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
1615 Apply 3-rd order analog normalized Butterworth low-pass filter, using analog transfer function format:
1617 aiir=z=1.3057 0 0 0:p=1.3057 2.3892 2.1860 1:f=sf:r=d
1623 The limiter prevents an input signal from rising over a desired threshold.
1624 This limiter uses lookahead technology to prevent your signal from distorting.
1625 It means that there is a small delay after the signal is processed. Keep in mind
1626 that the delay it produces is the attack time you set.
1628 The filter accepts the following options:
1632 Set input gain. Default is 1.
1635 Set output gain. Default is 1.
1638 Don't let signals above this level pass the limiter. Default is 1.
1641 The limiter will reach its attenuation level in this amount of time in
1642 milliseconds. Default is 5 milliseconds.
1645 Come back from limiting to attenuation 1.0 in this amount of milliseconds.
1646 Default is 50 milliseconds.
1649 When gain reduction is always needed ASC takes care of releasing to an
1650 average reduction level rather than reaching a reduction of 0 in the release
1654 Select how much the release time is affected by ASC, 0 means nearly no changes
1655 in release time while 1 produces higher release times.
1658 Auto level output signal. Default is enabled.
1659 This normalizes audio back to 0dB if enabled.
1662 Depending on picked setting it is recommended to upsample input 2x or 4x times
1663 with @ref{aresample} before applying this filter.
1667 Apply a two-pole all-pass filter with central frequency (in Hz)
1668 @var{frequency}, and filter-width @var{width}.
1669 An all-pass filter changes the audio's frequency to phase relationship
1670 without changing its frequency to amplitude relationship.
1672 The filter accepts the following options:
1676 Set frequency in Hz.
1679 Set method to specify band-width of filter.
1694 Specify the band-width of a filter in width_type units.
1697 How much to use filtered signal in output. Default is 1.
1698 Range is between 0 and 1.
1701 Specify which channels to filter, by default all available are filtered.
1704 Normalize biquad coefficients, by default is disabled.
1705 Enabling it will normalize magnitude response at DC to 0dB.
1708 Set the filter order, can be 1 or 2. Default is 2.
1711 Set transform type of IIR filter.
1720 @subsection Commands
1722 This filter supports the following commands:
1725 Change allpass frequency.
1726 Syntax for the command is : "@var{frequency}"
1729 Change allpass width_type.
1730 Syntax for the command is : "@var{width_type}"
1733 Change allpass width.
1734 Syntax for the command is : "@var{width}"
1738 Syntax for the command is : "@var{mix}"
1745 The filter accepts the following options:
1749 Set the number of loops. Setting this value to -1 will result in infinite loops.
1753 Set maximal number of samples. Default is 0.
1756 Set first sample of loop. Default is 0.
1762 Merge two or more audio streams into a single multi-channel stream.
1764 The filter accepts the following options:
1769 Set the number of inputs. Default is 2.
1773 If the channel layouts of the inputs are disjoint, and therefore compatible,
1774 the channel layout of the output will be set accordingly and the channels
1775 will be reordered as necessary. If the channel layouts of the inputs are not
1776 disjoint, the output will have all the channels of the first input then all
1777 the channels of the second input, in that order, and the channel layout of
1778 the output will be the default value corresponding to the total number of
1781 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
1782 is FC+BL+BR, then the output will be in 5.1, with the channels in the
1783 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
1784 first input, b1 is the first channel of the second input).
1786 On the other hand, if both input are in stereo, the output channels will be
1787 in the default order: a1, a2, b1, b2, and the channel layout will be
1788 arbitrarily set to 4.0, which may or may not be the expected value.
1790 All inputs must have the same sample rate, and format.
1792 If inputs do not have the same duration, the output will stop with the
1795 @subsection Examples
1799 Merge two mono files into a stereo stream:
1801 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
1805 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
1807 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
1813 Mixes multiple audio inputs into a single output.
1815 Note that this filter only supports float samples (the @var{amerge}
1816 and @var{pan} audio filters support many formats). If the @var{amix}
1817 input has integer samples then @ref{aresample} will be automatically
1818 inserted to perform the conversion to float samples.
1822 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
1824 will mix 3 input audio streams to a single output with the same duration as the
1825 first input and a dropout transition time of 3 seconds.
1827 It accepts the following parameters:
1831 The number of inputs. If unspecified, it defaults to 2.
1834 How to determine the end-of-stream.
1838 The duration of the longest input. (default)
1841 The duration of the shortest input.
1844 The duration of the first input.
1848 @item dropout_transition
1849 The transition time, in seconds, for volume renormalization when an input
1850 stream ends. The default value is 2 seconds.
1853 Specify weight of each input audio stream as sequence.
1854 Each weight is separated by space. By default all inputs have same weight.
1857 @subsection Commands
1859 This filter supports the following commands:
1862 Syntax is same as option with same name.
1867 Multiply first audio stream with second audio stream and store result
1868 in output audio stream. Multiplication is done by multiplying each
1869 sample from first stream with sample at same position from second stream.
1871 With this element-wise multiplication one can create amplitude fades and
1872 amplitude modulations.
1874 @section anequalizer
1876 High-order parametric multiband equalizer for each channel.
1878 It accepts the following parameters:
1882 This option string is in format:
1883 "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
1884 Each equalizer band is separated by '|'.
1888 Set channel number to which equalization will be applied.
1889 If input doesn't have that channel the entry is ignored.
1892 Set central frequency for band.
1893 If input doesn't have that frequency the entry is ignored.
1896 Set band width in Hertz.
1899 Set band gain in dB.
1902 Set filter type for band, optional, can be:
1906 Butterworth, this is default.
1917 With this option activated frequency response of anequalizer is displayed
1921 Set video stream size. Only useful if curves option is activated.
1924 Set max gain that will be displayed. Only useful if curves option is activated.
1925 Setting this to a reasonable value makes it possible to display gain which is derived from
1926 neighbour bands which are too close to each other and thus produce higher gain
1927 when both are activated.
1930 Set frequency scale used to draw frequency response in video output.
1931 Can be linear or logarithmic. Default is logarithmic.
1934 Set color for each channel curve which is going to be displayed in video stream.
1935 This is list of color names separated by space or by '|'.
1936 Unrecognised or missing colors will be replaced by white color.
1939 @subsection Examples
1943 Lower gain by 10 of central frequency 200Hz and width 100 Hz
1944 for first 2 channels using Chebyshev type 1 filter:
1946 anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
1950 @subsection Commands
1952 This filter supports the following commands:
1955 Alter existing filter parameters.
1956 Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
1958 @var{fN} is existing filter number, starting from 0, if no such filter is available
1960 @var{freq} set new frequency parameter.
1961 @var{width} set new width parameter in Hertz.
1962 @var{gain} set new gain parameter in dB.
1964 Full filter invocation with asendcmd may look like this:
1965 asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
1970 Reduce broadband noise in audio samples using Non-Local Means algorithm.
1972 Each sample is adjusted by looking for other samples with similar contexts. This
1973 context similarity is defined by comparing their surrounding patches of size
1974 @option{p}. Patches are searched in an area of @option{r} around the sample.
1976 The filter accepts the following options:
1980 Set denoising strength. Allowed range is from 0.00001 to 10. Default value is 0.00001.
1983 Set patch radius duration. Allowed range is from 1 to 100 milliseconds.
1984 Default value is 2 milliseconds.
1987 Set research radius duration. Allowed range is from 2 to 300 milliseconds.
1988 Default value is 6 milliseconds.
1991 Set the output mode.
1993 It accepts the following values:
1996 Pass input unchanged.
1999 Pass noise filtered out.
2004 Default value is @var{o}.
2008 Set smooth factor. Default value is @var{11}. Allowed range is from @var{1} to @var{15}.
2011 @subsection Commands
2013 This filter supports the all above options as @ref{commands}.
2016 Apply Normalized Least-Mean-Squares algorithm to the first audio stream using the second audio stream.
2018 This adaptive filter is used to mimic a desired filter by finding the filter coefficients that
2019 relate to producing the least mean square of the error signal (difference between the desired,
2020 2nd input audio stream and the actual signal, the 1st input audio stream).
2022 A description of the accepted options follows.
2035 Set the filter leakage.
2038 It accepts the following values:
2047 Pass filtered samples.
2050 Pass difference between desired and filtered samples.
2052 Default value is @var{o}.
2056 @subsection Examples
2060 One of many usages of this filter is noise reduction, input audio is filtered
2061 with same samples that are delayed by fixed amount, one such example for stereo audio is:
2063 asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o
2067 @subsection Commands
2069 This filter supports the same commands as options, excluding option @code{order}.
2073 Pass the audio source unchanged to the output.
2077 Pad the end of an audio stream with silence.
2079 This can be used together with @command{ffmpeg} @option{-shortest} to
2080 extend audio streams to the same length as the video stream.
2082 A description of the accepted options follows.
2086 Set silence packet size. Default value is 4096.
2089 Set the number of samples of silence to add to the end. After the
2090 value is reached, the stream is terminated. This option is mutually
2091 exclusive with @option{whole_len}.
2094 Set the minimum total number of samples in the output audio stream. If
2095 the value is longer than the input audio length, silence is added to
2096 the end, until the value is reached. This option is mutually exclusive
2097 with @option{pad_len}.
2100 Specify the duration of samples of silence to add. See
2101 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
2102 for the accepted syntax. Used only if set to non-zero value.
2105 Specify the minimum total duration in the output audio stream. See
2106 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
2107 for the accepted syntax. Used only if set to non-zero value. If the value is longer than
2108 the input audio length, silence is added to the end, until the value is reached.
2109 This option is mutually exclusive with @option{pad_dur}
2112 If neither the @option{pad_len} nor the @option{whole_len} nor @option{pad_dur}
2113 nor @option{whole_dur} option is set, the filter will add silence to the end of
2114 the input stream indefinitely.
2116 @subsection Examples
2120 Add 1024 samples of silence to the end of the input:
2126 Make sure the audio output will contain at least 10000 samples, pad
2127 the input with silence if required:
2129 apad=whole_len=10000
2133 Use @command{ffmpeg} to pad the audio input with silence, so that the
2134 video stream will always result the shortest and will be converted
2135 until the end in the output file when using the @option{shortest}
2138 ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
2143 Add a phasing effect to the input audio.
2145 A phaser filter creates series of peaks and troughs in the frequency spectrum.
2146 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
2148 A description of the accepted parameters follows.
2152 Set input gain. Default is 0.4.
2155 Set output gain. Default is 0.74
2158 Set delay in milliseconds. Default is 3.0.
2161 Set decay. Default is 0.4.
2164 Set modulation speed in Hz. Default is 0.5.
2167 Set modulation type. Default is triangular.
2169 It accepts the following values:
2176 @section aphaseshift
2177 Apply phase shift to input audio samples.
2179 The filter accepts the following options:
2183 Specify phase shift. Allowed range is from -1.0 to 1.0.
2184 Default value is 0.0.
2187 @subsection Commands
2189 This filter supports the above option as @ref{commands}.
2193 Audio pulsator is something between an autopanner and a tremolo.
2194 But it can produce funny stereo effects as well. Pulsator changes the volume
2195 of the left and right channel based on a LFO (low frequency oscillator) with
2196 different waveforms and shifted phases.
2197 This filter have the ability to define an offset between left and right
2198 channel. An offset of 0 means that both LFO shapes match each other.
2199 The left and right channel are altered equally - a conventional tremolo.
2200 An offset of 50% means that the shape of the right channel is exactly shifted
2201 in phase (or moved backwards about half of the frequency) - pulsator acts as
2202 an autopanner. At 1 both curves match again. Every setting in between moves the
2203 phase shift gapless between all stages and produces some "bypassing" sounds with
2204 sine and triangle waveforms. The more you set the offset near 1 (starting from
2205 the 0.5) the faster the signal passes from the left to the right speaker.
2207 The filter accepts the following options:
2211 Set input gain. By default it is 1. Range is [0.015625 - 64].
2214 Set output gain. By default it is 1. Range is [0.015625 - 64].
2217 Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
2218 sawup or sawdown. Default is sine.
2221 Set modulation. Define how much of original signal is affected by the LFO.
2224 Set left channel offset. Default is 0. Allowed range is [0 - 1].
2227 Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
2230 Set pulse width. Default is 1. Allowed range is [0 - 2].
2233 Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
2236 Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
2240 Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
2244 Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
2245 if timing is set to hz.
2251 Resample the input audio to the specified parameters, using the
2252 libswresample library. If none are specified then the filter will
2253 automatically convert between its input and output.
2255 This filter is also able to stretch/squeeze the audio data to make it match
2256 the timestamps or to inject silence / cut out audio to make it match the
2257 timestamps, do a combination of both or do neither.
2259 The filter accepts the syntax
2260 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
2261 expresses a sample rate and @var{resampler_options} is a list of
2262 @var{key}=@var{value} pairs, separated by ":". See the
2263 @ref{Resampler Options,,"Resampler Options" section in the
2264 ffmpeg-resampler(1) manual,ffmpeg-resampler}
2265 for the complete list of supported options.
2267 @subsection Examples
2271 Resample the input audio to 44100Hz:
2277 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
2278 samples per second compensation:
2280 aresample=async=1000
2286 Reverse an audio clip.
2288 Warning: This filter requires memory to buffer the entire clip, so trimming
2291 @subsection Examples
2295 Take the first 5 seconds of a clip, and reverse it.
2297 atrim=end=5,areverse
2303 Reduce noise from speech using Recurrent Neural Networks.
2305 This filter accepts the following options:
2309 Set train model file to load. This option is always required.
2312 Set how much to mix filtered samples into final output.
2313 Allowed range is from -1 to 1. Default value is 1.
2314 Negative values are special, they set how much to keep filtered noise
2315 in the final filter output. Set this option to -1 to hear actual
2316 noise removed from input signal.
2319 @section asetnsamples
2321 Set the number of samples per each output audio frame.
2323 The last output packet may contain a different number of samples, as
2324 the filter will flush all the remaining samples when the input audio
2327 The filter accepts the following options:
2331 @item nb_out_samples, n
2332 Set the number of frames per each output audio frame. The number is
2333 intended as the number of samples @emph{per each channel}.
2334 Default value is 1024.
2337 If set to 1, the filter will pad the last audio frame with zeroes, so
2338 that the last frame will contain the same number of samples as the
2339 previous ones. Default value is 1.
2342 For example, to set the number of per-frame samples to 1234 and
2343 disable padding for the last frame, use:
2345 asetnsamples=n=1234:p=0
2350 Set the sample rate without altering the PCM data.
2351 This will result in a change of speed and pitch.
2353 The filter accepts the following options:
2356 @item sample_rate, r
2357 Set the output sample rate. Default is 44100 Hz.
2362 Show a line containing various information for each input audio frame.
2363 The input audio is not modified.
2365 The shown line contains a sequence of key/value pairs of the form
2366 @var{key}:@var{value}.
2368 The following values are shown in the output:
2372 The (sequential) number of the input frame, starting from 0.
2375 The presentation timestamp of the input frame, in time base units; the time base
2376 depends on the filter input pad, and is usually 1/@var{sample_rate}.
2379 The presentation timestamp of the input frame in seconds.
2382 position of the frame in the input stream, -1 if this information in
2383 unavailable and/or meaningless (for example in case of synthetic audio)
2392 The sample rate for the audio frame.
2395 The number of samples (per channel) in the frame.
2398 The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
2399 audio, the data is treated as if all the planes were concatenated.
2401 @item plane_checksums
2402 A list of Adler-32 checksums for each data plane.
2406 Apply audio soft clipping.
2408 Soft clipping is a type of distortion effect where the amplitude of a signal is saturated
2409 along a smooth curve, rather than the abrupt shape of hard-clipping.
2411 This filter accepts the following options:
2415 Set type of soft-clipping.
2417 It accepts the following values:
2431 Set additional parameter which controls sigmoid function.
2434 Set oversampling factor.
2437 @subsection Commands
2439 This filter supports the all above options as @ref{commands}.
2442 Automatic Speech Recognition
2444 This filter uses PocketSphinx for speech recognition. To enable
2445 compilation of this filter, you need to configure FFmpeg with
2446 @code{--enable-pocketsphinx}.
2448 It accepts the following options:
2452 Set sampling rate of input audio. Defaults is @code{16000}.
2453 This need to match speech models, otherwise one will get poor results.
2456 Set dictionary containing acoustic model files.
2459 Set pronunciation dictionary.
2462 Set language model file.
2465 Set language model set.
2468 Set which language model to use.
2471 Set output for log messages.
2474 The filter exports recognized speech as the frame metadata @code{lavfi.asr.text}.
2479 Display time domain statistical information about the audio channels.
2480 Statistics are calculated and displayed for each audio channel and,
2481 where applicable, an overall figure is also given.
2483 It accepts the following option:
2486 Short window length in seconds, used for peak and trough RMS measurement.
2487 Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}.
2491 Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
2492 where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
2495 Available keys for each channel are:
2541 For example full key look like this @code{lavfi.astats.1.DC_offset} or
2542 this @code{lavfi.astats.Overall.Peak_count}.
2544 For description what each key means read below.
2547 Set number of frame after which stats are going to be recalculated.
2548 Default is disabled.
2550 @item measure_perchannel
2551 Select the entries which need to be measured per channel. The metadata keys can
2552 be used as flags, default is @option{all} which measures everything.
2553 @option{none} disables all per channel measurement.
2555 @item measure_overall
2556 Select the entries which need to be measured overall. The metadata keys can
2557 be used as flags, default is @option{all} which measures everything.
2558 @option{none} disables all overall measurement.
2562 A description of each shown parameter follows:
2566 Mean amplitude displacement from zero.
2569 Minimal sample level.
2572 Maximal sample level.
2574 @item Min difference
2575 Minimal difference between two consecutive samples.
2577 @item Max difference
2578 Maximal difference between two consecutive samples.
2580 @item Mean difference
2581 Mean difference between two consecutive samples.
2582 The average of each difference between two consecutive samples.
2584 @item RMS difference
2585 Root Mean Square difference between two consecutive samples.
2589 Standard peak and RMS level measured in dBFS.
2593 Peak and trough values for RMS level measured over a short window.
2596 Standard ratio of peak to RMS level (note: not in dB).
2599 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
2600 (i.e. either @var{Min level} or @var{Max level}).
2603 Number of occasions (not the number of samples) that the signal attained either
2604 @var{Min level} or @var{Max level}.
2606 @item Noise floor dB
2607 Minimum local peak measured in dBFS over a short window.
2609 @item Noise floor count
2610 Number of occasions (not the number of samples) that the signal attained
2614 Overall bit depth of audio. Number of bits used for each sample.
2617 Measured dynamic range of audio in dB.
2619 @item Zero crossings
2620 Number of points where the waveform crosses the zero level axis.
2622 @item Zero crossings rate
2623 Rate of Zero crossings and number of audio samples.
2627 Boost subwoofer frequencies.
2629 The filter accepts the following options:
2633 Set dry gain, how much of original signal is kept. Allowed range is from 0 to 1.
2634 Default value is 0.7.
2637 Set wet gain, how much of filtered signal is kept. Allowed range is from 0 to 1.
2638 Default value is 0.7.
2641 Set delay line decay gain value. Allowed range is from 0 to 1.
2642 Default value is 0.7.
2645 Set delay line feedback gain value. Allowed range is from 0 to 1.
2646 Default value is 0.9.
2649 Set cutoff frequency in Hertz. Allowed range is 50 to 900.
2650 Default value is 100.
2653 Set slope amount for cutoff frequency. Allowed range is 0.0001 to 1.
2654 Default value is 0.5.
2657 Set delay. Allowed range is from 1 to 100.
2658 Default value is 20.
2661 @subsection Commands
2663 This filter supports the all above options as @ref{commands}.
2666 Cut subwoofer frequencies.
2668 This filter allows to set custom, steeper
2669 roll off than highpass filter, and thus is able to more attenuate
2670 frequency content in stop-band.
2672 The filter accepts the following options:
2676 Set cutoff frequency in Hertz. Allowed range is 2 to 200.
2677 Default value is 20.
2680 Set filter order. Available values are from 3 to 20.
2681 Default value is 10.
2684 Set input gain level. Allowed range is from 0 to 1. Default value is 1.
2687 @subsection Commands
2689 This filter supports the all above options as @ref{commands}.
2692 Cut super frequencies.
2694 The filter accepts the following options:
2698 Set cutoff frequency in Hertz. Allowed range is 20000 to 192000.
2699 Default value is 20000.
2702 Set filter order. Available values are from 3 to 20.
2703 Default value is 10.
2706 Set input gain level. Allowed range is from 0 to 1. Default value is 1.
2709 @subsection Commands
2711 This filter supports the all above options as @ref{commands}.
2717 The filter accepts exactly one parameter, the audio tempo. If not
2718 specified then the filter will assume nominal 1.0 tempo. Tempo must
2719 be in the [0.5, 100.0] range.
2721 Note that tempo greater than 2 will skip some samples rather than
2722 blend them in. If for any reason this is a concern it is always
2723 possible to daisy-chain several instances of atempo to achieve the
2724 desired product tempo.
2726 @subsection Examples
2730 Slow down audio to 80% tempo:
2736 To speed up audio to 300% tempo:
2742 To speed up audio to 300% tempo by daisy-chaining two atempo instances:
2744 atempo=sqrt(3),atempo=sqrt(3)
2748 @subsection Commands
2750 This filter supports the following commands:
2753 Change filter tempo scale factor.
2754 Syntax for the command is : "@var{tempo}"
2759 Trim the input so that the output contains one continuous subpart of the input.
2761 It accepts the following parameters:
2764 Timestamp (in seconds) of the start of the section to keep. I.e. the audio
2765 sample with the timestamp @var{start} will be the first sample in the output.
2768 Specify time of the first audio sample that will be dropped, i.e. the
2769 audio sample immediately preceding the one with the timestamp @var{end} will be
2770 the last sample in the output.
2773 Same as @var{start}, except this option sets the start timestamp in samples
2777 Same as @var{end}, except this option sets the end timestamp in samples instead
2781 The maximum duration of the output in seconds.
2784 The number of the first sample that should be output.
2787 The number of the first sample that should be dropped.
2790 @option{start}, @option{end}, and @option{duration} are expressed as time
2791 duration specifications; see
2792 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
2794 Note that the first two sets of the start/end options and the @option{duration}
2795 option look at the frame timestamp, while the _sample options simply count the
2796 samples that pass through the filter. So start/end_pts and start/end_sample will
2797 give different results when the timestamps are wrong, inexact or do not start at
2798 zero. Also note that this filter does not modify the timestamps. If you wish
2799 to have the output timestamps start at zero, insert the asetpts filter after the
2802 If multiple start or end options are set, this filter tries to be greedy and
2803 keep all samples that match at least one of the specified constraints. To keep
2804 only the part that matches all the constraints at once, chain multiple atrim
2807 The defaults are such that all the input is kept. So it is possible to set e.g.
2808 just the end values to keep everything before the specified time.
2813 Drop everything except the second minute of input:
2815 ffmpeg -i INPUT -af atrim=60:120
2819 Keep only the first 1000 samples:
2821 ffmpeg -i INPUT -af atrim=end_sample=1000
2826 @section axcorrelate
2827 Calculate normalized cross-correlation between two input audio streams.
2829 Resulted samples are always between -1 and 1 inclusive.
2830 If result is 1 it means two input samples are highly correlated in that selected segment.
2831 Result 0 means they are not correlated at all.
2832 If result is -1 it means two input samples are out of phase, which means they cancel each
2835 The filter accepts the following options:
2839 Set size of segment over which cross-correlation is calculated.
2840 Default is 256. Allowed range is from 2 to 131072.
2843 Set algorithm for cross-correlation. Can be @code{slow} or @code{fast}.
2844 Default is @code{slow}. Fast algorithm assumes mean values over any given segment
2845 are always zero and thus need much less calculations to make.
2846 This is generally not true, but is valid for typical audio streams.
2849 @subsection Examples
2853 Calculate correlation between channels in stereo audio stream:
2855 ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav
2861 Apply a two-pole Butterworth band-pass filter with central
2862 frequency @var{frequency}, and (3dB-point) band-width width.
2863 The @var{csg} option selects a constant skirt gain (peak gain = Q)
2864 instead of the default: constant 0dB peak gain.
2865 The filter roll off at 6dB per octave (20dB per decade).
2867 The filter accepts the following options:
2871 Set the filter's central frequency. Default is @code{3000}.
2874 Constant skirt gain if set to 1. Defaults to 0.
2877 Set method to specify band-width of filter.
2892 Specify the band-width of a filter in width_type units.
2895 How much to use filtered signal in output. Default is 1.
2896 Range is between 0 and 1.
2899 Specify which channels to filter, by default all available are filtered.
2902 Normalize biquad coefficients, by default is disabled.
2903 Enabling it will normalize magnitude response at DC to 0dB.
2906 Set transform type of IIR filter.
2915 @subsection Commands
2917 This filter supports the following commands:
2920 Change bandpass frequency.
2921 Syntax for the command is : "@var{frequency}"
2924 Change bandpass width_type.
2925 Syntax for the command is : "@var{width_type}"
2928 Change bandpass width.
2929 Syntax for the command is : "@var{width}"
2932 Change bandpass mix.
2933 Syntax for the command is : "@var{mix}"
2938 Apply a two-pole Butterworth band-reject filter with central
2939 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
2940 The filter roll off at 6dB per octave (20dB per decade).
2942 The filter accepts the following options:
2946 Set the filter's central frequency. Default is @code{3000}.
2949 Set method to specify band-width of filter.
2964 Specify the band-width of a filter in width_type units.
2967 How much to use filtered signal in output. Default is 1.
2968 Range is between 0 and 1.
2971 Specify which channels to filter, by default all available are filtered.
2974 Normalize biquad coefficients, by default is disabled.
2975 Enabling it will normalize magnitude response at DC to 0dB.
2978 Set transform type of IIR filter.
2987 @subsection Commands
2989 This filter supports the following commands:
2992 Change bandreject frequency.
2993 Syntax for the command is : "@var{frequency}"
2996 Change bandreject width_type.
2997 Syntax for the command is : "@var{width_type}"
3000 Change bandreject width.
3001 Syntax for the command is : "@var{width}"
3004 Change bandreject mix.
3005 Syntax for the command is : "@var{mix}"
3008 @section bass, lowshelf
3010 Boost or cut the bass (lower) frequencies of the audio using a two-pole
3011 shelving filter with a response similar to that of a standard
3012 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
3014 The filter accepts the following options:
3018 Give the gain at 0 Hz. Its useful range is about -20
3019 (for a large cut) to +20 (for a large boost).
3020 Beware of clipping when using a positive gain.
3023 Set the filter's central frequency and so can be used
3024 to extend or reduce the frequency range to be boosted or cut.
3025 The default value is @code{100} Hz.
3028 Set method to specify band-width of filter.
3043 Determine how steep is the filter's shelf transition.
3046 How much to use filtered signal in output. Default is 1.
3047 Range is between 0 and 1.
3050 Specify which channels to filter, by default all available are filtered.
3053 Normalize biquad coefficients, by default is disabled.
3054 Enabling it will normalize magnitude response at DC to 0dB.
3057 Set transform type of IIR filter.
3066 @subsection Commands
3068 This filter supports the following commands:
3071 Change bass frequency.
3072 Syntax for the command is : "@var{frequency}"
3075 Change bass width_type.
3076 Syntax for the command is : "@var{width_type}"
3080 Syntax for the command is : "@var{width}"
3084 Syntax for the command is : "@var{gain}"
3088 Syntax for the command is : "@var{mix}"
3093 Apply a biquad IIR filter with the given coefficients.
3094 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
3095 are the numerator and denominator coefficients respectively.
3096 and @var{channels}, @var{c} specify which channels to filter, by default all
3097 available are filtered.
3099 @subsection Commands
3101 This filter supports the following commands:
3109 Change biquad parameter.
3110 Syntax for the command is : "@var{value}"
3113 How much to use filtered signal in output. Default is 1.
3114 Range is between 0 and 1.
3117 Specify which channels to filter, by default all available are filtered.
3120 Normalize biquad coefficients, by default is disabled.
3121 Enabling it will normalize magnitude response at DC to 0dB.
3124 Set transform type of IIR filter.
3134 Bauer stereo to binaural transformation, which improves headphone listening of
3135 stereo audio records.
3137 To enable compilation of this filter you need to configure FFmpeg with
3138 @code{--enable-libbs2b}.
3140 It accepts the following parameters:
3144 Pre-defined crossfeed level.
3148 Default level (fcut=700, feed=50).
3151 Chu Moy circuit (fcut=700, feed=60).
3154 Jan Meier circuit (fcut=650, feed=95).
3159 Cut frequency (in Hz).
3168 Remap input channels to new locations.
3170 It accepts the following parameters:
3173 Map channels from input to output. The argument is a '|'-separated list of
3174 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
3175 @var{in_channel} form. @var{in_channel} can be either the name of the input
3176 channel (e.g. FL for front left) or its index in the input channel layout.
3177 @var{out_channel} is the name of the output channel or its index in the output
3178 channel layout. If @var{out_channel} is not given then it is implicitly an
3179 index, starting with zero and increasing by one for each mapping.
3181 @item channel_layout
3182 The channel layout of the output stream.
3185 If no mapping is present, the filter will implicitly map input channels to
3186 output channels, preserving indices.
3188 @subsection Examples
3192 For example, assuming a 5.1+downmix input MOV file,
3194 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
3196 will create an output WAV file tagged as stereo from the downmix channels of
3200 To fix a 5.1 WAV improperly encoded in AAC's native channel order
3202 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
3206 @section channelsplit
3208 Split each channel from an input audio stream into a separate output stream.
3210 It accepts the following parameters:
3212 @item channel_layout
3213 The channel layout of the input stream. The default is "stereo".
3215 A channel layout describing the channels to be extracted as separate output streams
3216 or "all" to extract each input channel as a separate stream. The default is "all".
3218 Choosing channels not present in channel layout in the input will result in an error.
3221 @subsection Examples
3225 For example, assuming a stereo input MP3 file,
3227 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
3229 will create an output Matroska file with two audio streams, one containing only
3230 the left channel and the other the right channel.
3233 Split a 5.1 WAV file into per-channel files:
3235 ffmpeg -i in.wav -filter_complex
3236 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
3237 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
3238 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
3243 Extract only LFE from a 5.1 WAV file:
3245 ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
3246 -map '[LFE]' lfe.wav
3251 Add a chorus effect to the audio.
3253 Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
3255 Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
3256 constant, with chorus, it is varied using using sinusoidal or triangular modulation.
3257 The modulation depth defines the range the modulated delay is played before or after
3258 the delay. Hence the delayed sound will sound slower or faster, that is the delayed
3259 sound tuned around the original one, like in a chorus where some vocals are slightly
3262 It accepts the following parameters:
3265 Set input gain. Default is 0.4.
3268 Set output gain. Default is 0.4.
3271 Set delays. A typical delay is around 40ms to 60ms.
3283 @subsection Examples
3289 chorus=0.7:0.9:55:0.4:0.25:2
3295 chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
3299 Fuller sounding chorus with three delays:
3301 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
3306 Compress or expand the audio's dynamic range.
3308 It accepts the following parameters:
3314 A list of times in seconds for each channel over which the instantaneous level
3315 of the input signal is averaged to determine its volume. @var{attacks} refers to
3316 increase of volume and @var{decays} refers to decrease of volume. For most
3317 situations, the attack time (response to the audio getting louder) should be
3318 shorter than the decay time, because the human ear is more sensitive to sudden
3319 loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
3320 a typical value for decay is 0.8 seconds.
3321 If specified number of attacks & decays is lower than number of channels, the last
3322 set attack/decay will be used for all remaining channels.
3325 A list of points for the transfer function, specified in dB relative to the
3326 maximum possible signal amplitude. Each key points list must be defined using
3327 the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
3328 @code{x0/y0 x1/y1 x2/y2 ....}
3330 The input values must be in strictly increasing order but the transfer function
3331 does not have to be monotonically rising. The point @code{0/0} is assumed but
3332 may be overridden (by @code{0/out-dBn}). Typical values for the transfer
3333 function are @code{-70/-70|-60/-20|1/0}.
3336 Set the curve radius in dB for all joints. It defaults to 0.01.
3339 Set the additional gain in dB to be applied at all points on the transfer
3340 function. This allows for easy adjustment of the overall gain.
3344 Set an initial volume, in dB, to be assumed for each channel when filtering
3345 starts. This permits the user to supply a nominal level initially, so that, for
3346 example, a very large gain is not applied to initial signal levels before the
3347 companding has begun to operate. A typical value for audio which is initially
3348 quiet is -90 dB. It defaults to 0.
3351 Set a delay, in seconds. The input audio is analyzed immediately, but audio is
3352 delayed before being fed to the volume adjuster. Specifying a delay
3353 approximately equal to the attack/decay times allows the filter to effectively
3354 operate in predictive rather than reactive mode. It defaults to 0.
3358 @subsection Examples
3362 Make music with both quiet and loud passages suitable for listening to in a
3365 compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
3368 Another example for audio with whisper and explosion parts:
3370 compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
3374 A noise gate for when the noise is at a lower level than the signal:
3376 compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
3380 Here is another noise gate, this time for when the noise is at a higher level
3381 than the signal (making it, in some ways, similar to squelch):
3383 compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
3387 2:1 compression starting at -6dB:
3389 compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
3393 2:1 compression starting at -9dB:
3395 compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
3399 2:1 compression starting at -12dB:
3401 compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
3405 2:1 compression starting at -18dB:
3407 compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
3411 3:1 compression starting at -15dB:
3413 compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
3419 compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
3425 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
3429 Hard limiter at -6dB:
3431 compand=attacks=0:points=-80/-80|-6/-6|20/-6
3435 Hard limiter at -12dB:
3437 compand=attacks=0:points=-80/-80|-12/-12|20/-12
3441 Hard noise gate at -35 dB:
3443 compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
3449 compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
3453 @section compensationdelay
3455 Compensation Delay Line is a metric based delay to compensate differing
3456 positions of microphones or speakers.
3458 For example, you have recorded guitar with two microphones placed in
3459 different locations. Because the front of sound wave has fixed speed in
3460 normal conditions, the phasing of microphones can vary and depends on
3461 their location and interposition. The best sound mix can be achieved when
3462 these microphones are in phase (synchronized). Note that a distance of
3463 ~30 cm between microphones makes one microphone capture the signal in
3464 antiphase to the other microphone. That makes the final mix sound moody.
3465 This filter helps to solve phasing problems by adding different delays
3466 to each microphone track and make them synchronized.
3468 The best result can be reached when you take one track as base and
3469 synchronize other tracks one by one with it.
3470 Remember that synchronization/delay tolerance depends on sample rate, too.
3471 Higher sample rates will give more tolerance.
3473 The filter accepts the following parameters:
3477 Set millimeters distance. This is compensation distance for fine tuning.
3481 Set cm distance. This is compensation distance for tightening distance setup.
3485 Set meters distance. This is compensation distance for hard distance setup.
3489 Set dry amount. Amount of unprocessed (dry) signal.
3493 Set wet amount. Amount of processed (wet) signal.
3497 Set temperature in degrees Celsius. This is the temperature of the environment.
3502 Apply headphone crossfeed filter.
3504 Crossfeed is the process of blending the left and right channels of stereo
3506 It is mainly used to reduce extreme stereo separation of low frequencies.
3508 The intent is to produce more speaker like sound to the listener.
3510 The filter accepts the following options:
3514 Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1.
3515 This sets gain of low shelf filter for side part of stereo image.
3516 Default is -6dB. Max allowed is -30db when strength is set to 1.
3519 Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1.
3520 This sets cut off frequency of low shelf filter. Default is cut off near
3521 1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz.
3524 Set curve slope of low shelf filter. Default is 0.5.
3525 Allowed range is from 0.01 to 1.
3528 Set input gain. Default is 0.9.
3531 Set output gain. Default is 1.
3534 @subsection Commands
3536 This filter supports the all above options as @ref{commands}.
3538 @section crystalizer
3539 Simple algorithm to expand audio dynamic range.
3541 The filter accepts the following options:
3545 Sets the intensity of effect (default: 2.0). Must be in range between 0.0
3546 (unchanged sound) to 10.0 (maximum effect).
3549 Enable clipping. By default is enabled.
3552 @subsection Commands
3554 This filter supports the all above options as @ref{commands}.
3557 Apply a DC shift to the audio.
3559 This can be useful to remove a DC offset (caused perhaps by a hardware problem
3560 in the recording chain) from the audio. The effect of a DC offset is reduced
3561 headroom and hence volume. The @ref{astats} filter can be used to determine if
3562 a signal has a DC offset.
3566 Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
3570 Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
3571 used to prevent clipping.
3576 Apply de-essing to the audio samples.
3580 Set intensity for triggering de-essing. Allowed range is from 0 to 1.
3584 Set amount of ducking on treble part of sound. Allowed range is from 0 to 1.
3588 How much of original frequency content to keep when de-essing. Allowed range is from 0 to 1.
3592 Set the output mode.
3594 It accepts the following values:
3597 Pass input unchanged.
3600 Pass ess filtered out.
3605 Default value is @var{o}.
3611 Measure audio dynamic range.
3613 DR values of 14 and higher is found in very dynamic material. DR of 8 to 13
3614 is found in transition material. And anything less that 8 have very poor dynamics
3615 and is very compressed.
3617 The filter accepts the following options:
3621 Set window length in seconds used to split audio into segments of equal length.
3622 Default is 3 seconds.
3626 Dynamic Audio Normalizer.
3628 This filter applies a certain amount of gain to the input audio in order
3629 to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
3630 contrast to more "simple" normalization algorithms, the Dynamic Audio
3631 Normalizer *dynamically* re-adjusts the gain factor to the input audio.
3632 This allows for applying extra gain to the "quiet" sections of the audio
3633 while avoiding distortions or clipping the "loud" sections. In other words:
3634 The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
3635 sections, in the sense that the volume of each section is brought to the
3636 same target level. Note, however, that the Dynamic Audio Normalizer achieves
3637 this goal *without* applying "dynamic range compressing". It will retain 100%
3638 of the dynamic range *within* each section of the audio file.
3642 Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
3643 Default is 500 milliseconds.
3644 The Dynamic Audio Normalizer processes the input audio in small chunks,
3645 referred to as frames. This is required, because a peak magnitude has no
3646 meaning for just a single sample value. Instead, we need to determine the
3647 peak magnitude for a contiguous sequence of sample values. While a "standard"
3648 normalizer would simply use the peak magnitude of the complete file, the
3649 Dynamic Audio Normalizer determines the peak magnitude individually for each
3650 frame. The length of a frame is specified in milliseconds. By default, the
3651 Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
3652 been found to give good results with most files.
3653 Note that the exact frame length, in number of samples, will be determined
3654 automatically, based on the sampling rate of the individual input audio file.
3657 Set the Gaussian filter window size. In range from 3 to 301, must be odd
3658 number. Default is 31.
3659 Probably the most important parameter of the Dynamic Audio Normalizer is the
3660 @code{window size} of the Gaussian smoothing filter. The filter's window size
3661 is specified in frames, centered around the current frame. For the sake of
3662 simplicity, this must be an odd number. Consequently, the default value of 31
3663 takes into account the current frame, as well as the 15 preceding frames and
3664 the 15 subsequent frames. Using a larger window results in a stronger
3665 smoothing effect and thus in less gain variation, i.e. slower gain
3666 adaptation. Conversely, using a smaller window results in a weaker smoothing
3667 effect and thus in more gain variation, i.e. faster gain adaptation.
3668 In other words, the more you increase this value, the more the Dynamic Audio
3669 Normalizer will behave like a "traditional" normalization filter. On the
3670 contrary, the more you decrease this value, the more the Dynamic Audio
3671 Normalizer will behave like a dynamic range compressor.
3674 Set the target peak value. This specifies the highest permissible magnitude
3675 level for the normalized audio input. This filter will try to approach the
3676 target peak magnitude as closely as possible, but at the same time it also
3677 makes sure that the normalized signal will never exceed the peak magnitude.
3678 A frame's maximum local gain factor is imposed directly by the target peak
3679 magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
3680 It is not recommended to go above this value.
3683 Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
3684 The Dynamic Audio Normalizer determines the maximum possible (local) gain
3685 factor for each input frame, i.e. the maximum gain factor that does not
3686 result in clipping or distortion. The maximum gain factor is determined by
3687 the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
3688 additionally bounds the frame's maximum gain factor by a predetermined
3689 (global) maximum gain factor. This is done in order to avoid excessive gain
3690 factors in "silent" or almost silent frames. By default, the maximum gain
3691 factor is 10.0, For most inputs the default value should be sufficient and
3692 it usually is not recommended to increase this value. Though, for input
3693 with an extremely low overall volume level, it may be necessary to allow even
3694 higher gain factors. Note, however, that the Dynamic Audio Normalizer does
3695 not simply apply a "hard" threshold (i.e. cut off values above the threshold).
3696 Instead, a "sigmoid" threshold function will be applied. This way, the
3697 gain factors will smoothly approach the threshold value, but never exceed that
3701 Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
3702 By default, the Dynamic Audio Normalizer performs "peak" normalization.
3703 This means that the maximum local gain factor for each frame is defined
3704 (only) by the frame's highest magnitude sample. This way, the samples can
3705 be amplified as much as possible without exceeding the maximum signal
3706 level, i.e. without clipping. Optionally, however, the Dynamic Audio
3707 Normalizer can also take into account the frame's root mean square,
3708 abbreviated RMS. In electrical engineering, the RMS is commonly used to
3709 determine the power of a time-varying signal. It is therefore considered
3710 that the RMS is a better approximation of the "perceived loudness" than
3711 just looking at the signal's peak magnitude. Consequently, by adjusting all
3712 frames to a constant RMS value, a uniform "perceived loudness" can be
3713 established. If a target RMS value has been specified, a frame's local gain
3714 factor is defined as the factor that would result in exactly that RMS value.
3715 Note, however, that the maximum local gain factor is still restricted by the
3716 frame's highest magnitude sample, in order to prevent clipping.
3719 Enable channels coupling. By default is enabled.
3720 By default, the Dynamic Audio Normalizer will amplify all channels by the same
3721 amount. This means the same gain factor will be applied to all channels, i.e.
3722 the maximum possible gain factor is determined by the "loudest" channel.
3723 However, in some recordings, it may happen that the volume of the different
3724 channels is uneven, e.g. one channel may be "quieter" than the other one(s).
3725 In this case, this option can be used to disable the channel coupling. This way,
3726 the gain factor will be determined independently for each channel, depending
3727 only on the individual channel's highest magnitude sample. This allows for
3728 harmonizing the volume of the different channels.
3731 Enable DC bias correction. By default is disabled.
3732 An audio signal (in the time domain) is a sequence of sample values.
3733 In the Dynamic Audio Normalizer these sample values are represented in the
3734 -1.0 to 1.0 range, regardless of the original input format. Normally, the
3735 audio signal, or "waveform", should be centered around the zero point.
3736 That means if we calculate the mean value of all samples in a file, or in a
3737 single frame, then the result should be 0.0 or at least very close to that
3738 value. If, however, there is a significant deviation of the mean value from
3739 0.0, in either positive or negative direction, this is referred to as a
3740 DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
3741 Audio Normalizer provides optional DC bias correction.
3742 With DC bias correction enabled, the Dynamic Audio Normalizer will determine
3743 the mean value, or "DC correction" offset, of each input frame and subtract
3744 that value from all of the frame's sample values which ensures those samples
3745 are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
3746 boundaries, the DC correction offset values will be interpolated smoothly
3747 between neighbouring frames.
3749 @item altboundary, b
3750 Enable alternative boundary mode. By default is disabled.
3751 The Dynamic Audio Normalizer takes into account a certain neighbourhood
3752 around each frame. This includes the preceding frames as well as the
3753 subsequent frames. However, for the "boundary" frames, located at the very
3754 beginning and at the very end of the audio file, not all neighbouring
3755 frames are available. In particular, for the first few frames in the audio
3756 file, the preceding frames are not known. And, similarly, for the last few
3757 frames in the audio file, the subsequent frames are not known. Thus, the
3758 question arises which gain factors should be assumed for the missing frames
3759 in the "boundary" region. The Dynamic Audio Normalizer implements two modes
3760 to deal with this situation. The default boundary mode assumes a gain factor
3761 of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
3762 "fade out" at the beginning and at the end of the input, respectively.
3765 Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
3766 By default, the Dynamic Audio Normalizer does not apply "traditional"
3767 compression. This means that signal peaks will not be pruned and thus the
3768 full dynamic range will be retained within each local neighbourhood. However,
3769 in some cases it may be desirable to combine the Dynamic Audio Normalizer's
3770 normalization algorithm with a more "traditional" compression.
3771 For this purpose, the Dynamic Audio Normalizer provides an optional compression
3772 (thresholding) function. If (and only if) the compression feature is enabled,
3773 all input frames will be processed by a soft knee thresholding function prior
3774 to the actual normalization process. Put simply, the thresholding function is
3775 going to prune all samples whose magnitude exceeds a certain threshold value.
3776 However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
3777 value. Instead, the threshold value will be adjusted for each individual
3779 In general, smaller parameters result in stronger compression, and vice versa.
3780 Values below 3.0 are not recommended, because audible distortion may appear.
3783 Set the target threshold value. This specifies the lowest permissible
3784 magnitude level for the audio input which will be normalized.
3785 If input frame volume is above this value frame will be normalized.
3786 Otherwise frame may not be normalized at all. The default value is set
3787 to 0, which means all input frames will be normalized.
3788 This option is mostly useful if digital noise is not wanted to be amplified.
3791 @subsection Commands
3793 This filter supports the all above options as @ref{commands}.
3797 Make audio easier to listen to on headphones.
3799 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
3800 so that when listened to on headphones the stereo image is moved from
3801 inside your head (standard for headphones) to outside and in front of
3802 the listener (standard for speakers).
3808 Apply a two-pole peaking equalisation (EQ) filter. With this
3809 filter, the signal-level at and around a selected frequency can
3810 be increased or decreased, whilst (unlike bandpass and bandreject
3811 filters) that at all other frequencies is unchanged.
3813 In order to produce complex equalisation curves, this filter can
3814 be given several times, each with a different central frequency.
3816 The filter accepts the following options:
3820 Set the filter's central frequency in Hz.
3823 Set method to specify band-width of filter.
3838 Specify the band-width of a filter in width_type units.
3841 Set the required gain or attenuation in dB.
3842 Beware of clipping when using a positive gain.
3845 How much to use filtered signal in output. Default is 1.
3846 Range is between 0 and 1.
3849 Specify which channels to filter, by default all available are filtered.
3852 Normalize biquad coefficients, by default is disabled.
3853 Enabling it will normalize magnitude response at DC to 0dB.
3856 Set transform type of IIR filter.
3865 @subsection Examples
3868 Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
3870 equalizer=f=1000:t=h:width=200:g=-10
3874 Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
3876 equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
3880 @subsection Commands
3882 This filter supports the following commands:
3885 Change equalizer frequency.
3886 Syntax for the command is : "@var{frequency}"
3889 Change equalizer width_type.
3890 Syntax for the command is : "@var{width_type}"
3893 Change equalizer width.
3894 Syntax for the command is : "@var{width}"
3897 Change equalizer gain.
3898 Syntax for the command is : "@var{gain}"
3901 Change equalizer mix.
3902 Syntax for the command is : "@var{mix}"
3905 @section extrastereo
3907 Linearly increases the difference between left and right channels which
3908 adds some sort of "live" effect to playback.
3910 The filter accepts the following options:
3914 Sets the difference coefficient (default: 2.5). 0.0 means mono sound
3915 (average of both channels), with 1.0 sound will be unchanged, with
3916 -1.0 left and right channels will be swapped.
3919 Enable clipping. By default is enabled.
3922 @subsection Commands
3924 This filter supports the all above options as @ref{commands}.
3926 @section firequalizer
3927 Apply FIR Equalization using arbitrary frequency response.
3929 The filter accepts the following option:
3933 Set gain curve equation (in dB). The expression can contain variables:
3936 the evaluated frequency
3940 channel number, set to 0 when multichannels evaluation is disabled
3942 channel id, see libavutil/channel_layout.h, set to the first channel id when
3943 multichannels evaluation is disabled
3947 channel_layout, see libavutil/channel_layout.h
3952 @item gain_interpolate(f)
3953 interpolate gain on frequency f based on gain_entry
3954 @item cubic_interpolate(f)
3955 same as gain_interpolate, but smoother
3957 This option is also available as command. Default is @code{gain_interpolate(f)}.
3960 Set gain entry for gain_interpolate function. The expression can
3964 store gain entry at frequency f with value g
3966 This option is also available as command.
3969 Set filter delay in seconds. Higher value means more accurate.
3970 Default is @code{0.01}.
3973 Set filter accuracy in Hz. Lower value means more accurate.
3974 Default is @code{5}.
3977 Set window function. Acceptable values are:
3980 rectangular window, useful when gain curve is already smooth
3982 hann window (default)
3988 3-terms continuous 1st derivative nuttall window
3990 minimum 3-terms discontinuous nuttall window
3992 4-terms continuous 1st derivative nuttall window
3994 minimum 4-terms discontinuous nuttall (blackman-nuttall) window
3996 blackman-harris window
4002 If enabled, use fixed number of audio samples. This improves speed when
4003 filtering with large delay. Default is disabled.
4006 Enable multichannels evaluation on gain. Default is disabled.
4009 Enable zero phase mode by subtracting timestamp to compensate delay.
4010 Default is disabled.
4013 Set scale used by gain. Acceptable values are:
4016 linear frequency, linear gain
4018 linear frequency, logarithmic (in dB) gain (default)
4020 logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain
4022 logarithmic frequency, logarithmic gain
4026 Set file for dumping, suitable for gnuplot.
4029 Set scale for dumpfile. Acceptable values are same with scale option.
4033 Enable 2-channel convolution using complex FFT. This improves speed significantly.
4034 Default is disabled.
4037 Enable minimum phase impulse response. Default is disabled.
4040 @subsection Examples
4045 firequalizer=gain='if(lt(f,1000), 0, -INF)'
4048 lowpass at 1000 Hz with gain_entry:
4050 firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
4053 custom equalization:
4055 firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
4058 higher delay with zero phase to compensate delay:
4060 firequalizer=delay=0.1:fixed=on:zero_phase=on
4063 lowpass on left channel, highpass on right channel:
4065 firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
4066 :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
4071 Apply a flanging effect to the audio.
4073 The filter accepts the following options:
4077 Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
4080 Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2.
4083 Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
4087 Set percentage of delayed signal mixed with original. Range from 0 to 100.
4088 Default value is 71.
4091 Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
4094 Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
4095 Default value is @var{sinusoidal}.
4098 Set swept wave percentage-shift for multi channel. Range from 0 to 100.
4099 Default value is 25.
4102 Set delay-line interpolation, @var{linear} or @var{quadratic}.
4103 Default is @var{linear}.
4107 Apply Haas effect to audio.
4109 Note that this makes most sense to apply on mono signals.
4110 With this filter applied to mono signals it give some directionality and
4111 stretches its stereo image.
4113 The filter accepts the following options:
4117 Set input level. By default is @var{1}, or 0dB
4120 Set output level. By default is @var{1}, or 0dB.
4123 Set gain applied to side part of signal. By default is @var{1}.
4126 Set kind of middle source. Can be one of the following:
4136 Pick middle part signal of stereo image.
4139 Pick side part signal of stereo image.
4143 Change middle phase. By default is disabled.
4146 Set left channel delay. By default is @var{2.05} milliseconds.
4149 Set left channel balance. By default is @var{-1}.
4152 Set left channel gain. By default is @var{1}.
4155 Change left phase. By default is disabled.
4158 Set right channel delay. By defaults is @var{2.12} milliseconds.
4161 Set right channel balance. By default is @var{1}.
4164 Set right channel gain. By default is @var{1}.
4167 Change right phase. By default is enabled.
4172 Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
4173 embedded HDCD codes is expanded into a 20-bit PCM stream.
4175 The filter supports the Peak Extend and Low-level Gain Adjustment features
4176 of HDCD, and detects the Transient Filter flag.
4179 ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
4182 When using the filter with wav, note the default encoding for wav is 16-bit,
4183 so the resulting 20-bit stream will be truncated back to 16-bit. Use something
4184 like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
4186 ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
4187 ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
4190 The filter accepts the following options:
4193 @item disable_autoconvert
4194 Disable any automatic format conversion or resampling in the filter graph.
4196 @item process_stereo
4197 Process the stereo channels together. If target_gain does not match between
4198 channels, consider it invalid and use the last valid target_gain.
4201 Set the code detect timer period in ms.
4204 Always extend peaks above -3dBFS even if PE isn't signaled.
4207 Replace audio with a solid tone and adjust the amplitude to signal some
4208 specific aspect of the decoding process. The output file can be loaded in
4209 an audio editor alongside the original to aid analysis.
4211 @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
4218 Gain adjustment level at each sample
4220 Samples where peak extend occurs
4222 Samples where the code detect timer is active
4224 Samples where the target gain does not match between channels
4230 Apply head-related transfer functions (HRTFs) to create virtual
4231 loudspeakers around the user for binaural listening via headphones.
4232 The HRIRs are provided via additional streams, for each channel
4233 one stereo input stream is needed.
4235 The filter accepts the following options:
4239 Set mapping of input streams for convolution.
4240 The argument is a '|'-separated list of channel names in order as they
4241 are given as additional stream inputs for filter.
4242 This also specify number of input streams. Number of input streams
4243 must be not less than number of channels in first stream plus one.
4246 Set gain applied to audio. Value is in dB. Default is 0.
4249 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
4250 processing audio in time domain which is slow.
4251 @var{freq} is processing audio in frequency domain which is fast.
4252 Default is @var{freq}.
4255 Set custom gain for LFE channels. Value is in dB. Default is 0.
4258 Set size of frame in number of samples which will be processed at once.
4259 Default value is @var{1024}. Allowed range is from 1024 to 96000.
4262 Set format of hrir stream.
4263 Default value is @var{stereo}. Alternative value is @var{multich}.
4264 If value is set to @var{stereo}, number of additional streams should
4265 be greater or equal to number of input channels in first input stream.
4266 Also each additional stream should have stereo number of channels.
4267 If value is set to @var{multich}, number of additional streams should
4268 be exactly one. Also number of input channels of additional stream
4269 should be equal or greater than twice number of channels of first input
4273 @subsection Examples
4277 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
4278 each amovie filter use stereo file with IR coefficients as input.
4279 The files give coefficients for each position of virtual loudspeaker:
4282 -filter_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];[0:a][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR"
4287 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
4288 but now in @var{multich} @var{hrir} format.
4290 ffmpeg -i input.wav -filter_complex "amovie=minp.wav[hrirs];[0:a][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich"
4297 Apply a high-pass filter with 3dB point frequency.
4298 The filter can be either single-pole, or double-pole (the default).
4299 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
4301 The filter accepts the following options:
4305 Set frequency in Hz. Default is 3000.
4308 Set number of poles. Default is 2.
4311 Set method to specify band-width of filter.
4326 Specify the band-width of a filter in width_type units.
4327 Applies only to double-pole filter.
4328 The default is 0.707q and gives a Butterworth response.
4331 How much to use filtered signal in output. Default is 1.
4332 Range is between 0 and 1.
4335 Specify which channels to filter, by default all available are filtered.
4338 Normalize biquad coefficients, by default is disabled.
4339 Enabling it will normalize magnitude response at DC to 0dB.
4342 Set transform type of IIR filter.
4351 @subsection Commands
4353 This filter supports the following commands:
4356 Change highpass frequency.
4357 Syntax for the command is : "@var{frequency}"
4360 Change highpass width_type.
4361 Syntax for the command is : "@var{width_type}"
4364 Change highpass width.
4365 Syntax for the command is : "@var{width}"
4368 Change highpass mix.
4369 Syntax for the command is : "@var{mix}"
4374 Join multiple input streams into one multi-channel stream.
4376 It accepts the following parameters:
4380 The number of input streams. It defaults to 2.
4382 @item channel_layout
4383 The desired output channel layout. It defaults to stereo.
4386 Map channels from inputs to output. The argument is a '|'-separated list of
4387 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
4388 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
4389 can be either the name of the input channel (e.g. FL for front left) or its
4390 index in the specified input stream. @var{out_channel} is the name of the output
4394 The filter will attempt to guess the mappings when they are not specified
4395 explicitly. It does so by first trying to find an unused matching input channel
4396 and if that fails it picks the first unused input channel.
4398 Join 3 inputs (with properly set channel layouts):
4400 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
4403 Build a 5.1 output from 6 single-channel streams:
4405 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
4406 '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'
4412 Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
4414 To enable compilation of this filter you need to configure FFmpeg with
4415 @code{--enable-ladspa}.
4419 Specifies the name of LADSPA plugin library to load. If the environment
4420 variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
4421 each one of the directories specified by the colon separated list in
4422 @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
4423 this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
4424 @file{/usr/lib/ladspa/}.
4427 Specifies the plugin within the library. Some libraries contain only
4428 one plugin, but others contain many of them. If this is not set filter
4429 will list all available plugins within the specified library.
4432 Set the '|' separated list of controls which are zero or more floating point
4433 values that determine the behavior of the loaded plugin (for example delay,
4435 Controls need to be defined using the following syntax:
4436 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
4437 @var{valuei} is the value set on the @var{i}-th control.
4438 Alternatively they can be also defined using the following syntax:
4439 @var{value0}|@var{value1}|@var{value2}|..., where
4440 @var{valuei} is the value set on the @var{i}-th control.
4441 If @option{controls} is set to @code{help}, all available controls and
4442 their valid ranges are printed.
4444 @item sample_rate, s
4445 Specify the sample rate, default to 44100. Only used if plugin have
4449 Set the number of samples per channel per each output frame, default
4450 is 1024. Only used if plugin have zero inputs.
4453 Set the minimum duration of the sourced audio. See
4454 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4455 for the accepted syntax.
4456 Note that the resulting duration may be greater than the specified duration,
4457 as the generated audio is always cut at the end of a complete frame.
4458 If not specified, or the expressed duration is negative, the audio is
4459 supposed to be generated forever.
4460 Only used if plugin have zero inputs.
4463 Enable latency compensation, by default is disabled.
4464 Only used if plugin have inputs.
4467 @subsection Examples
4471 List all available plugins within amp (LADSPA example plugin) library:
4477 List all available controls and their valid ranges for @code{vcf_notch}
4478 plugin from @code{VCF} library:
4480 ladspa=f=vcf:p=vcf_notch:c=help
4484 Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
4487 ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
4491 Add reverberation to the audio using TAP-plugins
4492 (Tom's Audio Processing plugins):
4494 ladspa=file=tap_reverb:tap_reverb
4498 Generate white noise, with 0.2 amplitude:
4500 ladspa=file=cmt:noise_source_white:c=c0=.2
4504 Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
4505 @code{C* Audio Plugin Suite} (CAPS) library:
4507 ladspa=file=caps:Click:c=c1=20'
4511 Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
4513 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
4517 Increase volume by 20dB using fast lookahead limiter from Steve Harris
4518 @code{SWH Plugins} collection:
4520 ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
4524 Attenuate low frequencies using Multiband EQ from Steve Harris
4525 @code{SWH Plugins} collection:
4527 ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
4531 Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite}
4534 ladspa=caps:Narrower
4538 Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library:
4540 ladspa=caps:White:.2
4544 Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library:
4546 ladspa=caps:Fractal:c=c1=1
4550 Dynamic volume normalization using @code{VLevel} plugin:
4552 ladspa=vlevel-ladspa:vlevel_mono
4556 @subsection Commands
4558 This filter supports the following commands:
4561 Modify the @var{N}-th control value.
4563 If the specified value is not valid, it is ignored and prior one is kept.
4568 EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
4569 Support for both single pass (livestreams, files) and double pass (files) modes.
4570 This algorithm can target IL, LRA, and maximum true peak. In dynamic mode, to accurately
4571 detect true peaks, the audio stream will be upsampled to 192 kHz.
4572 Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate.
4574 The filter accepts the following options:
4578 Set integrated loudness target.
4579 Range is -70.0 - -5.0. Default value is -24.0.
4582 Set loudness range target.
4583 Range is 1.0 - 20.0. Default value is 7.0.
4586 Set maximum true peak.
4587 Range is -9.0 - +0.0. Default value is -2.0.
4589 @item measured_I, measured_i
4590 Measured IL of input file.
4591 Range is -99.0 - +0.0.
4593 @item measured_LRA, measured_lra
4594 Measured LRA of input file.
4595 Range is 0.0 - 99.0.
4597 @item measured_TP, measured_tp
4598 Measured true peak of input file.
4599 Range is -99.0 - +99.0.
4601 @item measured_thresh
4602 Measured threshold of input file.
4603 Range is -99.0 - +0.0.
4606 Set offset gain. Gain is applied before the true-peak limiter.
4607 Range is -99.0 - +99.0. Default is +0.0.
4610 Normalize by linearly scaling the source audio.
4611 @code{measured_I}, @code{measured_LRA}, @code{measured_TP},
4612 and @code{measured_thresh} must all be specified. Target LRA shouldn't
4613 be lower than source LRA and the change in integrated loudness shouldn't
4614 result in a true peak which exceeds the target TP. If any of these
4615 conditions aren't met, normalization mode will revert to @var{dynamic}.
4616 Options are @code{true} or @code{false}. Default is @code{true}.
4619 Treat mono input files as "dual-mono". If a mono file is intended for playback
4620 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
4621 If set to @code{true}, this option will compensate for this effect.
4622 Multi-channel input files are not affected by this option.
4623 Options are true or false. Default is false.
4626 Set print format for stats. Options are summary, json, or none.
4627 Default value is none.
4632 Apply a low-pass filter with 3dB point frequency.
4633 The filter can be either single-pole or double-pole (the default).
4634 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
4636 The filter accepts the following options:
4640 Set frequency in Hz. Default is 500.
4643 Set number of poles. Default is 2.
4646 Set method to specify band-width of filter.
4661 Specify the band-width of a filter in width_type units.
4662 Applies only to double-pole filter.
4663 The default is 0.707q and gives a Butterworth response.
4666 How much to use filtered signal in output. Default is 1.
4667 Range is between 0 and 1.
4670 Specify which channels to filter, by default all available are filtered.
4673 Normalize biquad coefficients, by default is disabled.
4674 Enabling it will normalize magnitude response at DC to 0dB.
4677 Set transform type of IIR filter.
4686 @subsection Examples
4689 Lowpass only LFE channel, it LFE is not present it does nothing:
4695 @subsection Commands
4697 This filter supports the following commands:
4700 Change lowpass frequency.
4701 Syntax for the command is : "@var{frequency}"
4704 Change lowpass width_type.
4705 Syntax for the command is : "@var{width_type}"
4708 Change lowpass width.
4709 Syntax for the command is : "@var{width}"
4713 Syntax for the command is : "@var{mix}"
4718 Load a LV2 (LADSPA Version 2) plugin.
4720 To enable compilation of this filter you need to configure FFmpeg with
4721 @code{--enable-lv2}.
4725 Specifies the plugin URI. You may need to escape ':'.
4728 Set the '|' separated list of controls which are zero or more floating point
4729 values that determine the behavior of the loaded plugin (for example delay,
4731 If @option{controls} is set to @code{help}, all available controls and
4732 their valid ranges are printed.
4734 @item sample_rate, s
4735 Specify the sample rate, default to 44100. Only used if plugin have
4739 Set the number of samples per channel per each output frame, default
4740 is 1024. Only used if plugin have zero inputs.
4743 Set the minimum duration of the sourced audio. See
4744 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4745 for the accepted syntax.
4746 Note that the resulting duration may be greater than the specified duration,
4747 as the generated audio is always cut at the end of a complete frame.
4748 If not specified, or the expressed duration is negative, the audio is
4749 supposed to be generated forever.
4750 Only used if plugin have zero inputs.
4753 @subsection Examples
4757 Apply bass enhancer plugin from Calf:
4759 lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
4763 Apply vinyl plugin from Calf:
4765 lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
4769 Apply bit crusher plugin from ArtyFX:
4771 lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
4776 Multiband Compress or expand the audio's dynamic range.
4778 The input audio is divided into bands using 4th order Linkwitz-Riley IIRs.
4779 This is akin to the crossover of a loudspeaker, and results in flat frequency
4780 response when absent compander action.
4782 It accepts the following parameters:
4786 This option syntax is:
4787 attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ...
4788 For explanation of each item refer to compand filter documentation.
4794 Mix channels with specific gain levels. The filter accepts the output
4795 channel layout followed by a set of channels definitions.
4797 This filter is also designed to efficiently remap the channels of an audio
4800 The filter accepts parameters of the form:
4801 "@var{l}|@var{outdef}|@var{outdef}|..."
4805 output channel layout or number of channels
4808 output channel specification, of the form:
4809 "@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]"
4812 output channel to define, either a channel name (FL, FR, etc.) or a channel
4813 number (c0, c1, etc.)
4816 multiplicative coefficient for the channel, 1 leaving the volume unchanged
4819 input channel to use, see out_name for details; it is not possible to mix
4820 named and numbered input channels
4823 If the `=' in a channel specification is replaced by `<', then the gains for
4824 that specification will be renormalized so that the total is 1, thus
4825 avoiding clipping noise.
4827 @subsection Mixing examples
4829 For example, if you want to down-mix from stereo to mono, but with a bigger
4830 factor for the left channel:
4832 pan=1c|c0=0.9*c0+0.1*c1
4835 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
4836 7-channels surround:
4838 pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
4841 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
4842 that should be preferred (see "-ac" option) unless you have very specific
4845 @subsection Remapping examples
4847 The channel remapping will be effective if, and only if:
4850 @item gain coefficients are zeroes or ones,
4851 @item only one input per channel output,
4854 If all these conditions are satisfied, the filter will notify the user ("Pure
4855 channel mapping detected"), and use an optimized and lossless method to do the
4858 For example, if you have a 5.1 source and want a stereo audio stream by
4859 dropping the extra channels:
4861 pan="stereo| c0=FL | c1=FR"
4864 Given the same source, you can also switch front left and front right channels
4865 and keep the input channel layout:
4867 pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
4870 If the input is a stereo audio stream, you can mute the front left channel (and
4871 still keep the stereo channel layout) with:
4876 Still with a stereo audio stream input, you can copy the right channel in both
4877 front left and right:
4879 pan="stereo| c0=FR | c1=FR"
4884 ReplayGain scanner filter. This filter takes an audio stream as an input and
4885 outputs it unchanged.
4886 At end of filtering it displays @code{track_gain} and @code{track_peak}.
4890 Convert the audio sample format, sample rate and channel layout. It is
4891 not meant to be used directly.
4894 Apply time-stretching and pitch-shifting with librubberband.
4896 To enable compilation of this filter, you need to configure FFmpeg with
4897 @code{--enable-librubberband}.
4899 The filter accepts the following options:
4903 Set tempo scale factor.
4906 Set pitch scale factor.
4909 Set transients detector.
4910 Possible values are:
4919 Possible values are:
4928 Possible values are:
4935 Set processing window size.
4936 Possible values are:
4945 Possible values are:
4952 Enable formant preservation when shift pitching.
4953 Possible values are:
4961 Possible values are:
4970 Possible values are:
4977 @subsection Commands
4979 This filter supports the following commands:
4982 Change filter tempo scale factor.
4983 Syntax for the command is : "@var{tempo}"
4986 Change filter pitch scale factor.
4987 Syntax for the command is : "@var{pitch}"
4990 @section sidechaincompress
4992 This filter acts like normal compressor but has the ability to compress
4993 detected signal using second input signal.
4994 It needs two input streams and returns one output stream.
4995 First input stream will be processed depending on second stream signal.
4996 The filtered signal then can be filtered with other filters in later stages of
4997 processing. See @ref{pan} and @ref{amerge} filter.
4999 The filter accepts the following options:
5003 Set input gain. Default is 1. Range is between 0.015625 and 64.
5006 Set mode of compressor operation. Can be @code{upward} or @code{downward}.
5007 Default is @code{downward}.
5010 If a signal of second stream raises above this level it will affect the gain
5011 reduction of first stream.
5012 By default is 0.125. Range is between 0.00097563 and 1.
5015 Set a ratio about which the signal is reduced. 1:2 means that if the level
5016 raised 4dB above the threshold, it will be only 2dB above after the reduction.
5017 Default is 2. Range is between 1 and 20.
5020 Amount of milliseconds the signal has to rise above the threshold before gain
5021 reduction starts. Default is 20. Range is between 0.01 and 2000.
5024 Amount of milliseconds the signal has to fall below the threshold before
5025 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
5028 Set the amount by how much signal will be amplified after processing.
5029 Default is 1. Range is from 1 to 64.
5032 Curve the sharp knee around the threshold to enter gain reduction more softly.
5033 Default is 2.82843. Range is between 1 and 8.
5036 Choose if the @code{average} level between all channels of side-chain stream
5037 or the louder(@code{maximum}) channel of side-chain stream affects the
5038 reduction. Default is @code{average}.
5041 Should the exact signal be taken in case of @code{peak} or an RMS one in case
5042 of @code{rms}. Default is @code{rms} which is mainly smoother.
5045 Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
5048 How much to use compressed signal in output. Default is 1.
5049 Range is between 0 and 1.
5052 @subsection Commands
5054 This filter supports the all above options as @ref{commands}.
5056 @subsection Examples
5060 Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
5061 depending on the signal of 2nd input and later compressed signal to be
5062 merged with 2nd input:
5064 ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
5068 @section sidechaingate
5070 A sidechain gate acts like a normal (wideband) gate but has the ability to
5071 filter the detected signal before sending it to the gain reduction stage.
5072 Normally a gate uses the full range signal to detect a level above the
5074 For example: If you cut all lower frequencies from your sidechain signal
5075 the gate will decrease the volume of your track only if not enough highs
5076 appear. With this technique you are able to reduce the resonation of a
5077 natural drum or remove "rumbling" of muted strokes from a heavily distorted
5079 It needs two input streams and returns one output stream.
5080 First input stream will be processed depending on second stream signal.
5082 The filter accepts the following options:
5086 Set input level before filtering.
5087 Default is 1. Allowed range is from 0.015625 to 64.
5090 Set the mode of operation. Can be @code{upward} or @code{downward}.
5091 Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
5092 will be amplified, expanding dynamic range in upward direction.
5093 Otherwise, in case of @code{downward} lower parts of signal will be reduced.
5096 Set the level of gain reduction when the signal is below the threshold.
5097 Default is 0.06125. Allowed range is from 0 to 1.
5098 Setting this to 0 disables reduction and then filter behaves like expander.
5101 If a signal rises above this level the gain reduction is released.
5102 Default is 0.125. Allowed range is from 0 to 1.
5105 Set a ratio about which the signal is reduced.
5106 Default is 2. Allowed range is from 1 to 9000.
5109 Amount of milliseconds the signal has to rise above the threshold before gain
5111 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
5114 Amount of milliseconds the signal has to fall below the threshold before the
5115 reduction is increased again. Default is 250 milliseconds.
5116 Allowed range is from 0.01 to 9000.
5119 Set amount of amplification of signal after processing.
5120 Default is 1. Allowed range is from 1 to 64.
5123 Curve the sharp knee around the threshold to enter gain reduction more softly.
5124 Default is 2.828427125. Allowed range is from 1 to 8.
5127 Choose if exact signal should be taken for detection or an RMS like one.
5128 Default is rms. Can be peak or rms.
5131 Choose if the average level between all channels or the louder channel affects
5133 Default is average. Can be average or maximum.
5136 Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
5139 @subsection Commands
5141 This filter supports the all above options as @ref{commands}.
5143 @section silencedetect
5145 Detect silence in an audio stream.
5147 This filter logs a message when it detects that the input audio volume is less
5148 or equal to a noise tolerance value for a duration greater or equal to the
5149 minimum detected noise duration.
5151 The printed times and duration are expressed in seconds. The
5152 @code{lavfi.silence_start} or @code{lavfi.silence_start.X} metadata key
5153 is set on the first frame whose timestamp equals or exceeds the detection
5154 duration and it contains the timestamp of the first frame of the silence.
5156 The @code{lavfi.silence_duration} or @code{lavfi.silence_duration.X}
5157 and @code{lavfi.silence_end} or @code{lavfi.silence_end.X} metadata
5158 keys are set on the first frame after the silence. If @option{mono} is
5159 enabled, and each channel is evaluated separately, the @code{.X}
5160 suffixed keys are used, and @code{X} corresponds to the channel number.
5162 The filter accepts the following options:
5166 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
5167 specified value) or amplitude ratio. Default is -60dB, or 0.001.
5170 Set silence duration until notification (default is 2 seconds). See
5171 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5172 for the accepted syntax.
5175 Process each channel separately, instead of combined. By default is disabled.
5178 @subsection Examples
5182 Detect 5 seconds of silence with -50dB noise tolerance:
5184 silencedetect=n=-50dB:d=5
5188 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
5189 tolerance in @file{silence.mp3}:
5191 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
5195 @section silenceremove
5197 Remove silence from the beginning, middle or end of the audio.
5199 The filter accepts the following options:
5203 This value is used to indicate if audio should be trimmed at beginning of
5204 the audio. A value of zero indicates no silence should be trimmed from the
5205 beginning. When specifying a non-zero value, it trims audio up until it
5206 finds non-silence. Normally, when trimming silence from beginning of audio
5207 the @var{start_periods} will be @code{1} but it can be increased to higher
5208 values to trim all audio up to specific count of non-silence periods.
5209 Default value is @code{0}.
5211 @item start_duration
5212 Specify the amount of time that non-silence must be detected before it stops
5213 trimming audio. By increasing the duration, bursts of noises can be treated
5214 as silence and trimmed off. Default value is @code{0}.
5216 @item start_threshold
5217 This indicates what sample value should be treated as silence. For digital
5218 audio, a value of @code{0} may be fine but for audio recorded from analog,
5219 you may wish to increase the value to account for background noise.
5220 Can be specified in dB (in case "dB" is appended to the specified value)
5221 or amplitude ratio. Default value is @code{0}.
5224 Specify max duration of silence at beginning that will be kept after
5225 trimming. Default is 0, which is equal to trimming all samples detected
5229 Specify mode of detection of silence end in start of multi-channel audio.
5230 Can be @var{any} or @var{all}. Default is @var{any}.
5231 With @var{any}, any sample that is detected as non-silence will cause
5232 stopped trimming of silence.
5233 With @var{all}, only if all channels are detected as non-silence will cause
5234 stopped trimming of silence.
5237 Set the count for trimming silence from the end of audio.
5238 To remove silence from the middle of a file, specify a @var{stop_periods}
5239 that is negative. This value is then treated as a positive value and is
5240 used to indicate the effect should restart processing as specified by
5241 @var{start_periods}, making it suitable for removing periods of silence
5242 in the middle of the audio.
5243 Default value is @code{0}.
5246 Specify a duration of silence that must exist before audio is not copied any
5247 more. By specifying a higher duration, silence that is wanted can be left in
5249 Default value is @code{0}.
5251 @item stop_threshold
5252 This is the same as @option{start_threshold} but for trimming silence from
5254 Can be specified in dB (in case "dB" is appended to the specified value)
5255 or amplitude ratio. Default value is @code{0}.
5258 Specify max duration of silence at end that will be kept after
5259 trimming. Default is 0, which is equal to trimming all samples detected
5263 Specify mode of detection of silence start in end of multi-channel audio.
5264 Can be @var{any} or @var{all}. Default is @var{any}.
5265 With @var{any}, any sample that is detected as non-silence will cause
5266 stopped trimming of silence.
5267 With @var{all}, only if all channels are detected as non-silence will cause
5268 stopped trimming of silence.
5271 Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
5272 and works better with digital silence which is exactly 0.
5273 Default value is @code{rms}.
5276 Set duration in number of seconds used to calculate size of window in number
5277 of samples for detecting silence.
5278 Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
5281 @subsection Examples
5285 The following example shows how this filter can be used to start a recording
5286 that does not contain the delay at the start which usually occurs between
5287 pressing the record button and the start of the performance:
5289 silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
5293 Trim all silence encountered from beginning to end where there is more than 1
5294 second of silence in audio:
5296 silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
5300 Trim all digital silence samples, using peak detection, from beginning to end
5301 where there is more than 0 samples of digital silence in audio and digital
5302 silence is detected in all channels at same positions in stream:
5304 silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0
5310 SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
5311 loudspeakers around the user for binaural listening via headphones (audio
5312 formats up to 9 channels supported).
5313 The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
5314 SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
5315 Austrian Academy of Sciences.
5317 To enable compilation of this filter you need to configure FFmpeg with
5318 @code{--enable-libmysofa}.
5320 The filter accepts the following options:
5324 Set the SOFA file used for rendering.
5327 Set gain applied to audio. Value is in dB. Default is 0.
5330 Set rotation of virtual loudspeakers in deg. Default is 0.
5333 Set elevation of virtual speakers in deg. Default is 0.
5336 Set distance in meters between loudspeakers and the listener with near-field
5337 HRTFs. Default is 1.
5340 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
5341 processing audio in time domain which is slow.
5342 @var{freq} is processing audio in frequency domain which is fast.
5343 Default is @var{freq}.
5346 Set custom positions of virtual loudspeakers. Syntax for this option is:
5347 <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
5348 Each virtual loudspeaker is described with short channel name following with
5349 azimuth and elevation in degrees.
5350 Each virtual loudspeaker description is separated by '|'.
5351 For example to override front left and front right channel positions use:
5352 'speakers=FL 45 15|FR 345 15'.
5353 Descriptions with unrecognised channel names are ignored.
5356 Set custom gain for LFE channels. Value is in dB. Default is 0.
5359 Set custom frame size in number of samples. Default is 1024.
5360 Allowed range is from 1024 to 96000. Only used if option @samp{type}
5361 is set to @var{freq}.
5364 Should all IRs be normalized upon importing SOFA file.
5365 By default is enabled.
5368 Should nearest IRs be interpolated with neighbor IRs if exact position
5369 does not match. By default is disabled.
5372 Minphase all IRs upon loading of SOFA file. By default is disabled.
5375 Set neighbor search angle step. Only used if option @var{interpolate} is enabled.
5378 Set neighbor search radius step. Only used if option @var{interpolate} is enabled.
5381 @subsection Examples
5385 Using ClubFritz6 sofa file:
5387 sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
5391 Using ClubFritz12 sofa file and bigger radius with small rotation:
5393 sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
5397 Similar as above but with custom speaker positions for front left, front right, back left and back right
5398 and also with custom gain:
5400 "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
5407 This filter expands or compresses each half-cycle of audio samples
5408 (local set of samples all above or all below zero and between two nearest zero crossings) depending
5409 on threshold value, so audio reaches target peak value under conditions controlled by below options.
5411 The filter accepts the following options:
5415 Set the expansion target peak value. This specifies the highest allowed absolute amplitude
5416 level for the normalized audio input. Default value is 0.95. Allowed range is from 0.0 to 1.0.
5419 Set the maximum expansion factor. Allowed range is from 1.0 to 50.0. Default value is 2.0.
5420 This option controls maximum local half-cycle of samples expansion. The maximum expansion
5421 would be such that local peak value reaches target peak value but never to surpass it and that
5422 ratio between new and previous peak value does not surpass this option value.
5424 @item compression, c
5425 Set the maximum compression factor. Allowed range is from 1.0 to 50.0. Default value is 2.0.
5426 This option controls maximum local half-cycle of samples compression. This option is used
5427 only if @option{threshold} option is set to value greater than 0.0, then in such cases
5428 when local peak is lower or same as value set by @option{threshold} all samples belonging to
5429 that peak's half-cycle will be compressed by current compression factor.
5432 Set the threshold value. Default value is 0.0. Allowed range is from 0.0 to 1.0.
5433 This option specifies which half-cycles of samples will be compressed and which will be expanded.
5434 Any half-cycle samples with their local peak value below or same as this option value will be
5435 compressed by current compression factor, otherwise, if greater than threshold value they will be
5436 expanded with expansion factor so that it could reach peak target value but never surpass it.
5439 Set the expansion raising amount per each half-cycle of samples. Default value is 0.001.
5440 Allowed range is from 0.0 to 1.0. This controls how fast expansion factor is raised per
5441 each new half-cycle until it reaches @option{expansion} value.
5442 Setting this options too high may lead to distortions.
5445 Set the compression raising amount per each half-cycle of samples. Default value is 0.001.
5446 Allowed range is from 0.0 to 1.0. This controls how fast compression factor is raised per
5447 each new half-cycle until it reaches @option{compression} value.
5450 Specify which channels to filter, by default all available channels are filtered.
5453 Enable inverted filtering, by default is disabled. This inverts interpretation of @option{threshold}
5454 option. When enabled any half-cycle of samples with their local peak value below or same as
5455 @option{threshold} option will be expanded otherwise it will be compressed.
5458 Link channels when calculating gain applied to each filtered channel sample, by default is disabled.
5459 When disabled each filtered channel gain calculation is independent, otherwise when this option
5460 is enabled the minimum of all possible gains for each filtered channel is used.
5463 @subsection Commands
5465 This filter supports the all above options as @ref{commands}.
5467 @section stereotools
5469 This filter has some handy utilities to manage stereo signals, for converting
5470 M/S stereo recordings to L/R signal while having control over the parameters
5471 or spreading the stereo image of master track.
5473 The filter accepts the following options:
5477 Set input level before filtering for both channels. Defaults is 1.
5478 Allowed range is from 0.015625 to 64.
5481 Set output level after filtering for both channels. Defaults is 1.
5482 Allowed range is from 0.015625 to 64.
5485 Set input balance between both channels. Default is 0.
5486 Allowed range is from -1 to 1.
5489 Set output balance between both channels. Default is 0.
5490 Allowed range is from -1 to 1.
5493 Enable softclipping. Results in analog distortion instead of harsh digital 0dB
5494 clipping. Disabled by default.
5497 Mute the left channel. Disabled by default.
5500 Mute the right channel. Disabled by default.
5503 Change the phase of the left channel. Disabled by default.
5506 Change the phase of the right channel. Disabled by default.
5509 Set stereo mode. Available values are:
5513 Left/Right to Left/Right, this is default.
5516 Left/Right to Mid/Side.
5519 Mid/Side to Left/Right.
5522 Left/Right to Left/Left.
5525 Left/Right to Right/Right.
5528 Left/Right to Left + Right.
5531 Left/Right to Right/Left.
5534 Mid/Side to Left/Left.
5537 Mid/Side to Right/Right.
5540 Mid/Side to Right/Left.
5543 Left/Right to Left - Right.
5547 Set level of side signal. Default is 1.
5548 Allowed range is from 0.015625 to 64.
5551 Set balance of side signal. Default is 0.
5552 Allowed range is from -1 to 1.
5555 Set level of the middle signal. Default is 1.
5556 Allowed range is from 0.015625 to 64.
5559 Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
5562 Set stereo base between mono and inversed channels. Default is 0.
5563 Allowed range is from -1 to 1.
5566 Set delay in milliseconds how much to delay left from right channel and
5567 vice versa. Default is 0. Allowed range is from -20 to 20.
5570 Set S/C level. Default is 1. Allowed range is from 1 to 100.
5573 Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
5575 @item bmode_in, bmode_out
5576 Set balance mode for balance_in/balance_out option.
5578 Can be one of the following:
5582 Classic balance mode. Attenuate one channel at time.
5583 Gain is raised up to 1.
5586 Similar as classic mode above but gain is raised up to 2.
5589 Equal power distribution, from -6dB to +6dB range.
5593 @subsection Commands
5595 This filter supports the all above options as @ref{commands}.
5597 @subsection Examples
5601 Apply karaoke like effect:
5603 stereotools=mlev=0.015625
5607 Convert M/S signal to L/R:
5609 "stereotools=mode=ms>lr"
5613 @section stereowiden
5615 This filter enhance the stereo effect by suppressing signal common to both
5616 channels and by delaying the signal of left into right and vice versa,
5617 thereby widening the stereo effect.
5619 The filter accepts the following options:
5623 Time in milliseconds of the delay of left signal into right and vice versa.
5624 Default is 20 milliseconds.
5627 Amount of gain in delayed signal into right and vice versa. Gives a delay
5628 effect of left signal in right output and vice versa which gives widening
5629 effect. Default is 0.3.
5632 Cross feed of left into right with inverted phase. This helps in suppressing
5633 the mono. If the value is 1 it will cancel all the signal common to both
5634 channels. Default is 0.3.
5637 Set level of input signal of original channel. Default is 0.8.
5640 @subsection Commands
5642 This filter supports the all above options except @code{delay} as @ref{commands}.
5644 @section superequalizer
5645 Apply 18 band equalizer.
5647 The filter accepts the following options:
5654 Set 131Hz band gain.
5656 Set 185Hz band gain.
5658 Set 262Hz band gain.
5660 Set 370Hz band gain.
5662 Set 523Hz band gain.
5664 Set 740Hz band gain.
5666 Set 1047Hz band gain.
5668 Set 1480Hz band gain.
5670 Set 2093Hz band gain.
5672 Set 2960Hz band gain.
5674 Set 4186Hz band gain.
5676 Set 5920Hz band gain.
5678 Set 8372Hz band gain.
5680 Set 11840Hz band gain.
5682 Set 16744Hz band gain.
5684 Set 20000Hz band gain.
5688 Apply audio surround upmix filter.
5690 This filter allows to produce multichannel output from audio stream.
5692 The filter accepts the following options:
5696 Set output channel layout. By default, this is @var{5.1}.
5698 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5699 for the required syntax.
5702 Set input channel layout. By default, this is @var{stereo}.
5704 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5705 for the required syntax.
5708 Set input volume level. By default, this is @var{1}.
5711 Set output volume level. By default, this is @var{1}.
5714 Enable LFE channel output if output channel layout has it. By default, this is enabled.
5717 Set LFE low cut off frequency. By default, this is @var{128} Hz.
5720 Set LFE high cut off frequency. By default, this is @var{256} Hz.
5723 Set LFE mode, can be @var{add} or @var{sub}. Default is @var{add}.
5724 In @var{add} mode, LFE channel is created from input audio and added to output.
5725 In @var{sub} mode, LFE channel is created from input audio and added to output but
5726 also all non-LFE output channels are subtracted with output LFE channel.
5729 Set angle of stereo surround transform, Allowed range is from @var{0} to @var{360}.
5730 Default is @var{90}.
5733 Set front center input volume. By default, this is @var{1}.
5736 Set front center output volume. By default, this is @var{1}.
5739 Set front left input volume. By default, this is @var{1}.
5742 Set front left output volume. By default, this is @var{1}.
5745 Set front right input volume. By default, this is @var{1}.
5748 Set front right output volume. By default, this is @var{1}.
5751 Set side left input volume. By default, this is @var{1}.
5754 Set side left output volume. By default, this is @var{1}.
5757 Set side right input volume. By default, this is @var{1}.
5760 Set side right output volume. By default, this is @var{1}.
5763 Set back left input volume. By default, this is @var{1}.
5766 Set back left output volume. By default, this is @var{1}.
5769 Set back right input volume. By default, this is @var{1}.
5772 Set back right output volume. By default, this is @var{1}.
5775 Set back center input volume. By default, this is @var{1}.
5778 Set back center output volume. By default, this is @var{1}.
5781 Set LFE input volume. By default, this is @var{1}.
5784 Set LFE output volume. By default, this is @var{1}.
5787 Set spread usage of stereo image across X axis for all channels.
5790 Set spread usage of stereo image across Y axis for all channels.
5792 @item fcx, flx, frx, blx, brx, slx, srx, bcx
5793 Set spread usage of stereo image across X axis for each channel.
5795 @item fcy, fly, fry, bly, bry, sly, sry, bcy
5796 Set spread usage of stereo image across Y axis for each channel.
5799 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
5802 Set window function.
5804 It accepts the following values:
5827 Default is @code{hann}.
5830 Set window overlap. If set to 1, the recommended overlap for selected
5831 window function will be picked. Default is @code{0.5}.
5834 @section treble, highshelf
5836 Boost or cut treble (upper) frequencies of the audio using a two-pole
5837 shelving filter with a response similar to that of a standard
5838 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
5840 The filter accepts the following options:
5844 Give the gain at whichever is the lower of ~22 kHz and the
5845 Nyquist frequency. Its useful range is about -20 (for a large cut)
5846 to +20 (for a large boost). Beware of clipping when using a positive gain.
5849 Set the filter's central frequency and so can be used
5850 to extend or reduce the frequency range to be boosted or cut.
5851 The default value is @code{3000} Hz.
5854 Set method to specify band-width of filter.
5869 Determine how steep is the filter's shelf transition.
5872 How much to use filtered signal in output. Default is 1.
5873 Range is between 0 and 1.
5876 Specify which channels to filter, by default all available are filtered.
5879 Normalize biquad coefficients, by default is disabled.
5880 Enabling it will normalize magnitude response at DC to 0dB.
5883 Set transform type of IIR filter.
5892 @subsection Commands
5894 This filter supports the following commands:
5897 Change treble frequency.
5898 Syntax for the command is : "@var{frequency}"
5901 Change treble width_type.
5902 Syntax for the command is : "@var{width_type}"
5905 Change treble width.
5906 Syntax for the command is : "@var{width}"
5910 Syntax for the command is : "@var{gain}"
5914 Syntax for the command is : "@var{mix}"
5919 Sinusoidal amplitude modulation.
5921 The filter accepts the following options:
5925 Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
5926 (20 Hz or lower) will result in a tremolo effect.
5927 This filter may also be used as a ring modulator by specifying
5928 a modulation frequency higher than 20 Hz.
5929 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
5932 Depth of modulation as a percentage. Range is 0.0 - 1.0.
5933 Default value is 0.5.
5938 Sinusoidal phase modulation.
5940 The filter accepts the following options:
5944 Modulation frequency in Hertz.
5945 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
5948 Depth of modulation as a percentage. Range is 0.0 - 1.0.
5949 Default value is 0.5.
5954 Adjust the input audio volume.
5956 It accepts the following parameters:
5960 Set audio volume expression.
5962 Output values are clipped to the maximum value.
5964 The output audio volume is given by the relation:
5966 @var{output_volume} = @var{volume} * @var{input_volume}
5969 The default value for @var{volume} is "1.0".
5972 This parameter represents the mathematical precision.
5974 It determines which input sample formats will be allowed, which affects the
5975 precision of the volume scaling.
5979 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
5981 32-bit floating-point; this limits input sample format to FLT. (default)
5983 64-bit floating-point; this limits input sample format to DBL.
5987 Choose the behaviour on encountering ReplayGain side data in input frames.
5991 Remove ReplayGain side data, ignoring its contents (the default).
5994 Ignore ReplayGain side data, but leave it in the frame.
5997 Prefer the track gain, if present.
6000 Prefer the album gain, if present.
6003 @item replaygain_preamp
6004 Pre-amplification gain in dB to apply to the selected replaygain gain.
6006 Default value for @var{replaygain_preamp} is 0.0.
6008 @item replaygain_noclip
6009 Prevent clipping by limiting the gain applied.
6011 Default value for @var{replaygain_noclip} is 1.
6014 Set when the volume expression is evaluated.
6016 It accepts the following values:
6019 only evaluate expression once during the filter initialization, or
6020 when the @samp{volume} command is sent
6023 evaluate expression for each incoming frame
6026 Default value is @samp{once}.
6029 The volume expression can contain the following parameters.
6033 frame number (starting at zero)
6036 @item nb_consumed_samples
6037 number of samples consumed by the filter
6039 number of samples in the current frame
6041 original frame position in the file
6047 PTS at start of stream
6049 time at start of stream
6055 last set volume value
6058 Note that when @option{eval} is set to @samp{once} only the
6059 @var{sample_rate} and @var{tb} variables are available, all other
6060 variables will evaluate to NAN.
6062 @subsection Commands
6064 This filter supports the following commands:
6067 Modify the volume expression.
6068 The command accepts the same syntax of the corresponding option.
6070 If the specified expression is not valid, it is kept at its current
6074 @subsection Examples
6078 Halve the input audio volume:
6082 volume=volume=-6.0206dB
6085 In all the above example the named key for @option{volume} can be
6086 omitted, for example like in:
6092 Increase input audio power by 6 decibels using fixed-point precision:
6094 volume=volume=6dB:precision=fixed
6098 Fade volume after time 10 with an annihilation period of 5 seconds:
6100 volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
6104 @section volumedetect
6106 Detect the volume of the input video.
6108 The filter has no parameters. The input is not modified. Statistics about
6109 the volume will be printed in the log when the input stream end is reached.
6111 In particular it will show the mean volume (root mean square), maximum
6112 volume (on a per-sample basis), and the beginning of a histogram of the
6113 registered volume values (from the maximum value to a cumulated 1/1000 of
6116 All volumes are in decibels relative to the maximum PCM value.
6118 @subsection Examples
6120 Here is an excerpt of the output:
6122 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
6123 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
6124 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
6125 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
6126 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
6127 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
6128 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
6129 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
6130 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
6136 The mean square energy is approximately -27 dB, or 10^-2.7.
6138 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
6140 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
6143 In other words, raising the volume by +4 dB does not cause any clipping,
6144 raising it by +5 dB causes clipping for 6 samples, etc.
6146 @c man end AUDIO FILTERS
6148 @chapter Audio Sources
6149 @c man begin AUDIO SOURCES
6151 Below is a description of the currently available audio sources.
6155 Buffer audio frames, and make them available to the filter chain.
6157 This source is mainly intended for a programmatic use, in particular
6158 through the interface defined in @file{libavfilter/buffersrc.h}.
6160 It accepts the following parameters:
6164 The timebase which will be used for timestamps of submitted frames. It must be
6165 either a floating-point number or in @var{numerator}/@var{denominator} form.
6168 The sample rate of the incoming audio buffers.
6171 The sample format of the incoming audio buffers.
6172 Either a sample format name or its corresponding integer representation from
6173 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
6175 @item channel_layout
6176 The channel layout of the incoming audio buffers.
6177 Either a channel layout name from channel_layout_map in
6178 @file{libavutil/channel_layout.c} or its corresponding integer representation
6179 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
6182 The number of channels of the incoming audio buffers.
6183 If both @var{channels} and @var{channel_layout} are specified, then they
6188 @subsection Examples
6191 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
6194 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
6195 Since the sample format with name "s16p" corresponds to the number
6196 6 and the "stereo" channel layout corresponds to the value 0x3, this is
6199 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
6204 Generate an audio signal specified by an expression.
6206 This source accepts in input one or more expressions (one for each
6207 channel), which are evaluated and used to generate a corresponding
6210 This source accepts the following options:
6214 Set the '|'-separated expressions list for each separate channel. In case the
6215 @option{channel_layout} option is not specified, the selected channel layout
6216 depends on the number of provided expressions. Otherwise the last
6217 specified expression is applied to the remaining output channels.
6219 @item channel_layout, c
6220 Set the channel layout. The number of channels in the specified layout
6221 must be equal to the number of specified expressions.
6224 Set the minimum duration of the sourced audio. See
6225 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
6226 for the accepted syntax.
6227 Note that the resulting duration may be greater than the specified
6228 duration, as the generated audio is always cut at the end of a
6231 If not specified, or the expressed duration is negative, the audio is
6232 supposed to be generated forever.
6235 Set the number of samples per channel per each output frame,
6238 @item sample_rate, s
6239 Specify the sample rate, default to 44100.
6242 Each expression in @var{exprs} can contain the following constants:
6246 number of the evaluated sample, starting from 0
6249 time of the evaluated sample expressed in seconds, starting from 0
6256 @subsection Examples
6266 Generate a sin signal with frequency of 440 Hz, set sample rate to
6269 aevalsrc="sin(440*2*PI*t):s=8000"
6273 Generate a two channels signal, specify the channel layout (Front
6274 Center + Back Center) explicitly:
6276 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
6280 Generate white noise:
6282 aevalsrc="-2+random(0)"
6286 Generate an amplitude modulated signal:
6288 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
6292 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
6294 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
6301 Generate a FIR coefficients using frequency sampling method.
6303 The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
6305 The filter accepts the following options:
6309 Set number of filter coefficents in output audio stream.
6310 Default value is 1025.
6313 Set frequency points from where magnitude and phase are set.
6314 This must be in non decreasing order, and first element must be 0, while last element
6315 must be 1. Elements are separated by white spaces.
6318 Set magnitude value for every frequency point set by @option{frequency}.
6319 Number of values must be same as number of frequency points.
6320 Values are separated by white spaces.
6323 Set phase value for every frequency point set by @option{frequency}.
6324 Number of values must be same as number of frequency points.
6325 Values are separated by white spaces.
6327 @item sample_rate, r
6328 Set sample rate, default is 44100.
6331 Set number of samples per each frame. Default is 1024.
6334 Set window function. Default is blackman.
6339 The null audio source, return unprocessed audio frames. It is mainly useful
6340 as a template and to be employed in analysis / debugging tools, or as
6341 the source for filters which ignore the input data (for example the sox
6344 This source accepts the following options:
6348 @item channel_layout, cl
6350 Specifies the channel layout, and can be either an integer or a string
6351 representing a channel layout. The default value of @var{channel_layout}
6354 Check the channel_layout_map definition in
6355 @file{libavutil/channel_layout.c} for the mapping between strings and
6356 channel layout values.
6358 @item sample_rate, r
6359 Specifies the sample rate, and defaults to 44100.
6362 Set the number of samples per requested frames.
6365 Set the duration of the sourced audio. See
6366 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
6367 for the accepted syntax.
6369 If not specified, or the expressed duration is negative, the audio is
6370 supposed to be generated forever.
6373 @subsection Examples
6377 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
6379 anullsrc=r=48000:cl=4
6383 Do the same operation with a more obvious syntax:
6385 anullsrc=r=48000:cl=mono
6389 All the parameters need to be explicitly defined.
6393 Synthesize a voice utterance using the libflite library.
6395 To enable compilation of this filter you need to configure FFmpeg with
6396 @code{--enable-libflite}.
6398 Note that versions of the flite library prior to 2.0 are not thread-safe.
6400 The filter accepts the following options:
6405 If set to 1, list the names of the available voices and exit
6406 immediately. Default value is 0.
6409 Set the maximum number of samples per frame. Default value is 512.
6412 Set the filename containing the text to speak.
6415 Set the text to speak.
6418 Set the voice to use for the speech synthesis. Default value is
6419 @code{kal}. See also the @var{list_voices} option.
6422 @subsection Examples
6426 Read from file @file{speech.txt}, and synthesize the text using the
6427 standard flite voice:
6429 flite=textfile=speech.txt
6433 Read the specified text selecting the @code{slt} voice:
6435 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
6439 Input text to ffmpeg:
6441 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
6445 Make @file{ffplay} speak the specified text, using @code{flite} and
6446 the @code{lavfi} device:
6448 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
6452 For more information about libflite, check:
6453 @url{http://www.festvox.org/flite/}
6457 Generate a noise audio signal.
6459 The filter accepts the following options:
6462 @item sample_rate, r
6463 Specify the sample rate. Default value is 48000 Hz.
6466 Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value
6470 Specify the duration of the generated audio stream. Not specifying this option
6471 results in noise with an infinite length.
6473 @item color, colour, c
6474 Specify the color of noise. Available noise colors are white, pink, brown,
6475 blue, violet and velvet. Default color is white.
6478 Specify a value used to seed the PRNG.
6481 Set the number of samples per each output frame, default is 1024.
6484 @subsection Examples
6489 Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5:
6491 anoisesrc=d=60:c=pink:r=44100:a=0.5
6497 Generate odd-tap Hilbert transform FIR coefficients.
6499 The resulting stream can be used with @ref{afir} filter for phase-shifting
6500 the signal by 90 degrees.
6502 This is used in many matrix coding schemes and for analytic signal generation.
6503 The process is often written as a multiplication by i (or j), the imaginary unit.
6505 The filter accepts the following options:
6509 @item sample_rate, s
6510 Set sample rate, default is 44100.
6513 Set length of FIR filter, default is 22051.
6516 Set number of samples per each frame.
6519 Set window function to be used when generating FIR coefficients.
6524 Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients.
6526 The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
6528 The filter accepts the following options:
6531 @item sample_rate, r
6532 Set sample rate, default is 44100.
6535 Set number of samples per each frame. Default is 1024.
6538 Set high-pass frequency. Default is 0.
6541 Set low-pass frequency. Default is 0.
6542 If high-pass frequency is lower than low-pass frequency and low-pass frequency
6543 is higher than 0 then filter will create band-pass filter coefficients,
6544 otherwise band-reject filter coefficients.
6547 Set filter phase response. Default is 50. Allowed range is from 0 to 100.
6550 Set Kaiser window beta.
6553 Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB.
6556 Enable rounding, by default is disabled.
6559 Set number of taps for high-pass filter.
6562 Set number of taps for low-pass filter.
6567 Generate an audio signal made of a sine wave with amplitude 1/8.
6569 The audio signal is bit-exact.
6571 The filter accepts the following options:
6576 Set the carrier frequency. Default is 440 Hz.
6578 @item beep_factor, b
6579 Enable a periodic beep every second with frequency @var{beep_factor} times
6580 the carrier frequency. Default is 0, meaning the beep is disabled.
6582 @item sample_rate, r
6583 Specify the sample rate, default is 44100.
6586 Specify the duration of the generated audio stream.
6588 @item samples_per_frame
6589 Set the number of samples per output frame.
6591 The expression can contain the following constants:
6595 The (sequential) number of the output audio frame, starting from 0.
6598 The PTS (Presentation TimeStamp) of the output audio frame,
6599 expressed in @var{TB} units.
6602 The PTS of the output audio frame, expressed in seconds.
6605 The timebase of the output audio frames.
6608 Default is @code{1024}.
6611 @subsection Examples
6616 Generate a simple 440 Hz sine wave:
6622 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
6626 sine=frequency=220:beep_factor=4:duration=5
6630 Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC
6633 sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
6637 @c man end AUDIO SOURCES
6639 @chapter Audio Sinks
6640 @c man begin AUDIO SINKS
6642 Below is a description of the currently available audio sinks.
6644 @section abuffersink
6646 Buffer audio frames, and make them available to the end of filter chain.
6648 This sink is mainly intended for programmatic use, in particular
6649 through the interface defined in @file{libavfilter/buffersink.h}
6650 or the options system.
6652 It accepts a pointer to an AVABufferSinkContext structure, which
6653 defines the incoming buffers' formats, to be passed as the opaque
6654 parameter to @code{avfilter_init_filter} for initialization.
6657 Null audio sink; do absolutely nothing with the input audio. It is
6658 mainly useful as a template and for use in analysis / debugging
6661 @c man end AUDIO SINKS
6663 @chapter Video Filters
6664 @c man begin VIDEO FILTERS
6666 When you configure your FFmpeg build, you can disable any of the
6667 existing filters using @code{--disable-filters}.
6668 The configure output will show the video filters included in your
6671 Below is a description of the currently available video filters.
6675 Mark a region of interest in a video frame.
6677 The frame data is passed through unchanged, but metadata is attached
6678 to the frame indicating regions of interest which can affect the
6679 behaviour of later encoding. Multiple regions can be marked by
6680 applying the filter multiple times.
6684 Region distance in pixels from the left edge of the frame.
6686 Region distance in pixels from the top edge of the frame.
6688 Region width in pixels.
6690 Region height in pixels.
6692 The parameters @var{x}, @var{y}, @var{w} and @var{h} are expressions,
6693 and may contain the following variables:
6696 Width of the input frame.
6698 Height of the input frame.
6702 Quantisation offset to apply within the region.
6704 This must be a real value in the range -1 to +1. A value of zero
6705 indicates no quality change. A negative value asks for better quality
6706 (less quantisation), while a positive value asks for worse quality
6707 (greater quantisation).
6709 The range is calibrated so that the extreme values indicate the
6710 largest possible offset - if the rest of the frame is encoded with the
6711 worst possible quality, an offset of -1 indicates that this region
6712 should be encoded with the best possible quality anyway. Intermediate
6713 values are then interpolated in some codec-dependent way.
6715 For example, in 10-bit H.264 the quantisation parameter varies between
6716 -12 and 51. A typical qoffset value of -1/10 therefore indicates that
6717 this region should be encoded with a QP around one-tenth of the full
6718 range better than the rest of the frame. So, if most of the frame
6719 were to be encoded with a QP of around 30, this region would get a QP
6720 of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3).
6721 An extreme value of -1 would indicate that this region should be
6722 encoded with the best possible quality regardless of the treatment of
6723 the rest of the frame - that is, should be encoded at a QP of -12.
6725 If set to true, remove any existing regions of interest marked on the
6726 frame before adding the new one.
6729 @subsection Examples
6733 Mark the centre quarter of the frame as interesting.
6735 addroi=iw/4:ih/4:iw/2:ih/2:-1/10
6738 Mark the 100-pixel-wide region on the left edge of the frame as very
6739 uninteresting (to be encoded at much lower quality than the rest of
6742 addroi=0:0:100:ih:+1/5
6746 @section alphaextract
6748 Extract the alpha component from the input as a grayscale video. This
6749 is especially useful with the @var{alphamerge} filter.
6753 Add or replace the alpha component of the primary input with the
6754 grayscale value of a second input. This is intended for use with
6755 @var{alphaextract} to allow the transmission or storage of frame
6756 sequences that have alpha in a format that doesn't support an alpha
6759 For example, to reconstruct full frames from a normal YUV-encoded video
6760 and a separate video created with @var{alphaextract}, you might use:
6762 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
6767 Amplify differences between current pixel and pixels of adjacent frames in
6768 same pixel location.
6770 This filter accepts the following options:
6774 Set frame radius. Default is 2. Allowed range is from 1 to 63.
6775 For example radius of 3 will instruct filter to calculate average of 7 frames.
6778 Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535.
6781 Set threshold for difference amplification. Any difference greater or equal to
6782 this value will not alter source pixel. Default is 10.
6783 Allowed range is from 0 to 65535.
6786 Set tolerance for difference amplification. Any difference lower to
6787 this value will not alter source pixel. Default is 0.
6788 Allowed range is from 0 to 65535.
6791 Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
6792 This option controls maximum possible value that will decrease source pixel value.
6795 Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
6796 This option controls maximum possible value that will increase source pixel value.
6799 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
6802 @subsection Commands
6804 This filter supports the following @ref{commands} that corresponds to option of same name:
6816 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
6817 and libavformat to work. On the other hand, it is limited to ASS (Advanced
6818 Substation Alpha) subtitles files.
6820 This filter accepts the following option in addition to the common options from
6821 the @ref{subtitles} filter:
6825 Set the shaping engine
6827 Available values are:
6830 The default libass shaping engine, which is the best available.
6832 Fast, font-agnostic shaper that can do only substitutions
6834 Slower shaper using OpenType for substitutions and positioning
6837 The default is @code{auto}.
6841 Apply an Adaptive Temporal Averaging Denoiser to the video input.
6843 The filter accepts the following options:
6847 Set threshold A for 1st plane. Default is 0.02.
6848 Valid range is 0 to 0.3.
6851 Set threshold B for 1st plane. Default is 0.04.
6852 Valid range is 0 to 5.
6855 Set threshold A for 2nd plane. Default is 0.02.
6856 Valid range is 0 to 0.3.
6859 Set threshold B for 2nd plane. Default is 0.04.
6860 Valid range is 0 to 5.
6863 Set threshold A for 3rd plane. Default is 0.02.
6864 Valid range is 0 to 0.3.
6867 Set threshold B for 3rd plane. Default is 0.04.
6868 Valid range is 0 to 5.
6870 Threshold A is designed to react on abrupt changes in the input signal and
6871 threshold B is designed to react on continuous changes in the input signal.
6874 Set number of frames filter will use for averaging. Default is 9. Must be odd
6875 number in range [5, 129].
6878 Set what planes of frame filter will use for averaging. Default is all.
6881 Set what variant of algorithm filter will use for averaging. Default is @code{p} parallel.
6882 Alternatively can be set to @code{s} serial.
6884 Parallel can be faster then serial, while other way around is never true.
6885 Parallel will abort early on first change being greater then thresholds, while serial
6886 will continue processing other side of frames if they are equal or below thresholds.
6889 @subsection Commands
6890 This filter supports same @ref{commands} as options except option @code{s}.
6891 The command accepts the same syntax of the corresponding option.
6895 Apply average blur filter.
6897 The filter accepts the following options:
6901 Set horizontal radius size.
6904 Set which planes to filter. By default all planes are filtered.
6907 Set vertical radius size, if zero it will be same as @code{sizeX}.
6908 Default is @code{0}.
6911 @subsection Commands
6912 This filter supports same commands as options.
6913 The command accepts the same syntax of the corresponding option.
6915 If the specified expression is not valid, it is kept at its current
6920 Compute the bounding box for the non-black pixels in the input frame
6923 This filter computes the bounding box containing all the pixels with a
6924 luminance value greater than the minimum allowed value.
6925 The parameters describing the bounding box are printed on the filter
6928 The filter accepts the following option:
6932 Set the minimal luminance value. Default is @code{16}.
6936 Apply bilateral filter, spatial smoothing while preserving edges.
6938 The filter accepts the following options:
6941 Set sigma of gaussian function to calculate spatial weight.
6942 Allowed range is 0 to 512. Default is 0.1.
6945 Set sigma of gaussian function to calculate range weight.
6946 Allowed range is 0 to 1. Default is 0.1.
6949 Set planes to filter. Default is first only.
6952 @section bitplanenoise
6954 Show and measure bit plane noise.
6956 The filter accepts the following options:
6960 Set which plane to analyze. Default is @code{1}.
6963 Filter out noisy pixels from @code{bitplane} set above.
6964 Default is disabled.
6967 @section blackdetect
6969 Detect video intervals that are (almost) completely black. Can be
6970 useful to detect chapter transitions, commercials, or invalid
6973 The filter outputs its detection analysis to both the log as well as
6974 frame metadata. If a black segment of at least the specified minimum
6975 duration is found, a line with the start and end timestamps as well
6976 as duration is printed to the log with level @code{info}. In addition,
6977 a log line with level @code{debug} is printed per frame showing the
6978 black amount detected for that frame.
6980 The filter also attaches metadata to the first frame of a black
6981 segment with key @code{lavfi.black_start} and to the first frame
6982 after the black segment ends with key @code{lavfi.black_end}. The
6983 value is the frame's timestamp. This metadata is added regardless
6984 of the minimum duration specified.
6986 The filter accepts the following options:
6989 @item black_min_duration, d
6990 Set the minimum detected black duration expressed in seconds. It must
6991 be a non-negative floating point number.
6993 Default value is 2.0.
6995 @item picture_black_ratio_th, pic_th
6996 Set the threshold for considering a picture "black".
6997 Express the minimum value for the ratio:
6999 @var{nb_black_pixels} / @var{nb_pixels}
7002 for which a picture is considered black.
7003 Default value is 0.98.
7005 @item pixel_black_th, pix_th
7006 Set the threshold for considering a pixel "black".
7008 The threshold expresses the maximum pixel luminance value for which a
7009 pixel is considered "black". The provided value is scaled according to
7010 the following equation:
7012 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
7015 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
7016 the input video format, the range is [0-255] for YUV full-range
7017 formats and [16-235] for YUV non full-range formats.
7019 Default value is 0.10.
7022 The following example sets the maximum pixel threshold to the minimum
7023 value, and detects only black intervals of 2 or more seconds:
7025 blackdetect=d=2:pix_th=0.00
7030 Detect frames that are (almost) completely black. Can be useful to
7031 detect chapter transitions or commercials. Output lines consist of
7032 the frame number of the detected frame, the percentage of blackness,
7033 the position in the file if known or -1 and the timestamp in seconds.
7035 In order to display the output lines, you need to set the loglevel at
7036 least to the AV_LOG_INFO value.
7038 This filter exports frame metadata @code{lavfi.blackframe.pblack}.
7039 The value represents the percentage of pixels in the picture that
7040 are below the threshold value.
7042 It accepts the following parameters:
7047 The percentage of the pixels that have to be below the threshold; it defaults to
7050 @item threshold, thresh
7051 The threshold below which a pixel value is considered black; it defaults to
7059 Blend two video frames into each other.
7061 The @code{blend} filter takes two input streams and outputs one
7062 stream, the first input is the "top" layer and second input is
7063 "bottom" layer. By default, the output terminates when the longest input terminates.
7065 The @code{tblend} (time blend) filter takes two consecutive frames
7066 from one single stream, and outputs the result obtained by blending
7067 the new frame on top of the old frame.
7069 A description of the accepted options follows.
7077 Set blend mode for specific pixel component or all pixel components in case
7078 of @var{all_mode}. Default value is @code{normal}.
7080 Available values for component modes are:
7122 Set blend opacity for specific pixel component or all pixel components in case
7123 of @var{all_opacity}. Only used in combination with pixel component blend modes.
7130 Set blend expression for specific pixel component or all pixel components in case
7131 of @var{all_expr}. Note that related mode options will be ignored if those are set.
7133 The expressions can use the following variables:
7137 The sequential number of the filtered frame, starting from @code{0}.
7141 the coordinates of the current sample
7145 the width and height of currently filtered plane
7149 Width and height scale for the plane being filtered. It is the
7150 ratio between the dimensions of the current plane to the luma plane,
7151 e.g. for a @code{yuv420p} frame, the values are @code{1,1} for
7152 the luma plane and @code{0.5,0.5} for the chroma planes.
7155 Time of the current frame, expressed in seconds.
7158 Value of pixel component at current location for first video frame (top layer).
7161 Value of pixel component at current location for second video frame (bottom layer).
7165 The @code{blend} filter also supports the @ref{framesync} options.
7167 @subsection Examples
7171 Apply transition from bottom layer to top layer in first 10 seconds:
7173 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
7177 Apply linear horizontal transition from top layer to bottom layer:
7179 blend=all_expr='A*(X/W)+B*(1-X/W)'
7183 Apply 1x1 checkerboard effect:
7185 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
7189 Apply uncover left effect:
7191 blend=all_expr='if(gte(N*SW+X,W),A,B)'
7195 Apply uncover down effect:
7197 blend=all_expr='if(gte(Y-N*SH,0),A,B)'
7201 Apply uncover up-left effect:
7203 blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
7207 Split diagonally video and shows top and bottom layer on each side:
7209 blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
7213 Display differences between the current and the previous frame:
7215 tblend=all_mode=grainextract
7221 Denoise frames using Block-Matching 3D algorithm.
7223 The filter accepts the following options.
7227 Set denoising strength. Default value is 1.
7228 Allowed range is from 0 to 999.9.
7229 The denoising algorithm is very sensitive to sigma, so adjust it
7230 according to the source.
7233 Set local patch size. This sets dimensions in 2D.
7236 Set sliding step for processing blocks. Default value is 4.
7237 Allowed range is from 1 to 64.
7238 Smaller values allows processing more reference blocks and is slower.
7241 Set maximal number of similar blocks for 3rd dimension. Default value is 1.
7242 When set to 1, no block matching is done. Larger values allows more blocks
7244 Allowed range is from 1 to 256.
7247 Set radius for search block matching. Default is 9.
7248 Allowed range is from 1 to INT32_MAX.
7251 Set step between two search locations for block matching. Default is 1.
7252 Allowed range is from 1 to 64. Smaller is slower.
7255 Set threshold of mean square error for block matching. Valid range is 0 to
7259 Set thresholding parameter for hard thresholding in 3D transformed domain.
7260 Larger values results in stronger hard-thresholding filtering in frequency
7264 Set filtering estimation mode. Can be @code{basic} or @code{final}.
7265 Default is @code{basic}.
7268 If enabled, filter will use 2nd stream for block matching.
7269 Default is disabled for @code{basic} value of @var{estim} option,
7270 and always enabled if value of @var{estim} is @code{final}.
7273 Set planes to filter. Default is all available except alpha.
7276 @subsection Examples
7280 Basic filtering with bm3d:
7282 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
7286 Same as above, but filtering only luma:
7288 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
7292 Same as above, but with both estimation modes:
7294 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
7298 Same as above, but prefilter with @ref{nlmeans} filter instead:
7300 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
7306 Apply a boxblur algorithm to the input video.
7308 It accepts the following parameters:
7312 @item luma_radius, lr
7313 @item luma_power, lp
7314 @item chroma_radius, cr
7315 @item chroma_power, cp
7316 @item alpha_radius, ar
7317 @item alpha_power, ap
7321 A description of the accepted options follows.
7324 @item luma_radius, lr
7325 @item chroma_radius, cr
7326 @item alpha_radius, ar
7327 Set an expression for the box radius in pixels used for blurring the
7328 corresponding input plane.
7330 The radius value must be a non-negative number, and must not be
7331 greater than the value of the expression @code{min(w,h)/2} for the
7332 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
7335 Default value for @option{luma_radius} is "2". If not specified,
7336 @option{chroma_radius} and @option{alpha_radius} default to the
7337 corresponding value set for @option{luma_radius}.
7339 The expressions can contain the following constants:
7343 The input width and height in pixels.
7347 The input chroma image width and height in pixels.
7351 The horizontal and vertical chroma subsample values. For example, for the
7352 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
7355 @item luma_power, lp
7356 @item chroma_power, cp
7357 @item alpha_power, ap
7358 Specify how many times the boxblur filter is applied to the
7359 corresponding plane.
7361 Default value for @option{luma_power} is 2. If not specified,
7362 @option{chroma_power} and @option{alpha_power} default to the
7363 corresponding value set for @option{luma_power}.
7365 A value of 0 will disable the effect.
7368 @subsection Examples
7372 Apply a boxblur filter with the luma, chroma, and alpha radii
7375 boxblur=luma_radius=2:luma_power=1
7380 Set the luma radius to 2, and alpha and chroma radius to 0:
7382 boxblur=2:1:cr=0:ar=0
7386 Set the luma and chroma radii to a fraction of the video dimension:
7388 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
7394 Deinterlace the input video ("bwdif" stands for "Bob Weaver
7395 Deinterlacing Filter").
7397 Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
7398 interpolation algorithms.
7399 It accepts the following parameters:
7403 The interlacing mode to adopt. It accepts one of the following values:
7407 Output one frame for each frame.
7409 Output one frame for each field.
7412 The default value is @code{send_field}.
7415 The picture field parity assumed for the input interlaced video. It accepts one
7416 of the following values:
7420 Assume the top field is first.
7422 Assume the bottom field is first.
7424 Enable automatic detection of field parity.
7427 The default value is @code{auto}.
7428 If the interlacing is unknown or the decoder does not export this information,
7429 top field first will be assumed.
7432 Specify which frames to deinterlace. Accepts one of the following
7437 Deinterlace all frames.
7439 Only deinterlace frames marked as interlaced.
7442 The default value is @code{all}.
7447 Apply Contrast Adaptive Sharpen filter to video stream.
7449 The filter accepts the following options:
7453 Set the sharpening strength. Default value is 0.
7456 Set planes to filter. Default value is to filter all
7457 planes except alpha plane.
7461 Remove all color information for all colors except for certain one.
7463 The filter accepts the following options:
7467 The color which will not be replaced with neutral chroma.
7470 Similarity percentage with the above color.
7471 0.01 matches only the exact key color, while 1.0 matches everything.
7475 0.0 makes pixels either fully gray, or not gray at all.
7476 Higher values result in more preserved color.
7479 Signals that the color passed is already in YUV instead of RGB.
7481 Literal colors like "green" or "red" don't make sense with this enabled anymore.
7482 This can be used to pass exact YUV values as hexadecimal numbers.
7485 @subsection Commands
7486 This filter supports same @ref{commands} as options.
7487 The command accepts the same syntax of the corresponding option.
7489 If the specified expression is not valid, it is kept at its current
7493 YUV colorspace color/chroma keying.
7495 The filter accepts the following options:
7499 The color which will be replaced with transparency.
7502 Similarity percentage with the key color.
7504 0.01 matches only the exact key color, while 1.0 matches everything.
7509 0.0 makes pixels either fully transparent, or not transparent at all.
7511 Higher values result in semi-transparent pixels, with a higher transparency
7512 the more similar the pixels color is to the key color.
7515 Signals that the color passed is already in YUV instead of RGB.
7517 Literal colors like "green" or "red" don't make sense with this enabled anymore.
7518 This can be used to pass exact YUV values as hexadecimal numbers.
7521 @subsection Commands
7522 This filter supports same @ref{commands} as options.
7523 The command accepts the same syntax of the corresponding option.
7525 If the specified expression is not valid, it is kept at its current
7528 @subsection Examples
7532 Make every green pixel in the input image transparent:
7534 ffmpeg -i input.png -vf chromakey=green out.png
7538 Overlay a greenscreen-video on top of a static black background.
7540 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
7545 Reduce chrominance noise.
7547 The filter accepts the following options:
7551 Set threshold for averaging chrominance values.
7552 Sum of absolute difference of U and V pixel components or current
7553 pixel and neighbour pixels lower than this threshold will be used in
7554 averaging. Luma component is left unchanged and is copied to output.
7555 Default value is 30. Allowed range is from 1 to 200.
7558 Set horizontal radius of rectangle used for averaging.
7559 Allowed range is from 1 to 100. Default value is 5.
7562 Set vertical radius of rectangle used for averaging.
7563 Allowed range is from 1 to 100. Default value is 5.
7566 Set horizontal step when averaging. Default value is 1.
7567 Allowed range is from 1 to 50.
7568 Mostly useful to speed-up filtering.
7571 Set vertical step when averaging. Default value is 1.
7572 Allowed range is from 1 to 50.
7573 Mostly useful to speed-up filtering.
7576 @subsection Commands
7577 This filter supports same @ref{commands} as options.
7578 The command accepts the same syntax of the corresponding option.
7580 @section chromashift
7581 Shift chroma pixels horizontally and/or vertically.
7583 The filter accepts the following options:
7586 Set amount to shift chroma-blue horizontally.
7588 Set amount to shift chroma-blue vertically.
7590 Set amount to shift chroma-red horizontally.
7592 Set amount to shift chroma-red vertically.
7594 Set edge mode, can be @var{smear}, default, or @var{warp}.
7597 @subsection Commands
7599 This filter supports the all above options as @ref{commands}.
7603 Display CIE color diagram with pixels overlaid onto it.
7605 The filter accepts the following options:
7620 @item uhdtv, rec2020
7634 Set what gamuts to draw.
7636 See @code{system} option for available values.
7639 Set ciescope size, by default set to 512.
7642 Set intensity used to map input pixel values to CIE diagram.
7645 Set contrast used to draw tongue colors that are out of active color system gamut.
7648 Correct gamma displayed on scope, by default enabled.
7651 Show white point on CIE diagram, by default disabled.
7654 Set input gamma. Used only with XYZ input color space.
7659 Visualize information exported by some codecs.
7661 Some codecs can export information through frames using side-data or other
7662 means. For example, some MPEG based codecs export motion vectors through the
7663 @var{export_mvs} flag in the codec @option{flags2} option.
7665 The filter accepts the following option:
7669 Set motion vectors to visualize.
7671 Available flags for @var{mv} are:
7675 forward predicted MVs of P-frames
7677 forward predicted MVs of B-frames
7679 backward predicted MVs of B-frames
7683 Display quantization parameters using the chroma planes.
7686 Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
7688 Available flags for @var{mv_type} are:
7692 forward predicted MVs
7694 backward predicted MVs
7697 @item frame_type, ft
7698 Set frame type to visualize motion vectors of.
7700 Available flags for @var{frame_type} are:
7704 intra-coded frames (I-frames)
7706 predicted frames (P-frames)
7708 bi-directionally predicted frames (B-frames)
7712 @subsection Examples
7716 Visualize forward predicted MVs of all frames using @command{ffplay}:
7718 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
7722 Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
7724 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
7728 @section colorbalance
7729 Modify intensity of primary colors (red, green and blue) of input frames.
7731 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
7732 regions for the red-cyan, green-magenta or blue-yellow balance.
7734 A positive adjustment value shifts the balance towards the primary color, a negative
7735 value towards the complementary color.
7737 The filter accepts the following options:
7743 Adjust red, green and blue shadows (darkest pixels).
7748 Adjust red, green and blue midtones (medium pixels).
7753 Adjust red, green and blue highlights (brightest pixels).
7755 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
7758 Preserve lightness when changing color balance. Default is disabled.
7761 @subsection Examples
7765 Add red color cast to shadows:
7771 @subsection Commands
7773 This filter supports the all above options as @ref{commands}.
7775 @section colorchannelmixer
7777 Adjust video input frames by re-mixing color channels.
7779 This filter modifies a color channel by adding the values associated to
7780 the other channels of the same pixels. For example if the value to
7781 modify is red, the output value will be:
7783 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
7786 The filter accepts the following options:
7793 Adjust contribution of input red, green, blue and alpha channels for output red channel.
7794 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
7800 Adjust contribution of input red, green, blue and alpha channels for output green channel.
7801 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
7807 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
7808 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
7814 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
7815 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
7817 Allowed ranges for options are @code{[-2.0, 2.0]}.
7820 @subsection Examples
7824 Convert source to grayscale:
7826 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
7829 Simulate sepia tones:
7831 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
7835 @subsection Commands
7837 This filter supports the all above options as @ref{commands}.
7840 RGB colorspace color keying.
7842 The filter accepts the following options:
7846 The color which will be replaced with transparency.
7849 Similarity percentage with the key color.
7851 0.01 matches only the exact key color, while 1.0 matches everything.
7856 0.0 makes pixels either fully transparent, or not transparent at all.
7858 Higher values result in semi-transparent pixels, with a higher transparency
7859 the more similar the pixels color is to the key color.
7862 @subsection Examples
7866 Make every green pixel in the input image transparent:
7868 ffmpeg -i input.png -vf colorkey=green out.png
7872 Overlay a greenscreen-video on top of a static background image.
7874 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
7878 @subsection Commands
7879 This filter supports same @ref{commands} as options.
7880 The command accepts the same syntax of the corresponding option.
7882 If the specified expression is not valid, it is kept at its current
7886 Remove all color information for all RGB colors except for certain one.
7888 The filter accepts the following options:
7892 The color which will not be replaced with neutral gray.
7895 Similarity percentage with the above color.
7896 0.01 matches only the exact key color, while 1.0 matches everything.
7899 Blend percentage. 0.0 makes pixels fully gray.
7900 Higher values result in more preserved color.
7903 @subsection Commands
7904 This filter supports same @ref{commands} as options.
7905 The command accepts the same syntax of the corresponding option.
7907 If the specified expression is not valid, it is kept at its current
7910 @section colorlevels
7912 Adjust video input frames using levels.
7914 The filter accepts the following options:
7921 Adjust red, green, blue and alpha input black point.
7922 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
7928 Adjust red, green, blue and alpha input white point.
7929 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
7931 Input levels are used to lighten highlights (bright tones), darken shadows
7932 (dark tones), change the balance of bright and dark tones.
7938 Adjust red, green, blue and alpha output black point.
7939 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
7945 Adjust red, green, blue and alpha output white point.
7946 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
7948 Output levels allows manual selection of a constrained output level range.
7951 @subsection Examples
7955 Make video output darker:
7957 colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
7963 colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
7967 Make video output lighter:
7969 colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
7973 Increase brightness:
7975 colorlevels=romin=0.5:gomin=0.5:bomin=0.5
7979 @subsection Commands
7981 This filter supports the all above options as @ref{commands}.
7983 @section colormatrix
7985 Convert color matrix.
7987 The filter accepts the following options:
7992 Specify the source and destination color matrix. Both values must be
7995 The accepted values are:
8023 For example to convert from BT.601 to SMPTE-240M, use the command:
8025 colormatrix=bt601:smpte240m
8030 Convert colorspace, transfer characteristics or color primaries.
8031 Input video needs to have an even size.
8033 The filter accepts the following options:
8038 Specify all color properties at once.
8040 The accepted values are:
8070 Specify output colorspace.
8072 The accepted values are:
8081 BT.470BG or BT.601-6 625
8084 SMPTE-170M or BT.601-6 525
8093 BT.2020 with non-constant luminance
8099 Specify output transfer characteristics.
8101 The accepted values are:
8113 Constant gamma of 2.2
8116 Constant gamma of 2.8
8119 SMPTE-170M, BT.601-6 625 or BT.601-6 525
8137 BT.2020 for 10-bits content
8140 BT.2020 for 12-bits content
8146 Specify output color primaries.
8148 The accepted values are:
8157 BT.470BG or BT.601-6 625
8160 SMPTE-170M or BT.601-6 525
8184 Specify output color range.
8186 The accepted values are:
8189 TV (restricted) range
8192 MPEG (restricted) range
8203 Specify output color format.
8205 The accepted values are:
8208 YUV 4:2:0 planar 8-bits
8211 YUV 4:2:0 planar 10-bits
8214 YUV 4:2:0 planar 12-bits
8217 YUV 4:2:2 planar 8-bits
8220 YUV 4:2:2 planar 10-bits
8223 YUV 4:2:2 planar 12-bits
8226 YUV 4:4:4 planar 8-bits
8229 YUV 4:4:4 planar 10-bits
8232 YUV 4:4:4 planar 12-bits
8237 Do a fast conversion, which skips gamma/primary correction. This will take
8238 significantly less CPU, but will be mathematically incorrect. To get output
8239 compatible with that produced by the colormatrix filter, use fast=1.
8242 Specify dithering mode.
8244 The accepted values are:
8250 Floyd-Steinberg dithering
8254 Whitepoint adaptation mode.
8256 The accepted values are:
8259 Bradford whitepoint adaptation
8262 von Kries whitepoint adaptation
8265 identity whitepoint adaptation (i.e. no whitepoint adaptation)
8269 Override all input properties at once. Same accepted values as @ref{all}.
8272 Override input colorspace. Same accepted values as @ref{space}.
8275 Override input color primaries. Same accepted values as @ref{primaries}.
8278 Override input transfer characteristics. Same accepted values as @ref{trc}.
8281 Override input color range. Same accepted values as @ref{range}.
8285 The filter converts the transfer characteristics, color space and color
8286 primaries to the specified user values. The output value, if not specified,
8287 is set to a default value based on the "all" property. If that property is
8288 also not specified, the filter will log an error. The output color range and
8289 format default to the same value as the input color range and format. The
8290 input transfer characteristics, color space, color primaries and color range
8291 should be set on the input data. If any of these are missing, the filter will
8292 log an error and no conversion will take place.
8294 For example to convert the input to SMPTE-240M, use the command:
8296 colorspace=smpte240m
8299 @section convolution
8301 Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
8303 The filter accepts the following options:
8310 Set matrix for each plane.
8311 Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode,
8312 and from 1 to 49 odd number of signed integers in @var{row} mode.
8318 Set multiplier for calculated value for each plane.
8319 If unset or 0, it will be sum of all matrix elements.
8325 Set bias for each plane. This value is added to the result of the multiplication.
8326 Useful for making the overall image brighter or darker. Default is 0.0.
8332 Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}.
8333 Default is @var{square}.
8336 @subsection Examples
8342 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"
8348 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"
8354 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"
8360 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"
8364 Apply laplacian edge detector which includes diagonals:
8366 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"
8372 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"
8378 Apply 2D convolution of video stream in frequency domain using second stream
8381 The filter accepts the following options:
8385 Set which planes to process.
8388 Set which impulse video frames will be processed, can be @var{first}
8389 or @var{all}. Default is @var{all}.
8392 The @code{convolve} filter also supports the @ref{framesync} options.
8396 Copy the input video source unchanged to the output. This is mainly useful for
8401 Video filtering on GPU using Apple's CoreImage API on OSX.
8403 Hardware acceleration is based on an OpenGL context. Usually, this means it is
8404 processed by video hardware. However, software-based OpenGL implementations
8405 exist which means there is no guarantee for hardware processing. It depends on
8408 There are many filters and image generators provided by Apple that come with a
8409 large variety of options. The filter has to be referenced by its name along
8412 The coreimage filter accepts the following options:
8415 List all available filters and generators along with all their respective
8416 options as well as possible minimum and maximum values along with the default
8423 Specify all filters by their respective name and options.
8424 Use @var{list_filters} to determine all valid filter names and options.
8425 Numerical options are specified by a float value and are automatically clamped
8426 to their respective value range. Vector and color options have to be specified
8427 by a list of space separated float values. Character escaping has to be done.
8428 A special option name @code{default} is available to use default options for a
8431 It is required to specify either @code{default} or at least one of the filter options.
8432 All omitted options are used with their default values.
8433 The syntax of the filter string is as follows:
8435 filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
8439 Specify a rectangle where the output of the filter chain is copied into the
8440 input image. It is given by a list of space separated float values:
8442 output_rect=x\ y\ width\ height
8444 If not given, the output rectangle equals the dimensions of the input image.
8445 The output rectangle is automatically cropped at the borders of the input
8446 image. Negative values are valid for each component.
8448 output_rect=25\ 25\ 100\ 100
8452 Several filters can be chained for successive processing without GPU-HOST
8453 transfers allowing for fast processing of complex filter chains.
8454 Currently, only filters with zero (generators) or exactly one (filters) input
8455 image and one output image are supported. Also, transition filters are not yet
8458 Some filters generate output images with additional padding depending on the
8459 respective filter kernel. The padding is automatically removed to ensure the
8460 filter output has the same size as the input image.
8462 For image generators, the size of the output image is determined by the
8463 previous output image of the filter chain or the input image of the whole
8464 filterchain, respectively. The generators do not use the pixel information of
8465 this image to generate their output. However, the generated output is
8466 blended onto this image, resulting in partial or complete coverage of the
8469 The @ref{coreimagesrc} video source can be used for generating input images
8470 which are directly fed into the filter chain. By using it, providing input
8471 images by another video source or an input video is not required.
8473 @subsection Examples
8478 List all filters available:
8480 coreimage=list_filters=true
8484 Use the CIBoxBlur filter with default options to blur an image:
8486 coreimage=filter=CIBoxBlur@@default
8490 Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
8491 its center at 100x100 and a radius of 50 pixels:
8493 coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
8497 Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
8498 given as complete and escaped command-line for Apple's standard bash shell:
8500 ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
8506 Cover a rectangular object
8508 It accepts the following options:
8512 Filepath of the optional cover image, needs to be in yuv420.
8517 It accepts the following values:
8520 cover it by the supplied image
8522 cover it by interpolating the surrounding pixels
8525 Default value is @var{blur}.
8528 @subsection Examples
8532 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
8534 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
8540 Crop the input video to given dimensions.
8542 It accepts the following parameters:
8546 The width of the output video. It defaults to @code{iw}.
8547 This expression is evaluated only once during the filter
8548 configuration, or when the @samp{w} or @samp{out_w} command is sent.
8551 The height of the output video. It defaults to @code{ih}.
8552 This expression is evaluated only once during the filter
8553 configuration, or when the @samp{h} or @samp{out_h} command is sent.
8556 The horizontal position, in the input video, of the left edge of the output
8557 video. It defaults to @code{(in_w-out_w)/2}.
8558 This expression is evaluated per-frame.
8561 The vertical position, in the input video, of the top edge of the output video.
8562 It defaults to @code{(in_h-out_h)/2}.
8563 This expression is evaluated per-frame.
8566 If set to 1 will force the output display aspect ratio
8567 to be the same of the input, by changing the output sample aspect
8568 ratio. It defaults to 0.
8571 Enable exact cropping. If enabled, subsampled videos will be cropped at exact
8572 width/height/x/y as specified and will not be rounded to nearest smaller value.
8576 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
8577 expressions containing the following constants:
8582 The computed values for @var{x} and @var{y}. They are evaluated for
8587 The input width and height.
8591 These are the same as @var{in_w} and @var{in_h}.
8595 The output (cropped) width and height.
8599 These are the same as @var{out_w} and @var{out_h}.
8602 same as @var{iw} / @var{ih}
8605 input sample aspect ratio
8608 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
8612 horizontal and vertical chroma subsample values. For example for the
8613 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8616 The number of the input frame, starting from 0.
8619 the position in the file of the input frame, NAN if unknown
8622 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
8626 The expression for @var{out_w} may depend on the value of @var{out_h},
8627 and the expression for @var{out_h} may depend on @var{out_w}, but they
8628 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
8629 evaluated after @var{out_w} and @var{out_h}.
8631 The @var{x} and @var{y} parameters specify the expressions for the
8632 position of the top-left corner of the output (non-cropped) area. They
8633 are evaluated for each frame. If the evaluated value is not valid, it
8634 is approximated to the nearest valid value.
8636 The expression for @var{x} may depend on @var{y}, and the expression
8637 for @var{y} may depend on @var{x}.
8639 @subsection Examples
8643 Crop area with size 100x100 at position (12,34).
8648 Using named options, the example above becomes:
8650 crop=w=100:h=100:x=12:y=34
8654 Crop the central input area with size 100x100:
8660 Crop the central input area with size 2/3 of the input video:
8662 crop=2/3*in_w:2/3*in_h
8666 Crop the input video central square:
8673 Delimit the rectangle with the top-left corner placed at position
8674 100:100 and the right-bottom corner corresponding to the right-bottom
8675 corner of the input image.
8677 crop=in_w-100:in_h-100:100:100
8681 Crop 10 pixels from the left and right borders, and 20 pixels from
8682 the top and bottom borders
8684 crop=in_w-2*10:in_h-2*20
8688 Keep only the bottom right quarter of the input image:
8690 crop=in_w/2:in_h/2:in_w/2:in_h/2
8694 Crop height for getting Greek harmony:
8696 crop=in_w:1/PHI*in_w
8700 Apply trembling effect:
8702 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)
8706 Apply erratic camera effect depending on timestamp:
8708 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)"
8712 Set x depending on the value of y:
8714 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
8718 @subsection Commands
8720 This filter supports the following commands:
8726 Set width/height of the output video and the horizontal/vertical position
8728 The command accepts the same syntax of the corresponding option.
8730 If the specified expression is not valid, it is kept at its current
8736 Auto-detect the crop size.
8738 It calculates the necessary cropping parameters and prints the
8739 recommended parameters via the logging system. The detected dimensions
8740 correspond to the non-black area of the input video.
8742 It accepts the following parameters:
8747 Set higher black value threshold, which can be optionally specified
8748 from nothing (0) to everything (255 for 8-bit based formats). An intensity
8749 value greater to the set value is considered non-black. It defaults to 24.
8750 You can also specify a value between 0.0 and 1.0 which will be scaled depending
8751 on the bitdepth of the pixel format.
8754 The value which the width/height should be divisible by. It defaults to
8755 16. The offset is automatically adjusted to center the video. Use 2 to
8756 get only even dimensions (needed for 4:2:2 video). 16 is best when
8757 encoding to most video codecs.
8759 @item reset_count, reset
8760 Set the counter that determines after how many frames cropdetect will
8761 reset the previously detected largest video area and start over to
8762 detect the current optimal crop area. Default value is 0.
8764 This can be useful when channel logos distort the video area. 0
8765 indicates 'never reset', and returns the largest area encountered during
8772 Delay video filtering until a given wallclock timestamp. The filter first
8773 passes on @option{preroll} amount of frames, then it buffers at most
8774 @option{buffer} amount of frames and waits for the cue. After reaching the cue
8775 it forwards the buffered frames and also any subsequent frames coming in its
8778 The filter can be used synchronize the output of multiple ffmpeg processes for
8779 realtime output devices like decklink. By putting the delay in the filtering
8780 chain and pre-buffering frames the process can pass on data to output almost
8781 immediately after the target wallclock timestamp is reached.
8783 Perfect frame accuracy cannot be guaranteed, but the result is good enough for
8789 The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0.
8792 The duration of content to pass on as preroll expressed in seconds. Default is 0.
8795 The maximum duration of content to buffer before waiting for the cue expressed
8796 in seconds. Default is 0.
8803 Apply color adjustments using curves.
8805 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
8806 component (red, green and blue) has its values defined by @var{N} key points
8807 tied from each other using a smooth curve. The x-axis represents the pixel
8808 values from the input frame, and the y-axis the new pixel values to be set for
8811 By default, a component curve is defined by the two points @var{(0;0)} and
8812 @var{(1;1)}. This creates a straight line where each original pixel value is
8813 "adjusted" to its own value, which means no change to the image.
8815 The filter allows you to redefine these two points and add some more. A new
8816 curve (using a natural cubic spline interpolation) will be define to pass
8817 smoothly through all these new coordinates. The new defined points needs to be
8818 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
8819 be in the @var{[0;1]} interval. If the computed curves happened to go outside
8820 the vector spaces, the values will be clipped accordingly.
8822 The filter accepts the following options:
8826 Select one of the available color presets. This option can be used in addition
8827 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
8828 options takes priority on the preset values.
8829 Available presets are:
8832 @item color_negative
8835 @item increase_contrast
8837 @item linear_contrast
8838 @item medium_contrast
8840 @item strong_contrast
8843 Default is @code{none}.
8845 Set the master key points. These points will define a second pass mapping. It
8846 is sometimes called a "luminance" or "value" mapping. It can be used with
8847 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
8848 post-processing LUT.
8850 Set the key points for the red component.
8852 Set the key points for the green component.
8854 Set the key points for the blue component.
8856 Set the key points for all components (not including master).
8857 Can be used in addition to the other key points component
8858 options. In this case, the unset component(s) will fallback on this
8859 @option{all} setting.
8861 Specify a Photoshop curves file (@code{.acv}) to import the settings from.
8863 Save Gnuplot script of the curves in specified file.
8866 To avoid some filtergraph syntax conflicts, each key points list need to be
8867 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
8869 @subsection Examples
8873 Increase slightly the middle level of blue:
8875 curves=blue='0/0 0.5/0.58 1/1'
8881 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'
8883 Here we obtain the following coordinates for each components:
8886 @code{(0;0.11) (0.42;0.51) (1;0.95)}
8888 @code{(0;0) (0.50;0.48) (1;1)}
8890 @code{(0;0.22) (0.49;0.44) (1;0.80)}
8894 The previous example can also be achieved with the associated built-in preset:
8896 curves=preset=vintage
8906 Use a Photoshop preset and redefine the points of the green component:
8908 curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
8912 Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
8913 and @command{gnuplot}:
8915 ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
8916 gnuplot -p /tmp/curves.plt
8922 Video data analysis filter.
8924 This filter shows hexadecimal pixel values of part of video.
8926 The filter accepts the following options:
8930 Set output video size.
8933 Set x offset from where to pick pixels.
8936 Set y offset from where to pick pixels.
8939 Set scope mode, can be one of the following:
8942 Draw hexadecimal pixel values with white color on black background.
8945 Draw hexadecimal pixel values with input video pixel color on black
8949 Draw hexadecimal pixel values on color background picked from input video,
8950 the text color is picked in such way so its always visible.
8954 Draw rows and columns numbers on left and top of video.
8957 Set background opacity.
8960 Set display number format. Can be @code{hex}, or @code{dec}. Default is @code{hex}.
8964 Apply Directional blur filter.
8966 The filter accepts the following options:
8970 Set angle of directional blur. Default is @code{45}.
8973 Set radius of directional blur. Default is @code{5}.
8976 Set which planes to filter. By default all planes are filtered.
8979 @subsection Commands
8980 This filter supports same @ref{commands} as options.
8981 The command accepts the same syntax of the corresponding option.
8983 If the specified expression is not valid, it is kept at its current
8988 Denoise frames using 2D DCT (frequency domain filtering).
8990 This filter is not designed for real time.
8992 The filter accepts the following options:
8996 Set the noise sigma constant.
8998 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
8999 coefficient (absolute value) below this threshold with be dropped.
9001 If you need a more advanced filtering, see @option{expr}.
9003 Default is @code{0}.
9006 Set number overlapping pixels for each block. Since the filter can be slow, you
9007 may want to reduce this value, at the cost of a less effective filter and the
9008 risk of various artefacts.
9010 If the overlapping value doesn't permit processing the whole input width or
9011 height, a warning will be displayed and according borders won't be denoised.
9013 Default value is @var{blocksize}-1, which is the best possible setting.
9016 Set the coefficient factor expression.
9018 For each coefficient of a DCT block, this expression will be evaluated as a
9019 multiplier value for the coefficient.
9021 If this is option is set, the @option{sigma} option will be ignored.
9023 The absolute value of the coefficient can be accessed through the @var{c}
9027 Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
9028 @var{blocksize}, which is the width and height of the processed blocks.
9030 The default value is @var{3} (8x8) and can be raised to @var{4} for a
9031 @var{blocksize} of 16x16. Note that changing this setting has huge consequences
9032 on the speed processing. Also, a larger block size does not necessarily means a
9036 @subsection Examples
9038 Apply a denoise with a @option{sigma} of @code{4.5}:
9043 The same operation can be achieved using the expression system:
9045 dctdnoiz=e='gte(c, 4.5*3)'
9048 Violent denoise using a block size of @code{16x16}:
9055 Remove banding artifacts from input video.
9056 It works by replacing banded pixels with average value of referenced pixels.
9058 The filter accepts the following options:
9065 Set banding detection threshold for each plane. Default is 0.02.
9066 Valid range is 0.00003 to 0.5.
9067 If difference between current pixel and reference pixel is less than threshold,
9068 it will be considered as banded.
9071 Banding detection range in pixels. Default is 16. If positive, random number
9072 in range 0 to set value will be used. If negative, exact absolute value
9074 The range defines square of four pixels around current pixel.
9077 Set direction in radians from which four pixel will be compared. If positive,
9078 random direction from 0 to set direction will be picked. If negative, exact of
9079 absolute value will be picked. For example direction 0, -PI or -2*PI radians
9080 will pick only pixels on same row and -PI/2 will pick only pixels on same
9084 If enabled, current pixel is compared with average value of all four
9085 surrounding pixels. The default is enabled. If disabled current pixel is
9086 compared with all four surrounding pixels. The pixel is considered banded
9087 if only all four differences with surrounding pixels are less than threshold.
9090 If enabled, current pixel is changed if and only if all pixel components are banded,
9091 e.g. banding detection threshold is triggered for all color components.
9092 The default is disabled.
9097 Remove blocking artifacts from input video.
9099 The filter accepts the following options:
9103 Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}.
9104 This controls what kind of deblocking is applied.
9107 Set size of block, allowed range is from 4 to 512. Default is @var{8}.
9113 Set blocking detection thresholds. Allowed range is 0 to 1.
9114 Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest.
9115 Using higher threshold gives more deblocking strength.
9116 Setting @var{alpha} controls threshold detection at exact edge of block.
9117 Remaining options controls threshold detection near the edge. Each one for
9118 below/above or left/right. Setting any of those to @var{0} disables
9122 Set planes to filter. Default is to filter all available planes.
9125 @subsection Examples
9129 Deblock using weak filter and block size of 4 pixels.
9131 deblock=filter=weak:block=4
9135 Deblock using strong filter, block size of 4 pixels and custom thresholds for
9136 deblocking more edges.
9138 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
9142 Similar as above, but filter only first plane.
9144 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
9148 Similar as above, but filter only second and third plane.
9150 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
9157 Drop duplicated frames at regular intervals.
9159 The filter accepts the following options:
9163 Set the number of frames from which one will be dropped. Setting this to
9164 @var{N} means one frame in every batch of @var{N} frames will be dropped.
9165 Default is @code{5}.
9168 Set the threshold for duplicate detection. If the difference metric for a frame
9169 is less than or equal to this value, then it is declared as duplicate. Default
9173 Set scene change threshold. Default is @code{15}.
9177 Set the size of the x and y-axis blocks used during metric calculations.
9178 Larger blocks give better noise suppression, but also give worse detection of
9179 small movements. Must be a power of two. Default is @code{32}.
9182 Mark main input as a pre-processed input and activate clean source input
9183 stream. This allows the input to be pre-processed with various filters to help
9184 the metrics calculation while keeping the frame selection lossless. When set to
9185 @code{1}, the first stream is for the pre-processed input, and the second
9186 stream is the clean source from where the kept frames are chosen. Default is
9190 Set whether or not chroma is considered in the metric calculations. Default is
9196 Apply 2D deconvolution of video stream in frequency domain using second stream
9199 The filter accepts the following options:
9203 Set which planes to process.
9206 Set which impulse video frames will be processed, can be @var{first}
9207 or @var{all}. Default is @var{all}.
9210 Set noise when doing divisions. Default is @var{0.0000001}. Useful when width
9211 and height are not same and not power of 2 or if stream prior to convolving
9215 The @code{deconvolve} filter also supports the @ref{framesync} options.
9219 Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video.
9221 It accepts the following options:
9225 Set mode of operation. Can be combination of @var{dotcrawl} for cross-luminance reduction and/or
9226 @var{rainbows} for cross-color reduction.
9229 Set spatial luma threshold. Lower values increases reduction of cross-luminance.
9232 Set tolerance for temporal luma. Higher values increases reduction of cross-luminance.
9235 Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color.
9238 Set temporal chroma threshold. Lower values increases reduction of cross-color.
9243 Apply deflate effect to the video.
9245 This filter replaces the pixel by the local(3x3) average by taking into account
9246 only values lower than the pixel.
9248 It accepts the following options:
9255 Limit the maximum change for each plane, default is 65535.
9256 If 0, plane will remain unchanged.
9259 @subsection Commands
9261 This filter supports the all above options as @ref{commands}.
9265 Remove temporal frame luminance variations.
9267 It accepts the following options:
9271 Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129.
9274 Set averaging mode to smooth temporal luminance variations.
9276 Available values are:
9301 Do not actually modify frame. Useful when one only wants metadata.
9306 Remove judder produced by partially interlaced telecined content.
9308 Judder can be introduced, for instance, by @ref{pullup} filter. If the original
9309 source was partially telecined content then the output of @code{pullup,dejudder}
9310 will have a variable frame rate. May change the recorded frame rate of the
9311 container. Aside from that change, this filter will not affect constant frame
9314 The option available in this filter is:
9318 Specify the length of the window over which the judder repeats.
9320 Accepts any integer greater than 1. Useful values are:
9324 If the original was telecined from 24 to 30 fps (Film to NTSC).
9327 If the original was telecined from 25 to 30 fps (PAL to NTSC).
9330 If a mixture of the two.
9333 The default is @samp{4}.
9338 Suppress a TV station logo by a simple interpolation of the surrounding
9339 pixels. Just set a rectangle covering the logo and watch it disappear
9340 (and sometimes something even uglier appear - your mileage may vary).
9342 It accepts the following parameters:
9347 Specify the top left corner coordinates of the logo. They must be
9352 Specify the width and height of the logo to clear. They must be
9356 Specify the thickness of the fuzzy edge of the rectangle (added to
9357 @var{w} and @var{h}). The default value is 1. This option is
9358 deprecated, setting higher values should no longer be necessary and
9362 When set to 1, a green rectangle is drawn on the screen to simplify
9363 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
9364 The default value is 0.
9366 The rectangle is drawn on the outermost pixels which will be (partly)
9367 replaced with interpolated values. The values of the next pixels
9368 immediately outside this rectangle in each direction will be used to
9369 compute the interpolated pixel values inside the rectangle.
9373 @subsection Examples
9377 Set a rectangle covering the area with top left corner coordinates 0,0
9378 and size 100x77, and a band of size 10:
9380 delogo=x=0:y=0:w=100:h=77:band=10
9388 Remove the rain in the input image/video by applying the derain methods based on
9389 convolutional neural networks. Supported models:
9393 Recurrent Squeeze-and-Excitation Context Aggregation Net (RESCAN).
9394 See @url{http://openaccess.thecvf.com/content_ECCV_2018/papers/Xia_Li_Recurrent_Squeeze-and-Excitation_Context_ECCV_2018_paper.pdf}.
9397 Training as well as model generation scripts are provided in
9398 the repository at @url{https://github.com/XueweiMeng/derain_filter.git}.
9400 Native model files (.model) can be generated from TensorFlow model
9401 files (.pb) by using tools/python/convert.py
9403 The filter accepts the following options:
9407 Specify which filter to use. This option accepts the following values:
9411 Derain filter. To conduct derain filter, you need to use a derain model.
9414 Dehaze filter. To conduct dehaze filter, you need to use a dehaze model.
9416 Default value is @samp{derain}.
9419 Specify which DNN backend to use for model loading and execution. This option accepts
9420 the following values:
9424 Native implementation of DNN loading and execution.
9427 TensorFlow backend. To enable this backend you
9428 need to install the TensorFlow for C library (see
9429 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
9430 @code{--enable-libtensorflow}
9432 Default value is @samp{native}.
9435 Set path to model file specifying network architecture and its parameters.
9436 Note that different backends use different file formats. TensorFlow and native
9437 backend can load files for only its format.
9440 It can also be finished with @ref{dnn_processing} filter.
9444 Attempt to fix small changes in horizontal and/or vertical shift. This
9445 filter helps remove camera shake from hand-holding a camera, bumping a
9446 tripod, moving on a vehicle, etc.
9448 The filter accepts the following options:
9456 Specify a rectangular area where to limit the search for motion
9458 If desired the search for motion vectors can be limited to a
9459 rectangular area of the frame defined by its top left corner, width
9460 and height. These parameters have the same meaning as the drawbox
9461 filter which can be used to visualise the position of the bounding
9464 This is useful when simultaneous movement of subjects within the frame
9465 might be confused for camera motion by the motion vector search.
9467 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
9468 then the full frame is used. This allows later options to be set
9469 without specifying the bounding box for the motion vector search.
9471 Default - search the whole frame.
9475 Specify the maximum extent of movement in x and y directions in the
9476 range 0-64 pixels. Default 16.
9479 Specify how to generate pixels to fill blanks at the edge of the
9480 frame. Available values are:
9483 Fill zeroes at blank locations
9485 Original image at blank locations
9487 Extruded edge value at blank locations
9489 Mirrored edge at blank locations
9491 Default value is @samp{mirror}.
9494 Specify the blocksize to use for motion search. Range 4-128 pixels,
9498 Specify the contrast threshold for blocks. Only blocks with more than
9499 the specified contrast (difference between darkest and lightest
9500 pixels) will be considered. Range 1-255, default 125.
9503 Specify the search strategy. Available values are:
9506 Set exhaustive search
9508 Set less exhaustive search.
9510 Default value is @samp{exhaustive}.
9513 If set then a detailed log of the motion search is written to the
9520 Remove unwanted contamination of foreground colors, caused by reflected color of
9521 greenscreen or bluescreen.
9523 This filter accepts the following options:
9527 Set what type of despill to use.
9530 Set how spillmap will be generated.
9533 Set how much to get rid of still remaining spill.
9536 Controls amount of red in spill area.
9539 Controls amount of green in spill area.
9540 Should be -1 for greenscreen.
9543 Controls amount of blue in spill area.
9544 Should be -1 for bluescreen.
9547 Controls brightness of spill area, preserving colors.
9550 Modify alpha from generated spillmap.
9553 @subsection Commands
9555 This filter supports the all above options as @ref{commands}.
9559 Apply an exact inverse of the telecine operation. It requires a predefined
9560 pattern specified using the pattern option which must be the same as that passed
9561 to the telecine filter.
9563 This filter accepts the following options:
9572 The default value is @code{top}.
9576 A string of numbers representing the pulldown pattern you wish to apply.
9577 The default value is @code{23}.
9580 A number representing position of the first frame with respect to the telecine
9581 pattern. This is to be used if the stream is cut. The default value is @code{0}.
9586 Apply dilation effect to the video.
9588 This filter replaces the pixel by the local(3x3) maximum.
9590 It accepts the following options:
9597 Limit the maximum change for each plane, default is 65535.
9598 If 0, plane will remain unchanged.
9601 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
9604 Flags to local 3x3 coordinates maps like this:
9611 @subsection Commands
9613 This filter supports the all above options as @ref{commands}.
9617 Displace pixels as indicated by second and third input stream.
9619 It takes three input streams and outputs one stream, the first input is the
9620 source, and second and third input are displacement maps.
9622 The second input specifies how much to displace pixels along the
9623 x-axis, while the third input specifies how much to displace pixels
9625 If one of displacement map streams terminates, last frame from that
9626 displacement map will be used.
9628 Note that once generated, displacements maps can be reused over and over again.
9630 A description of the accepted options follows.
9634 Set displace behavior for pixels that are out of range.
9636 Available values are:
9639 Missing pixels are replaced by black pixels.
9642 Adjacent pixels will spread out to replace missing pixels.
9645 Out of range pixels are wrapped so they point to pixels of other side.
9648 Out of range pixels will be replaced with mirrored pixels.
9650 Default is @samp{smear}.
9654 @subsection Examples
9658 Add ripple effect to rgb input of video size hd720:
9660 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
9664 Add wave effect to rgb input of video size hd720:
9666 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
9670 @anchor{dnn_processing}
9671 @section dnn_processing
9673 Do image processing with deep neural networks. It works together with another filter
9674 which converts the pixel format of the Frame to what the dnn network requires.
9676 The filter accepts the following options:
9680 Specify which DNN backend to use for model loading and execution. This option accepts
9681 the following values:
9685 Native implementation of DNN loading and execution.
9688 TensorFlow backend. To enable this backend you
9689 need to install the TensorFlow for C library (see
9690 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
9691 @code{--enable-libtensorflow}
9694 OpenVINO backend. To enable this backend you
9695 need to build and install the OpenVINO for C library (see
9696 @url{https://github.com/openvinotoolkit/openvino/blob/master/build-instruction.md}) and configure FFmpeg with
9697 @code{--enable-libopenvino} (--extra-cflags=-I... --extra-ldflags=-L... might
9698 be needed if the header files and libraries are not installed into system path)
9702 Default value is @samp{native}.
9705 Set path to model file specifying network architecture and its parameters.
9706 Note that different backends use different file formats. TensorFlow, OpenVINO and native
9707 backend can load files for only its format.
9709 Native model file (.model) can be generated from TensorFlow model file (.pb) by using tools/python/convert.py
9712 Set the input name of the dnn network.
9715 Set the output name of the dnn network.
9719 @subsection Examples
9723 Remove rain in rgb24 frame with can.pb (see @ref{derain} filter):
9725 ./ffmpeg -i rain.jpg -vf format=rgb24,dnn_processing=dnn_backend=tensorflow:model=can.pb:input=x:output=y derain.jpg
9729 Halve the pixel value of the frame with format gray32f:
9731 ffmpeg -i input.jpg -vf format=grayf32,dnn_processing=model=halve_gray_float.model:input=dnn_in:output=dnn_out:dnn_backend=native -y out.native.png
9735 Handle the Y channel with srcnn.pb (see @ref{sr} filter) for frame with yuv420p (planar YUV formats supported):
9737 ./ffmpeg -i 480p.jpg -vf format=yuv420p,scale=w=iw*2:h=ih*2,dnn_processing=dnn_backend=tensorflow:model=srcnn.pb:input=x:output=y -y srcnn.jpg
9741 Handle the Y channel with espcn.pb (see @ref{sr} filter), which changes frame size, for format yuv420p (planar YUV formats supported):
9743 ./ffmpeg -i 480p.jpg -vf format=yuv420p,dnn_processing=dnn_backend=tensorflow:model=espcn.pb:input=x:output=y -y tmp.espcn.jpg
9750 Draw a colored box on the input image.
9752 It accepts the following parameters:
9757 The expressions which specify the top left corner coordinates of the box. It defaults to 0.
9761 The expressions which specify the width and height of the box; if 0 they are interpreted as
9762 the input width and height. It defaults to 0.
9765 Specify the color of the box to write. For the general syntax of this option,
9766 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
9767 value @code{invert} is used, the box edge color is the same as the
9768 video with inverted luma.
9771 The expression which sets the thickness of the box edge.
9772 A value of @code{fill} will create a filled box. Default value is @code{3}.
9774 See below for the list of accepted constants.
9777 Applicable if the input has alpha. With value @code{1}, the pixels of the painted box
9778 will overwrite the video's color and alpha pixels.
9779 Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact.
9782 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
9783 following constants:
9787 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
9791 horizontal and vertical chroma subsample values. For example for the
9792 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9796 The input width and height.
9799 The input sample aspect ratio.
9803 The x and y offset coordinates where the box is drawn.
9807 The width and height of the drawn box.
9810 The thickness of the drawn box.
9812 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
9813 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
9817 @subsection Examples
9821 Draw a black box around the edge of the input image:
9827 Draw a box with color red and an opacity of 50%:
9829 drawbox=10:20:200:60:red@@0.5
9832 The previous example can be specified as:
9834 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
9838 Fill the box with pink color:
9840 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill
9844 Draw a 2-pixel red 2.40:1 mask:
9846 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
9850 @subsection Commands
9851 This filter supports same commands as options.
9852 The command accepts the same syntax of the corresponding option.
9854 If the specified expression is not valid, it is kept at its current
9859 Draw a graph using input video metadata.
9861 It accepts the following parameters:
9865 Set 1st frame metadata key from which metadata values will be used to draw a graph.
9868 Set 1st foreground color expression.
9871 Set 2nd frame metadata key from which metadata values will be used to draw a graph.
9874 Set 2nd foreground color expression.
9877 Set 3rd frame metadata key from which metadata values will be used to draw a graph.
9880 Set 3rd foreground color expression.
9883 Set 4th frame metadata key from which metadata values will be used to draw a graph.
9886 Set 4th foreground color expression.
9889 Set minimal value of metadata value.
9892 Set maximal value of metadata value.
9895 Set graph background color. Default is white.
9900 Available values for mode is:
9907 Default is @code{line}.
9912 Available values for slide is:
9915 Draw new frame when right border is reached.
9918 Replace old columns with new ones.
9921 Scroll from right to left.
9924 Scroll from left to right.
9927 Draw single picture.
9930 Default is @code{frame}.
9933 Set size of graph video. For the syntax of this option, check the
9934 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
9935 The default value is @code{900x256}.
9938 Set the output frame rate. Default value is @code{25}.
9940 The foreground color expressions can use the following variables:
9943 Minimal value of metadata value.
9946 Maximal value of metadata value.
9949 Current metadata key value.
9952 The color is defined as 0xAABBGGRR.
9955 Example using metadata from @ref{signalstats} filter:
9957 signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
9960 Example using metadata from @ref{ebur128} filter:
9962 ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
9967 Draw a grid on the input image.
9969 It accepts the following parameters:
9974 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
9978 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
9979 input width and height, respectively, minus @code{thickness}, so image gets
9980 framed. Default to 0.
9983 Specify the color of the grid. For the general syntax of this option,
9984 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
9985 value @code{invert} is used, the grid color is the same as the
9986 video with inverted luma.
9989 The expression which sets the thickness of the grid line. Default value is @code{1}.
9991 See below for the list of accepted constants.
9994 Applicable if the input has alpha. With @code{1} the pixels of the painted grid
9995 will overwrite the video's color and alpha pixels.
9996 Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact.
9999 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
10000 following constants:
10004 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
10008 horizontal and vertical chroma subsample values. For example for the
10009 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
10013 The input grid cell width and height.
10016 The input sample aspect ratio.
10020 The x and y coordinates of some point of grid intersection (meant to configure offset).
10024 The width and height of the drawn cell.
10027 The thickness of the drawn cell.
10029 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
10030 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
10034 @subsection Examples
10038 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
10040 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
10044 Draw a white 3x3 grid with an opacity of 50%:
10046 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
10050 @subsection Commands
10051 This filter supports same commands as options.
10052 The command accepts the same syntax of the corresponding option.
10054 If the specified expression is not valid, it is kept at its current
10060 Draw a text string or text from a specified file on top of a video, using the
10061 libfreetype library.
10063 To enable compilation of this filter, you need to configure FFmpeg with
10064 @code{--enable-libfreetype}.
10065 To enable default font fallback and the @var{font} option you need to
10066 configure FFmpeg with @code{--enable-libfontconfig}.
10067 To enable the @var{text_shaping} option, you need to configure FFmpeg with
10068 @code{--enable-libfribidi}.
10072 It accepts the following parameters:
10077 Used to draw a box around text using the background color.
10078 The value must be either 1 (enable) or 0 (disable).
10079 The default value of @var{box} is 0.
10082 Set the width of the border to be drawn around the box using @var{boxcolor}.
10083 The default value of @var{boxborderw} is 0.
10086 The color to be used for drawing box around text. For the syntax of this
10087 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
10089 The default value of @var{boxcolor} is "white".
10092 Set the line spacing in pixels of the border to be drawn around the box using @var{box}.
10093 The default value of @var{line_spacing} is 0.
10096 Set the width of the border to be drawn around the text using @var{bordercolor}.
10097 The default value of @var{borderw} is 0.
10100 Set the color to be used for drawing border around text. For the syntax of this
10101 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
10103 The default value of @var{bordercolor} is "black".
10106 Select how the @var{text} is expanded. Can be either @code{none},
10107 @code{strftime} (deprecated) or
10108 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
10112 Set a start time for the count. Value is in microseconds. Only applied
10113 in the deprecated strftime expansion mode. To emulate in normal expansion
10114 mode use the @code{pts} function, supplying the start time (in seconds)
10115 as the second argument.
10118 If true, check and fix text coords to avoid clipping.
10121 The color to be used for drawing fonts. For the syntax of this option, check
10122 the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
10124 The default value of @var{fontcolor} is "black".
10126 @item fontcolor_expr
10127 String which is expanded the same way as @var{text} to obtain dynamic
10128 @var{fontcolor} value. By default this option has empty value and is not
10129 processed. When this option is set, it overrides @var{fontcolor} option.
10132 The font family to be used for drawing text. By default Sans.
10135 The font file to be used for drawing text. The path must be included.
10136 This parameter is mandatory if the fontconfig support is disabled.
10139 Draw the text applying alpha blending. The value can
10140 be a number between 0.0 and 1.0.
10141 The expression accepts the same variables @var{x, y} as well.
10142 The default value is 1.
10143 Please see @var{fontcolor_expr}.
10146 The font size to be used for drawing text.
10147 The default value of @var{fontsize} is 16.
10150 If set to 1, attempt to shape the text (for example, reverse the order of
10151 right-to-left text and join Arabic characters) before drawing it.
10152 Otherwise, just draw the text exactly as given.
10153 By default 1 (if supported).
10155 @item ft_load_flags
10156 The flags to be used for loading the fonts.
10158 The flags map the corresponding flags supported by libfreetype, and are
10159 a combination of the following values:
10166 @item vertical_layout
10167 @item force_autohint
10170 @item ignore_global_advance_width
10172 @item ignore_transform
10174 @item linear_design
10178 Default value is "default".
10180 For more information consult the documentation for the FT_LOAD_*
10184 The color to be used for drawing a shadow behind the drawn text. For the
10185 syntax of this option, check the @ref{color syntax,,"Color" section in the
10186 ffmpeg-utils manual,ffmpeg-utils}.
10188 The default value of @var{shadowcolor} is "black".
10192 The x and y offsets for the text shadow position with respect to the
10193 position of the text. They can be either positive or negative
10194 values. The default value for both is "0".
10197 The starting frame number for the n/frame_num variable. The default value
10201 The size in number of spaces to use for rendering the tab.
10202 Default value is 4.
10205 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
10206 format. It can be used with or without text parameter. @var{timecode_rate}
10207 option must be specified.
10209 @item timecode_rate, rate, r
10210 Set the timecode frame rate (timecode only). Value will be rounded to nearest
10211 integer. Minimum value is "1".
10212 Drop-frame timecode is supported for frame rates 30 & 60.
10215 If set to 1, the output of the timecode option will wrap around at 24 hours.
10216 Default is 0 (disabled).
10219 The text string to be drawn. The text must be a sequence of UTF-8
10220 encoded characters.
10221 This parameter is mandatory if no file is specified with the parameter
10225 A text file containing text to be drawn. The text must be a sequence
10226 of UTF-8 encoded characters.
10228 This parameter is mandatory if no text string is specified with the
10229 parameter @var{text}.
10231 If both @var{text} and @var{textfile} are specified, an error is thrown.
10234 If set to 1, the @var{textfile} will be reloaded before each frame.
10235 Be sure to update it atomically, or it may be read partially, or even fail.
10239 The expressions which specify the offsets where text will be drawn
10240 within the video frame. They are relative to the top/left border of the
10243 The default value of @var{x} and @var{y} is "0".
10245 See below for the list of accepted constants and functions.
10248 The parameters for @var{x} and @var{y} are expressions containing the
10249 following constants and functions:
10253 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
10257 horizontal and vertical chroma subsample values. For example for the
10258 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
10261 the height of each text line
10269 @item max_glyph_a, ascent
10270 the maximum distance from the baseline to the highest/upper grid
10271 coordinate used to place a glyph outline point, for all the rendered
10273 It is a positive value, due to the grid's orientation with the Y axis
10276 @item max_glyph_d, descent
10277 the maximum distance from the baseline to the lowest grid coordinate
10278 used to place a glyph outline point, for all the rendered glyphs.
10279 This is a negative value, due to the grid's orientation, with the Y axis
10283 maximum glyph height, that is the maximum height for all the glyphs
10284 contained in the rendered text, it is equivalent to @var{ascent} -
10288 maximum glyph width, that is the maximum width for all the glyphs
10289 contained in the rendered text
10292 the number of input frame, starting from 0
10294 @item rand(min, max)
10295 return a random number included between @var{min} and @var{max}
10298 The input sample aspect ratio.
10301 timestamp expressed in seconds, NAN if the input timestamp is unknown
10304 the height of the rendered text
10307 the width of the rendered text
10311 the x and y offset coordinates where the text is drawn.
10313 These parameters allow the @var{x} and @var{y} expressions to refer
10314 to each other, so you can for example specify @code{y=x/dar}.
10317 A one character description of the current frame's picture type.
10320 The current packet's position in the input file or stream
10321 (in bytes, from the start of the input). A value of -1 indicates
10322 this info is not available.
10325 The current packet's duration, in seconds.
10328 The current packet's size (in bytes).
10331 @anchor{drawtext_expansion}
10332 @subsection Text expansion
10334 If @option{expansion} is set to @code{strftime},
10335 the filter recognizes strftime() sequences in the provided text and
10336 expands them accordingly. Check the documentation of strftime(). This
10337 feature is deprecated.
10339 If @option{expansion} is set to @code{none}, the text is printed verbatim.
10341 If @option{expansion} is set to @code{normal} (which is the default),
10342 the following expansion mechanism is used.
10344 The backslash character @samp{\}, followed by any character, always expands to
10345 the second character.
10347 Sequences of the form @code{%@{...@}} are expanded. The text between the
10348 braces is a function name, possibly followed by arguments separated by ':'.
10349 If the arguments contain special characters or delimiters (':' or '@}'),
10350 they should be escaped.
10352 Note that they probably must also be escaped as the value for the
10353 @option{text} option in the filter argument string and as the filter
10354 argument in the filtergraph description, and possibly also for the shell,
10355 that makes up to four levels of escaping; using a text file avoids these
10358 The following functions are available:
10363 The expression evaluation result.
10365 It must take one argument specifying the expression to be evaluated,
10366 which accepts the same constants and functions as the @var{x} and
10367 @var{y} values. Note that not all constants should be used, for
10368 example the text size is not known when evaluating the expression, so
10369 the constants @var{text_w} and @var{text_h} will have an undefined
10372 @item expr_int_format, eif
10373 Evaluate the expression's value and output as formatted integer.
10375 The first argument is the expression to be evaluated, just as for the @var{expr} function.
10376 The second argument specifies the output format. Allowed values are @samp{x},
10377 @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
10378 @code{printf} function.
10379 The third parameter is optional and sets the number of positions taken by the output.
10380 It can be used to add padding with zeros from the left.
10383 The time at which the filter is running, expressed in UTC.
10384 It can accept an argument: a strftime() format string.
10387 The time at which the filter is running, expressed in the local time zone.
10388 It can accept an argument: a strftime() format string.
10391 Frame metadata. Takes one or two arguments.
10393 The first argument is mandatory and specifies the metadata key.
10395 The second argument is optional and specifies a default value, used when the
10396 metadata key is not found or empty.
10398 Available metadata can be identified by inspecting entries
10399 starting with TAG included within each frame section
10400 printed by running @code{ffprobe -show_frames}.
10402 String metadata generated in filters leading to
10403 the drawtext filter are also available.
10406 The frame number, starting from 0.
10409 A one character description of the current picture type.
10412 The timestamp of the current frame.
10413 It can take up to three arguments.
10415 The first argument is the format of the timestamp; it defaults to @code{flt}
10416 for seconds as a decimal number with microsecond accuracy; @code{hms} stands
10417 for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
10418 @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
10419 @code{localtime} stands for the timestamp of the frame formatted as
10420 local time zone time.
10422 The second argument is an offset added to the timestamp.
10424 If the format is set to @code{hms}, a third argument @code{24HH} may be
10425 supplied to present the hour part of the formatted timestamp in 24h format
10428 If the format is set to @code{localtime} or @code{gmtime},
10429 a third argument may be supplied: a strftime() format string.
10430 By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
10433 @subsection Commands
10435 This filter supports altering parameters via commands:
10438 Alter existing filter parameters.
10440 Syntax for the argument is the same as for filter invocation, e.g.
10443 fontsize=56:fontcolor=green:text='Hello World'
10446 Full filter invocation with sendcmd would look like this:
10449 sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World'
10453 If the entire argument can't be parsed or applied as valid values then the filter will
10454 continue with its existing parameters.
10456 @subsection Examples
10460 Draw "Test Text" with font FreeSerif, using the default values for the
10461 optional parameters.
10464 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
10468 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
10469 and y=50 (counting from the top-left corner of the screen), text is
10470 yellow with a red box around it. Both the text and the box have an
10474 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
10475 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
10478 Note that the double quotes are not necessary if spaces are not used
10479 within the parameter list.
10482 Show the text at the center of the video frame:
10484 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
10488 Show the text at a random position, switching to a new position every 30 seconds:
10490 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)"
10494 Show a text line sliding from right to left in the last row of the video
10495 frame. The file @file{LONG_LINE} is assumed to contain a single line
10498 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
10502 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
10504 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
10508 Draw a single green letter "g", at the center of the input video.
10509 The glyph baseline is placed at half screen height.
10511 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
10515 Show text for 1 second every 3 seconds:
10517 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
10521 Use fontconfig to set the font. Note that the colons need to be escaped.
10523 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
10527 Draw "Test Text" with font size dependent on height of the video.
10529 drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)"
10533 Print the date of a real-time encoding (see strftime(3)):
10535 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
10539 Show text fading in and out (appearing/disappearing):
10542 DS=1.0 # display start
10543 DE=10.0 # display end
10544 FID=1.5 # fade in duration
10545 FOD=5 # fade out duration
10546 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 @}"
10550 Horizontally align multiple separate texts. Note that @option{max_glyph_a}
10551 and the @option{fontsize} value are included in the @option{y} offset.
10553 drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
10554 drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
10558 Plot special @var{lavf.image2dec.source_basename} metadata onto each frame if
10559 such metadata exists. Otherwise, plot the string "NA". Note that image2 demuxer
10560 must have option @option{-export_path_metadata 1} for the special metadata fields
10561 to be available for filters.
10563 drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%@{metadata\:lavf.image2dec.source_basename\:NA@}':x=10:y=10"
10568 For more information about libfreetype, check:
10569 @url{http://www.freetype.org/}.
10571 For more information about fontconfig, check:
10572 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
10574 For more information about libfribidi, check:
10575 @url{http://fribidi.org/}.
10577 @section edgedetect
10579 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
10581 The filter accepts the following options:
10586 Set low and high threshold values used by the Canny thresholding
10589 The high threshold selects the "strong" edge pixels, which are then
10590 connected through 8-connectivity with the "weak" edge pixels selected
10591 by the low threshold.
10593 @var{low} and @var{high} threshold values must be chosen in the range
10594 [0,1], and @var{low} should be lesser or equal to @var{high}.
10596 Default value for @var{low} is @code{20/255}, and default value for @var{high}
10600 Define the drawing mode.
10604 Draw white/gray wires on black background.
10607 Mix the colors to create a paint/cartoon effect.
10610 Apply Canny edge detector on all selected planes.
10612 Default value is @var{wires}.
10615 Select planes for filtering. By default all available planes are filtered.
10618 @subsection Examples
10622 Standard edge detection with custom values for the hysteresis thresholding:
10624 edgedetect=low=0.1:high=0.4
10628 Painting effect without thresholding:
10630 edgedetect=mode=colormix:high=0
10636 Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
10638 For each input image, the filter will compute the optimal mapping from
10639 the input to the output given the codebook length, that is the number
10640 of distinct output colors.
10642 This filter accepts the following options.
10645 @item codebook_length, l
10646 Set codebook length. The value must be a positive integer, and
10647 represents the number of distinct output colors. Default value is 256.
10650 Set the maximum number of iterations to apply for computing the optimal
10651 mapping. The higher the value the better the result and the higher the
10652 computation time. Default value is 1.
10655 Set a random seed, must be an integer included between 0 and
10656 UINT32_MAX. If not specified, or if explicitly set to -1, the filter
10657 will try to use a good random seed on a best effort basis.
10660 Set pal8 output pixel format. This option does not work with codebook
10661 length greater than 256.
10666 Measure graylevel entropy in histogram of color channels of video frames.
10668 It accepts the following parameters:
10672 Can be either @var{normal} or @var{diff}. Default is @var{normal}.
10674 @var{diff} mode measures entropy of histogram delta values, absolute differences
10675 between neighbour histogram values.
10679 Set brightness, contrast, saturation and approximate gamma adjustment.
10681 The filter accepts the following options:
10685 Set the contrast expression. The value must be a float value in range
10686 @code{-1000.0} to @code{1000.0}. The default value is "1".
10689 Set the brightness expression. The value must be a float value in
10690 range @code{-1.0} to @code{1.0}. The default value is "0".
10693 Set the saturation expression. The value must be a float in
10694 range @code{0.0} to @code{3.0}. The default value is "1".
10697 Set the gamma expression. The value must be a float in range
10698 @code{0.1} to @code{10.0}. The default value is "1".
10701 Set the gamma expression for red. The value must be a float in
10702 range @code{0.1} to @code{10.0}. The default value is "1".
10705 Set the gamma expression for green. The value must be a float in range
10706 @code{0.1} to @code{10.0}. The default value is "1".
10709 Set the gamma expression for blue. The value must be a float in range
10710 @code{0.1} to @code{10.0}. The default value is "1".
10713 Set the gamma weight expression. It can be used to reduce the effect
10714 of a high gamma value on bright image areas, e.g. keep them from
10715 getting overamplified and just plain white. The value must be a float
10716 in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
10717 gamma correction all the way down while @code{1.0} leaves it at its
10718 full strength. Default is "1".
10721 Set when the expressions for brightness, contrast, saturation and
10722 gamma expressions are evaluated.
10724 It accepts the following values:
10727 only evaluate expressions once during the filter initialization or
10728 when a command is processed
10731 evaluate expressions for each incoming frame
10734 Default value is @samp{init}.
10737 The expressions accept the following parameters:
10740 frame count of the input frame starting from 0
10743 byte position of the corresponding packet in the input file, NAN if
10747 frame rate of the input video, NAN if the input frame rate is unknown
10750 timestamp expressed in seconds, NAN if the input timestamp is unknown
10753 @subsection Commands
10754 The filter supports the following commands:
10758 Set the contrast expression.
10761 Set the brightness expression.
10764 Set the saturation expression.
10767 Set the gamma expression.
10770 Set the gamma_r expression.
10773 Set gamma_g expression.
10776 Set gamma_b expression.
10779 Set gamma_weight expression.
10781 The command accepts the same syntax of the corresponding option.
10783 If the specified expression is not valid, it is kept at its current
10790 Apply erosion effect to the video.
10792 This filter replaces the pixel by the local(3x3) minimum.
10794 It accepts the following options:
10801 Limit the maximum change for each plane, default is 65535.
10802 If 0, plane will remain unchanged.
10805 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
10808 Flags to local 3x3 coordinates maps like this:
10815 @subsection Commands
10817 This filter supports the all above options as @ref{commands}.
10819 @section extractplanes
10821 Extract color channel components from input video stream into
10822 separate grayscale video streams.
10824 The filter accepts the following option:
10828 Set plane(s) to extract.
10830 Available values for planes are:
10841 Choosing planes not available in the input will result in an error.
10842 That means you cannot select @code{r}, @code{g}, @code{b} planes
10843 with @code{y}, @code{u}, @code{v} planes at same time.
10846 @subsection Examples
10850 Extract luma, u and v color channel component from input video frame
10851 into 3 grayscale outputs:
10853 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
10859 Apply a fade-in/out effect to the input video.
10861 It accepts the following parameters:
10865 The effect type can be either "in" for a fade-in, or "out" for a fade-out
10867 Default is @code{in}.
10869 @item start_frame, s
10870 Specify the number of the frame to start applying the fade
10871 effect at. Default is 0.
10874 The number of frames that the fade effect lasts. At the end of the
10875 fade-in effect, the output video will have the same intensity as the input video.
10876 At the end of the fade-out transition, the output video will be filled with the
10877 selected @option{color}.
10881 If set to 1, fade only alpha channel, if one exists on the input.
10882 Default value is 0.
10884 @item start_time, st
10885 Specify the timestamp (in seconds) of the frame to start to apply the fade
10886 effect. If both start_frame and start_time are specified, the fade will start at
10887 whichever comes last. Default is 0.
10890 The number of seconds for which the fade effect has to last. At the end of the
10891 fade-in effect the output video will have the same intensity as the input video,
10892 at the end of the fade-out transition the output video will be filled with the
10893 selected @option{color}.
10894 If both duration and nb_frames are specified, duration is used. Default is 0
10895 (nb_frames is used by default).
10898 Specify the color of the fade. Default is "black".
10901 @subsection Examples
10905 Fade in the first 30 frames of video:
10910 The command above is equivalent to:
10916 Fade out the last 45 frames of a 200-frame video:
10919 fade=type=out:start_frame=155:nb_frames=45
10923 Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
10925 fade=in:0:25, fade=out:975:25
10929 Make the first 5 frames yellow, then fade in from frame 5-24:
10931 fade=in:5:20:color=yellow
10935 Fade in alpha over first 25 frames of video:
10937 fade=in:0:25:alpha=1
10941 Make the first 5.5 seconds black, then fade in for 0.5 seconds:
10943 fade=t=in:st=5.5:d=0.5
10949 Denoise frames using 3D FFT (frequency domain filtering).
10951 The filter accepts the following options:
10955 Set the noise sigma constant. This sets denoising strength.
10956 Default value is 1. Allowed range is from 0 to 30.
10957 Using very high sigma with low overlap may give blocking artifacts.
10960 Set amount of denoising. By default all detected noise is reduced.
10961 Default value is 1. Allowed range is from 0 to 1.
10964 Set size of block, Default is 4, can be 3, 4, 5 or 6.
10965 Actual size of block in pixels is 2 to power of @var{block}, so by default
10966 block size in pixels is 2^4 which is 16.
10969 Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8.
10972 Set number of previous frames to use for denoising. By default is set to 0.
10975 Set number of next frames to to use for denoising. By default is set to 0.
10978 Set planes which will be filtered, by default are all available filtered
10983 Apply arbitrary expressions to samples in frequency domain
10987 Adjust the dc value (gain) of the luma plane of the image. The filter
10988 accepts an integer value in range @code{0} to @code{1000}. The default
10989 value is set to @code{0}.
10992 Adjust the dc value (gain) of the 1st chroma plane of the image. The
10993 filter accepts an integer value in range @code{0} to @code{1000}. The
10994 default value is set to @code{0}.
10997 Adjust the dc value (gain) of the 2nd chroma plane of the image. The
10998 filter accepts an integer value in range @code{0} to @code{1000}. The
10999 default value is set to @code{0}.
11002 Set the frequency domain weight expression for the luma plane.
11005 Set the frequency domain weight expression for the 1st chroma plane.
11008 Set the frequency domain weight expression for the 2nd chroma plane.
11011 Set when the expressions are evaluated.
11013 It accepts the following values:
11016 Only evaluate expressions once during the filter initialization.
11019 Evaluate expressions for each incoming frame.
11022 Default value is @samp{init}.
11024 The filter accepts the following variables:
11027 The coordinates of the current sample.
11031 The width and height of the image.
11034 The number of input frame, starting from 0.
11037 @subsection Examples
11043 fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
11049 fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
11055 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
11061 fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
11068 Extract a single field from an interlaced image using stride
11069 arithmetic to avoid wasting CPU time. The output frames are marked as
11072 The filter accepts the following options:
11076 Specify whether to extract the top (if the value is @code{0} or
11077 @code{top}) or the bottom field (if the value is @code{1} or
11083 Create new frames by copying the top and bottom fields from surrounding frames
11084 supplied as numbers by the hint file.
11088 Set file containing hints: absolute/relative frame numbers.
11090 There must be one line for each frame in a clip. Each line must contain two
11091 numbers separated by the comma, optionally followed by @code{-} or @code{+}.
11092 Numbers supplied on each line of file can not be out of [N-1,N+1] where N
11093 is current frame number for @code{absolute} mode or out of [-1, 1] range
11094 for @code{relative} mode. First number tells from which frame to pick up top
11095 field and second number tells from which frame to pick up bottom field.
11097 If optionally followed by @code{+} output frame will be marked as interlaced,
11098 else if followed by @code{-} output frame will be marked as progressive, else
11099 it will be marked same as input frame.
11100 If optionally followed by @code{t} output frame will use only top field, or in
11101 case of @code{b} it will use only bottom field.
11102 If line starts with @code{#} or @code{;} that line is skipped.
11105 Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
11108 Example of first several lines of @code{hint} file for @code{relative} mode:
11110 0,0 - # first frame
11111 1,0 - # second frame, use third's frame top field and second's frame bottom field
11112 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
11127 @section fieldmatch
11129 Field matching filter for inverse telecine. It is meant to reconstruct the
11130 progressive frames from a telecined stream. The filter does not drop duplicated
11131 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
11132 followed by a decimation filter such as @ref{decimate} in the filtergraph.
11134 The separation of the field matching and the decimation is notably motivated by
11135 the possibility of inserting a de-interlacing filter fallback between the two.
11136 If the source has mixed telecined and real interlaced content,
11137 @code{fieldmatch} will not be able to match fields for the interlaced parts.
11138 But these remaining combed frames will be marked as interlaced, and thus can be
11139 de-interlaced by a later filter such as @ref{yadif} before decimation.
11141 In addition to the various configuration options, @code{fieldmatch} can take an
11142 optional second stream, activated through the @option{ppsrc} option. If
11143 enabled, the frames reconstruction will be based on the fields and frames from
11144 this second stream. This allows the first input to be pre-processed in order to
11145 help the various algorithms of the filter, while keeping the output lossless
11146 (assuming the fields are matched properly). Typically, a field-aware denoiser,
11147 or brightness/contrast adjustments can help.
11149 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
11150 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
11151 which @code{fieldmatch} is based on. While the semantic and usage are very
11152 close, some behaviour and options names can differ.
11154 The @ref{decimate} filter currently only works for constant frame rate input.
11155 If your input has mixed telecined (30fps) and progressive content with a lower
11156 framerate like 24fps use the following filterchain to produce the necessary cfr
11157 stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
11159 The filter accepts the following options:
11163 Specify the assumed field order of the input stream. Available values are:
11167 Auto detect parity (use FFmpeg's internal parity value).
11169 Assume bottom field first.
11171 Assume top field first.
11174 Note that it is sometimes recommended not to trust the parity announced by the
11177 Default value is @var{auto}.
11180 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
11181 sense that it won't risk creating jerkiness due to duplicate frames when
11182 possible, but if there are bad edits or blended fields it will end up
11183 outputting combed frames when a good match might actually exist. On the other
11184 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
11185 but will almost always find a good frame if there is one. The other values are
11186 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
11187 jerkiness and creating duplicate frames versus finding good matches in sections
11188 with bad edits, orphaned fields, blended fields, etc.
11190 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
11192 Available values are:
11196 2-way matching (p/c)
11198 2-way matching, and trying 3rd match if still combed (p/c + n)
11200 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
11202 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
11203 still combed (p/c + n + u/b)
11205 3-way matching (p/c/n)
11207 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
11208 detected as combed (p/c/n + u/b)
11211 The parenthesis at the end indicate the matches that would be used for that
11212 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
11215 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
11218 Default value is @var{pc_n}.
11221 Mark the main input stream as a pre-processed input, and enable the secondary
11222 input stream as the clean source to pick the fields from. See the filter
11223 introduction for more details. It is similar to the @option{clip2} feature from
11226 Default value is @code{0} (disabled).
11229 Set the field to match from. It is recommended to set this to the same value as
11230 @option{order} unless you experience matching failures with that setting. In
11231 certain circumstances changing the field that is used to match from can have a
11232 large impact on matching performance. Available values are:
11236 Automatic (same value as @option{order}).
11238 Match from the bottom field.
11240 Match from the top field.
11243 Default value is @var{auto}.
11246 Set whether or not chroma is included during the match comparisons. In most
11247 cases it is recommended to leave this enabled. You should set this to @code{0}
11248 only if your clip has bad chroma problems such as heavy rainbowing or other
11249 artifacts. Setting this to @code{0} could also be used to speed things up at
11250 the cost of some accuracy.
11252 Default value is @code{1}.
11256 These define an exclusion band which excludes the lines between @option{y0} and
11257 @option{y1} from being included in the field matching decision. An exclusion
11258 band can be used to ignore subtitles, a logo, or other things that may
11259 interfere with the matching. @option{y0} sets the starting scan line and
11260 @option{y1} sets the ending line; all lines in between @option{y0} and
11261 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
11262 @option{y0} and @option{y1} to the same value will disable the feature.
11263 @option{y0} and @option{y1} defaults to @code{0}.
11266 Set the scene change detection threshold as a percentage of maximum change on
11267 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
11268 detection is only relevant in case @option{combmatch}=@var{sc}. The range for
11269 @option{scthresh} is @code{[0.0, 100.0]}.
11271 Default value is @code{12.0}.
11274 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
11275 account the combed scores of matches when deciding what match to use as the
11276 final match. Available values are:
11280 No final matching based on combed scores.
11282 Combed scores are only used when a scene change is detected.
11284 Use combed scores all the time.
11287 Default is @var{sc}.
11290 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
11291 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
11292 Available values are:
11296 No forced calculation.
11298 Force p/c/n calculations.
11300 Force p/c/n/u/b calculations.
11303 Default value is @var{none}.
11306 This is the area combing threshold used for combed frame detection. This
11307 essentially controls how "strong" or "visible" combing must be to be detected.
11308 Larger values mean combing must be more visible and smaller values mean combing
11309 can be less visible or strong and still be detected. Valid settings are from
11310 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
11311 be detected as combed). This is basically a pixel difference value. A good
11312 range is @code{[8, 12]}.
11314 Default value is @code{9}.
11317 Sets whether or not chroma is considered in the combed frame decision. Only
11318 disable this if your source has chroma problems (rainbowing, etc.) that are
11319 causing problems for the combed frame detection with chroma enabled. Actually,
11320 using @option{chroma}=@var{0} is usually more reliable, except for the case
11321 where there is chroma only combing in the source.
11323 Default value is @code{0}.
11327 Respectively set the x-axis and y-axis size of the window used during combed
11328 frame detection. This has to do with the size of the area in which
11329 @option{combpel} pixels are required to be detected as combed for a frame to be
11330 declared combed. See the @option{combpel} parameter description for more info.
11331 Possible values are any number that is a power of 2 starting at 4 and going up
11334 Default value is @code{16}.
11337 The number of combed pixels inside any of the @option{blocky} by
11338 @option{blockx} size blocks on the frame for the frame to be detected as
11339 combed. While @option{cthresh} controls how "visible" the combing must be, this
11340 setting controls "how much" combing there must be in any localized area (a
11341 window defined by the @option{blockx} and @option{blocky} settings) on the
11342 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
11343 which point no frames will ever be detected as combed). This setting is known
11344 as @option{MI} in TFM/VFM vocabulary.
11346 Default value is @code{80}.
11349 @anchor{p/c/n/u/b meaning}
11350 @subsection p/c/n/u/b meaning
11352 @subsubsection p/c/n
11354 We assume the following telecined stream:
11357 Top fields: 1 2 2 3 4
11358 Bottom fields: 1 2 3 4 4
11361 The numbers correspond to the progressive frame the fields relate to. Here, the
11362 first two frames are progressive, the 3rd and 4th are combed, and so on.
11364 When @code{fieldmatch} is configured to run a matching from bottom
11365 (@option{field}=@var{bottom}) this is how this input stream get transformed:
11370 B 1 2 3 4 4 <-- matching reference
11379 As a result of the field matching, we can see that some frames get duplicated.
11380 To perform a complete inverse telecine, you need to rely on a decimation filter
11381 after this operation. See for instance the @ref{decimate} filter.
11383 The same operation now matching from top fields (@option{field}=@var{top})
11388 T 1 2 2 3 4 <-- matching reference
11398 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
11399 basically, they refer to the frame and field of the opposite parity:
11402 @item @var{p} matches the field of the opposite parity in the previous frame
11403 @item @var{c} matches the field of the opposite parity in the current frame
11404 @item @var{n} matches the field of the opposite parity in the next frame
11409 The @var{u} and @var{b} matching are a bit special in the sense that they match
11410 from the opposite parity flag. In the following examples, we assume that we are
11411 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
11412 'x' is placed above and below each matched fields.
11414 With bottom matching (@option{field}=@var{bottom}):
11419 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
11420 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
11428 With top matching (@option{field}=@var{top}):
11433 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
11434 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
11442 @subsection Examples
11444 Simple IVTC of a top field first telecined stream:
11446 fieldmatch=order=tff:combmatch=none, decimate
11449 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
11451 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
11454 @section fieldorder
11456 Transform the field order of the input video.
11458 It accepts the following parameters:
11463 The output field order. Valid values are @var{tff} for top field first or @var{bff}
11464 for bottom field first.
11467 The default value is @samp{tff}.
11469 The transformation is done by shifting the picture content up or down
11470 by one line, and filling the remaining line with appropriate picture content.
11471 This method is consistent with most broadcast field order converters.
11473 If the input video is not flagged as being interlaced, or it is already
11474 flagged as being of the required output field order, then this filter does
11475 not alter the incoming video.
11477 It is very useful when converting to or from PAL DV material,
11478 which is bottom field first.
11482 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
11485 @section fifo, afifo
11487 Buffer input images and send them when they are requested.
11489 It is mainly useful when auto-inserted by the libavfilter
11492 It does not take parameters.
11494 @section fillborders
11496 Fill borders of the input video, without changing video stream dimensions.
11497 Sometimes video can have garbage at the four edges and you may not want to
11498 crop video input to keep size multiple of some number.
11500 This filter accepts the following options:
11504 Number of pixels to fill from left border.
11507 Number of pixels to fill from right border.
11510 Number of pixels to fill from top border.
11513 Number of pixels to fill from bottom border.
11518 It accepts the following values:
11521 fill pixels using outermost pixels
11524 fill pixels using mirroring
11527 fill pixels with constant value
11530 Default is @var{smear}.
11533 Set color for pixels in fixed mode. Default is @var{black}.
11536 @subsection Commands
11537 This filter supports same @ref{commands} as options.
11538 The command accepts the same syntax of the corresponding option.
11540 If the specified expression is not valid, it is kept at its current
11545 Find a rectangular object
11547 It accepts the following options:
11551 Filepath of the object image, needs to be in gray8.
11554 Detection threshold, default is 0.5.
11557 Number of mipmaps, default is 3.
11559 @item xmin, ymin, xmax, ymax
11560 Specifies the rectangle in which to search.
11563 @subsection Examples
11567 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
11569 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
11575 Flood area with values of same pixel components with another values.
11577 It accepts the following options:
11580 Set pixel x coordinate.
11583 Set pixel y coordinate.
11586 Set source #0 component value.
11589 Set source #1 component value.
11592 Set source #2 component value.
11595 Set source #3 component value.
11598 Set destination #0 component value.
11601 Set destination #1 component value.
11604 Set destination #2 component value.
11607 Set destination #3 component value.
11613 Convert the input video to one of the specified pixel formats.
11614 Libavfilter will try to pick one that is suitable as input to
11617 It accepts the following parameters:
11621 A '|'-separated list of pixel format names, such as
11622 "pix_fmts=yuv420p|monow|rgb24".
11626 @subsection Examples
11630 Convert the input video to the @var{yuv420p} format
11632 format=pix_fmts=yuv420p
11635 Convert the input video to any of the formats in the list
11637 format=pix_fmts=yuv420p|yuv444p|yuv410p
11644 Convert the video to specified constant frame rate by duplicating or dropping
11645 frames as necessary.
11647 It accepts the following parameters:
11651 The desired output frame rate. The default is @code{25}.
11654 Assume the first PTS should be the given value, in seconds. This allows for
11655 padding/trimming at the start of stream. By default, no assumption is made
11656 about the first frame's expected PTS, so no padding or trimming is done.
11657 For example, this could be set to 0 to pad the beginning with duplicates of
11658 the first frame if a video stream starts after the audio stream or to trim any
11659 frames with a negative PTS.
11662 Timestamp (PTS) rounding method.
11664 Possible values are:
11671 round towards -infinity
11673 round towards +infinity
11677 The default is @code{near}.
11680 Action performed when reading the last frame.
11682 Possible values are:
11685 Use same timestamp rounding method as used for other frames.
11687 Pass through last frame if input duration has not been reached yet.
11689 The default is @code{round}.
11693 Alternatively, the options can be specified as a flat string:
11694 @var{fps}[:@var{start_time}[:@var{round}]].
11696 See also the @ref{setpts} filter.
11698 @subsection Examples
11702 A typical usage in order to set the fps to 25:
11708 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
11710 fps=fps=film:round=near
11716 Pack two different video streams into a stereoscopic video, setting proper
11717 metadata on supported codecs. The two views should have the same size and
11718 framerate and processing will stop when the shorter video ends. Please note
11719 that you may conveniently adjust view properties with the @ref{scale} and
11722 It accepts the following parameters:
11726 The desired packing format. Supported values are:
11731 The views are next to each other (default).
11734 The views are on top of each other.
11737 The views are packed by line.
11740 The views are packed by column.
11743 The views are temporally interleaved.
11752 # Convert left and right views into a frame-sequential video
11753 ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
11755 # Convert views into a side-by-side video with the same output resolution as the input
11756 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
11761 Change the frame rate by interpolating new video output frames from the source
11764 This filter is not designed to function correctly with interlaced media. If
11765 you wish to change the frame rate of interlaced media then you are required
11766 to deinterlace before this filter and re-interlace after this filter.
11768 A description of the accepted options follows.
11772 Specify the output frames per second. This option can also be specified
11773 as a value alone. The default is @code{50}.
11776 Specify the start of a range where the output frame will be created as a
11777 linear interpolation of two frames. The range is [@code{0}-@code{255}],
11778 the default is @code{15}.
11781 Specify the end of a range where the output frame will be created as a
11782 linear interpolation of two frames. The range is [@code{0}-@code{255}],
11783 the default is @code{240}.
11786 Specify the level at which a scene change is detected as a value between
11787 0 and 100 to indicate a new scene; a low value reflects a low
11788 probability for the current frame to introduce a new scene, while a higher
11789 value means the current frame is more likely to be one.
11790 The default is @code{8.2}.
11793 Specify flags influencing the filter process.
11795 Available value for @var{flags} is:
11798 @item scene_change_detect, scd
11799 Enable scene change detection using the value of the option @var{scene}.
11800 This flag is enabled by default.
11806 Select one frame every N-th frame.
11808 This filter accepts the following option:
11811 Select frame after every @code{step} frames.
11812 Allowed values are positive integers higher than 0. Default value is @code{1}.
11815 @section freezedetect
11817 Detect frozen video.
11819 This filter logs a message and sets frame metadata when it detects that the
11820 input video has no significant change in content during a specified duration.
11821 Video freeze detection calculates the mean average absolute difference of all
11822 the components of video frames and compares it to a noise floor.
11824 The printed times and duration are expressed in seconds. The
11825 @code{lavfi.freezedetect.freeze_start} metadata key is set on the first frame
11826 whose timestamp equals or exceeds the detection duration and it contains the
11827 timestamp of the first frame of the freeze. The
11828 @code{lavfi.freezedetect.freeze_duration} and
11829 @code{lavfi.freezedetect.freeze_end} metadata keys are set on the first frame
11832 The filter accepts the following options:
11836 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
11837 specified value) or as a difference ratio between 0 and 1. Default is -60dB, or
11841 Set freeze duration until notification (default is 2 seconds).
11844 @section freezeframes
11846 Freeze video frames.
11848 This filter freezes video frames using frame from 2nd input.
11850 The filter accepts the following options:
11854 Set number of first frame from which to start freeze.
11857 Set number of last frame from which to end freeze.
11860 Set number of frame from 2nd input which will be used instead of replaced frames.
11866 Apply a frei0r effect to the input video.
11868 To enable the compilation of this filter, you need to install the frei0r
11869 header and configure FFmpeg with @code{--enable-frei0r}.
11871 It accepts the following parameters:
11876 The name of the frei0r effect to load. If the environment variable
11877 @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
11878 directories specified by the colon-separated list in @env{FREI0R_PATH}.
11879 Otherwise, the standard frei0r paths are searched, in this order:
11880 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
11881 @file{/usr/lib/frei0r-1/}.
11883 @item filter_params
11884 A '|'-separated list of parameters to pass to the frei0r effect.
11888 A frei0r effect parameter can be a boolean (its value is either
11889 "y" or "n"), a double, a color (specified as
11890 @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
11891 numbers between 0.0 and 1.0, inclusive) or a color description as specified in the
11892 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils},
11893 a position (specified as @var{X}/@var{Y}, where
11894 @var{X} and @var{Y} are floating point numbers) and/or a string.
11896 The number and types of parameters depend on the loaded effect. If an
11897 effect parameter is not specified, the default value is set.
11899 @subsection Examples
11903 Apply the distort0r effect, setting the first two double parameters:
11905 frei0r=filter_name=distort0r:filter_params=0.5|0.01
11909 Apply the colordistance effect, taking a color as the first parameter:
11911 frei0r=colordistance:0.2/0.3/0.4
11912 frei0r=colordistance:violet
11913 frei0r=colordistance:0x112233
11917 Apply the perspective effect, specifying the top left and top right image
11920 frei0r=perspective:0.2/0.2|0.8/0.2
11924 For more information, see
11925 @url{http://frei0r.dyne.org}
11927 @subsection Commands
11929 This filter supports the @option{filter_params} option as @ref{commands}.
11933 Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
11935 It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
11936 processing filter, one of them is performed once per block, not per pixel.
11937 This allows for much higher speed.
11939 The filter accepts the following options:
11943 Set quality. This option defines the number of levels for averaging. It accepts
11944 an integer in the range 4-5. Default value is @code{4}.
11947 Force a constant quantization parameter. It accepts an integer in range 0-63.
11948 If not set, the filter will use the QP from the video stream (if available).
11951 Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
11952 more details but also more artifacts, while higher values make the image smoother
11953 but also blurrier. Default value is @code{0} − PSNR optimal.
11955 @item use_bframe_qp
11956 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
11957 option may cause flicker since the B-Frames have often larger QP. Default is
11958 @code{0} (not enabled).
11964 Apply Gaussian blur filter.
11966 The filter accepts the following options:
11970 Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
11973 Set number of steps for Gaussian approximation. Default is @code{1}.
11976 Set which planes to filter. By default all planes are filtered.
11979 Set vertical sigma, if negative it will be same as @code{sigma}.
11980 Default is @code{-1}.
11983 @subsection Commands
11984 This filter supports same commands as options.
11985 The command accepts the same syntax of the corresponding option.
11987 If the specified expression is not valid, it is kept at its current
11992 Apply generic equation to each pixel.
11994 The filter accepts the following options:
11997 @item lum_expr, lum
11998 Set the luminance expression.
12000 Set the chrominance blue expression.
12002 Set the chrominance red expression.
12003 @item alpha_expr, a
12004 Set the alpha expression.
12006 Set the red expression.
12007 @item green_expr, g
12008 Set the green expression.
12010 Set the blue expression.
12013 The colorspace is selected according to the specified options. If one
12014 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
12015 options is specified, the filter will automatically select a YCbCr
12016 colorspace. If one of the @option{red_expr}, @option{green_expr}, or
12017 @option{blue_expr} options is specified, it will select an RGB
12020 If one of the chrominance expression is not defined, it falls back on the other
12021 one. If no alpha expression is specified it will evaluate to opaque value.
12022 If none of chrominance expressions are specified, they will evaluate
12023 to the luminance expression.
12025 The expressions can use the following variables and functions:
12029 The sequential number of the filtered frame, starting from @code{0}.
12033 The coordinates of the current sample.
12037 The width and height of the image.
12041 Width and height scale depending on the currently filtered plane. It is the
12042 ratio between the corresponding luma plane number of pixels and the current
12043 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
12044 @code{0.5,0.5} for chroma planes.
12047 Time of the current frame, expressed in seconds.
12050 Return the value of the pixel at location (@var{x},@var{y}) of the current
12054 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
12058 Return the value of the pixel at location (@var{x},@var{y}) of the
12059 blue-difference chroma plane. Return 0 if there is no such plane.
12062 Return the value of the pixel at location (@var{x},@var{y}) of the
12063 red-difference chroma plane. Return 0 if there is no such plane.
12068 Return the value of the pixel at location (@var{x},@var{y}) of the
12069 red/green/blue component. Return 0 if there is no such component.
12072 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
12073 plane. Return 0 if there is no such plane.
12075 @item psum(x,y), lumsum(x, y), cbsum(x,y), crsum(x,y), rsum(x,y), gsum(x,y), bsum(x,y), alphasum(x,y)
12076 Sum of sample values in the rectangle from (0,0) to (x,y), this allows obtaining
12077 sums of samples within a rectangle. See the functions without the sum postfix.
12079 @item interpolation
12080 Set one of interpolation methods:
12085 Default is bilinear.
12088 For functions, if @var{x} and @var{y} are outside the area, the value will be
12089 automatically clipped to the closer edge.
12091 Please note that this filter can use multiple threads in which case each slice
12092 will have its own expression state. If you want to use only a single expression
12093 state because your expressions depend on previous state then you should limit
12094 the number of filter threads to 1.
12096 @subsection Examples
12100 Flip the image horizontally:
12106 Generate a bidimensional sine wave, with angle @code{PI/3} and a
12107 wavelength of 100 pixels:
12109 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
12113 Generate a fancy enigmatic moving light:
12115 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
12119 Generate a quick emboss effect:
12121 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
12125 Modify RGB components depending on pixel position:
12127 geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
12131 Create a radial gradient that is the same size as the input (also see
12132 the @ref{vignette} filter):
12134 geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
12140 Fix the banding artifacts that are sometimes introduced into nearly flat
12141 regions by truncation to 8-bit color depth.
12142 Interpolate the gradients that should go where the bands are, and
12145 It is designed for playback only. Do not use it prior to
12146 lossy compression, because compression tends to lose the dither and
12147 bring back the bands.
12149 It accepts the following parameters:
12154 The maximum amount by which the filter will change any one pixel. This is also
12155 the threshold for detecting nearly flat regions. Acceptable values range from
12156 .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
12160 The neighborhood to fit the gradient to. A larger radius makes for smoother
12161 gradients, but also prevents the filter from modifying the pixels near detailed
12162 regions. Acceptable values are 8-32; the default value is 16. Out-of-range
12163 values will be clipped to the valid range.
12167 Alternatively, the options can be specified as a flat string:
12168 @var{strength}[:@var{radius}]
12170 @subsection Examples
12174 Apply the filter with a @code{3.5} strength and radius of @code{8}:
12180 Specify radius, omitting the strength (which will fall-back to the default
12188 @anchor{graphmonitor}
12189 @section graphmonitor
12190 Show various filtergraph stats.
12192 With this filter one can debug complete filtergraph.
12193 Especially issues with links filling with queued frames.
12195 The filter accepts the following options:
12199 Set video output size. Default is @var{hd720}.
12202 Set video opacity. Default is @var{0.9}. Allowed range is from @var{0} to @var{1}.
12205 Set output mode, can be @var{fulll} or @var{compact}.
12206 In @var{compact} mode only filters with some queued frames have displayed stats.
12209 Set flags which enable which stats are shown in video.
12211 Available values for flags are:
12214 Display number of queued frames in each link.
12216 @item frame_count_in
12217 Display number of frames taken from filter.
12219 @item frame_count_out
12220 Display number of frames given out from filter.
12223 Display current filtered frame pts.
12226 Display current filtered frame time.
12229 Display time base for filter link.
12232 Display used format for filter link.
12235 Display video size or number of audio channels in case of audio used by filter link.
12238 Display video frame rate or sample rate in case of audio used by filter link.
12241 Display link output status.
12245 Set upper limit for video rate of output stream, Default value is @var{25}.
12246 This guarantee that output video frame rate will not be higher than this value.
12250 A color constancy variation filter which estimates scene illumination via grey edge algorithm
12251 and corrects the scene colors accordingly.
12253 See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf}
12255 The filter accepts the following options:
12259 The order of differentiation to be applied on the scene. Must be chosen in the range
12260 [0,2] and default value is 1.
12263 The Minkowski parameter to be used for calculating the Minkowski distance. Must
12264 be chosen in the range [0,20] and default value is 1. Set to 0 for getting
12265 max value instead of calculating Minkowski distance.
12268 The standard deviation of Gaussian blur to be applied on the scene. Must be
12269 chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) )
12270 can't be equal to 0 if @var{difford} is greater than 0.
12273 @subsection Examples
12279 greyedge=difford=1:minknorm=5:sigma=2
12285 greyedge=difford=1:minknorm=0:sigma=2
12293 Apply a Hald CLUT to a video stream.
12295 First input is the video stream to process, and second one is the Hald CLUT.
12296 The Hald CLUT input can be a simple picture or a complete video stream.
12298 The filter accepts the following options:
12302 Force termination when the shortest input terminates. Default is @code{0}.
12304 Continue applying the last CLUT after the end of the stream. A value of
12305 @code{0} disable the filter after the last frame of the CLUT is reached.
12306 Default is @code{1}.
12309 @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
12310 filters share the same internals).
12312 This filter also supports the @ref{framesync} options.
12314 More information about the Hald CLUT can be found on Eskil Steenberg's website
12315 (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
12317 @subsection Workflow examples
12319 @subsubsection Hald CLUT video stream
12321 Generate an identity Hald CLUT stream altered with various effects:
12323 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
12326 Note: make sure you use a lossless codec.
12328 Then use it with @code{haldclut} to apply it on some random stream:
12330 ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
12333 The Hald CLUT will be applied to the 10 first seconds (duration of
12334 @file{clut.nut}), then the latest picture of that CLUT stream will be applied
12335 to the remaining frames of the @code{mandelbrot} stream.
12337 @subsubsection Hald CLUT with preview
12339 A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
12340 @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
12341 biggest possible square starting at the top left of the picture. The remaining
12342 padding pixels (bottom or right) will be ignored. This area can be used to add
12343 a preview of the Hald CLUT.
12345 Typically, the following generated Hald CLUT will be supported by the
12346 @code{haldclut} filter:
12349 ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
12350 pad=iw+320 [padded_clut];
12351 smptebars=s=320x256, split [a][b];
12352 [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
12353 [main][b] overlay=W-320" -frames:v 1 clut.png
12356 It contains the original and a preview of the effect of the CLUT: SMPTE color
12357 bars are displayed on the right-top, and below the same color bars processed by
12360 Then, the effect of this Hald CLUT can be visualized with:
12362 ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
12367 Flip the input video horizontally.
12369 For example, to horizontally flip the input video with @command{ffmpeg}:
12371 ffmpeg -i in.avi -vf "hflip" out.avi
12375 This filter applies a global color histogram equalization on a
12378 It can be used to correct video that has a compressed range of pixel
12379 intensities. The filter redistributes the pixel intensities to
12380 equalize their distribution across the intensity range. It may be
12381 viewed as an "automatically adjusting contrast filter". This filter is
12382 useful only for correcting degraded or poorly captured source
12385 The filter accepts the following options:
12389 Determine the amount of equalization to be applied. As the strength
12390 is reduced, the distribution of pixel intensities more-and-more
12391 approaches that of the input frame. The value must be a float number
12392 in the range [0,1] and defaults to 0.200.
12395 Set the maximum intensity that can generated and scale the output
12396 values appropriately. The strength should be set as desired and then
12397 the intensity can be limited if needed to avoid washing-out. The value
12398 must be a float number in the range [0,1] and defaults to 0.210.
12401 Set the antibanding level. If enabled the filter will randomly vary
12402 the luminance of output pixels by a small amount to avoid banding of
12403 the histogram. Possible values are @code{none}, @code{weak} or
12404 @code{strong}. It defaults to @code{none}.
12410 Compute and draw a color distribution histogram for the input video.
12412 The computed histogram is a representation of the color component
12413 distribution in an image.
12415 Standard histogram displays the color components distribution in an image.
12416 Displays color graph for each color component. Shows distribution of
12417 the Y, U, V, A or R, G, B components, depending on input format, in the
12418 current frame. Below each graph a color component scale meter is shown.
12420 The filter accepts the following options:
12424 Set height of level. Default value is @code{200}.
12425 Allowed range is [50, 2048].
12428 Set height of color scale. Default value is @code{12}.
12429 Allowed range is [0, 40].
12433 It accepts the following values:
12436 Per color component graphs are placed below each other.
12439 Per color component graphs are placed side by side.
12442 Presents information identical to that in the @code{parade}, except
12443 that the graphs representing color components are superimposed directly
12446 Default is @code{stack}.
12449 Set mode. Can be either @code{linear}, or @code{logarithmic}.
12450 Default is @code{linear}.
12453 Set what color components to display.
12454 Default is @code{7}.
12457 Set foreground opacity. Default is @code{0.7}.
12460 Set background opacity. Default is @code{0.5}.
12463 @subsection Examples
12468 Calculate and draw histogram:
12470 ffplay -i input -vf histogram
12478 This is a high precision/quality 3d denoise filter. It aims to reduce
12479 image noise, producing smooth images and making still images really
12480 still. It should enhance compressibility.
12482 It accepts the following optional parameters:
12486 A non-negative floating point number which specifies spatial luma strength.
12487 It defaults to 4.0.
12489 @item chroma_spatial
12490 A non-negative floating point number which specifies spatial chroma strength.
12491 It defaults to 3.0*@var{luma_spatial}/4.0.
12494 A floating point number which specifies luma temporal strength. It defaults to
12495 6.0*@var{luma_spatial}/4.0.
12498 A floating point number which specifies chroma temporal strength. It defaults to
12499 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
12502 @subsection Commands
12503 This filter supports same @ref{commands} as options.
12504 The command accepts the same syntax of the corresponding option.
12506 If the specified expression is not valid, it is kept at its current
12509 @anchor{hwdownload}
12510 @section hwdownload
12512 Download hardware frames to system memory.
12514 The input must be in hardware frames, and the output a non-hardware format.
12515 Not all formats will be supported on the output - it may be necessary to insert
12516 an additional @option{format} filter immediately following in the graph to get
12517 the output in a supported format.
12521 Map hardware frames to system memory or to another device.
12523 This filter has several different modes of operation; which one is used depends
12524 on the input and output formats:
12527 Hardware frame input, normal frame output
12529 Map the input frames to system memory and pass them to the output. If the
12530 original hardware frame is later required (for example, after overlaying
12531 something else on part of it), the @option{hwmap} filter can be used again
12532 in the next mode to retrieve it.
12534 Normal frame input, hardware frame output
12536 If the input is actually a software-mapped hardware frame, then unmap it -
12537 that is, return the original hardware frame.
12539 Otherwise, a device must be provided. Create new hardware surfaces on that
12540 device for the output, then map them back to the software format at the input
12541 and give those frames to the preceding filter. This will then act like the
12542 @option{hwupload} filter, but may be able to avoid an additional copy when
12543 the input is already in a compatible format.
12545 Hardware frame input and output
12547 A device must be supplied for the output, either directly or with the
12548 @option{derive_device} option. The input and output devices must be of
12549 different types and compatible - the exact meaning of this is
12550 system-dependent, but typically it means that they must refer to the same
12551 underlying hardware context (for example, refer to the same graphics card).
12553 If the input frames were originally created on the output device, then unmap
12554 to retrieve the original frames.
12556 Otherwise, map the frames to the output device - create new hardware frames
12557 on the output corresponding to the frames on the input.
12560 The following additional parameters are accepted:
12564 Set the frame mapping mode. Some combination of:
12567 The mapped frame should be readable.
12569 The mapped frame should be writeable.
12571 The mapping will always overwrite the entire frame.
12573 This may improve performance in some cases, as the original contents of the
12574 frame need not be loaded.
12576 The mapping must not involve any copying.
12578 Indirect mappings to copies of frames are created in some cases where either
12579 direct mapping is not possible or it would have unexpected properties.
12580 Setting this flag ensures that the mapping is direct and will fail if that is
12583 Defaults to @var{read+write} if not specified.
12585 @item derive_device @var{type}
12586 Rather than using the device supplied at initialisation, instead derive a new
12587 device of type @var{type} from the device the input frames exist on.
12590 In a hardware to hardware mapping, map in reverse - create frames in the sink
12591 and map them back to the source. This may be necessary in some cases where
12592 a mapping in one direction is required but only the opposite direction is
12593 supported by the devices being used.
12595 This option is dangerous - it may break the preceding filter in undefined
12596 ways if there are any additional constraints on that filter's output.
12597 Do not use it without fully understanding the implications of its use.
12603 Upload system memory frames to hardware surfaces.
12605 The device to upload to must be supplied when the filter is initialised. If
12606 using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
12607 option or with the @option{derive_device} option. The input and output devices
12608 must be of different types and compatible - the exact meaning of this is
12609 system-dependent, but typically it means that they must refer to the same
12610 underlying hardware context (for example, refer to the same graphics card).
12612 The following additional parameters are accepted:
12615 @item derive_device @var{type}
12616 Rather than using the device supplied at initialisation, instead derive a new
12617 device of type @var{type} from the device the input frames exist on.
12620 @anchor{hwupload_cuda}
12621 @section hwupload_cuda
12623 Upload system memory frames to a CUDA device.
12625 It accepts the following optional parameters:
12629 The number of the CUDA device to use
12634 Apply a high-quality magnification filter designed for pixel art. This filter
12635 was originally created by Maxim Stepin.
12637 It accepts the following option:
12641 Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
12642 @code{hq3x} and @code{4} for @code{hq4x}.
12643 Default is @code{3}.
12647 Stack input videos horizontally.
12649 All streams must be of same pixel format and of same height.
12651 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
12652 to create same output.
12654 The filter accepts the following option:
12658 Set number of input streams. Default is 2.
12661 If set to 1, force the output to terminate when the shortest input
12662 terminates. Default value is 0.
12667 Modify the hue and/or the saturation of the input.
12669 It accepts the following parameters:
12673 Specify the hue angle as a number of degrees. It accepts an expression,
12674 and defaults to "0".
12677 Specify the saturation in the [-10,10] range. It accepts an expression and
12681 Specify the hue angle as a number of radians. It accepts an
12682 expression, and defaults to "0".
12685 Specify the brightness in the [-10,10] range. It accepts an expression and
12689 @option{h} and @option{H} are mutually exclusive, and can't be
12690 specified at the same time.
12692 The @option{b}, @option{h}, @option{H} and @option{s} option values are
12693 expressions containing the following constants:
12697 frame count of the input frame starting from 0
12700 presentation timestamp of the input frame expressed in time base units
12703 frame rate of the input video, NAN if the input frame rate is unknown
12706 timestamp expressed in seconds, NAN if the input timestamp is unknown
12709 time base of the input video
12712 @subsection Examples
12716 Set the hue to 90 degrees and the saturation to 1.0:
12722 Same command but expressing the hue in radians:
12728 Rotate hue and make the saturation swing between 0
12729 and 2 over a period of 1 second:
12731 hue="H=2*PI*t: s=sin(2*PI*t)+1"
12735 Apply a 3 seconds saturation fade-in effect starting at 0:
12737 hue="s=min(t/3\,1)"
12740 The general fade-in expression can be written as:
12742 hue="s=min(0\, max((t-START)/DURATION\, 1))"
12746 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
12748 hue="s=max(0\, min(1\, (8-t)/3))"
12751 The general fade-out expression can be written as:
12753 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
12758 @subsection Commands
12760 This filter supports the following commands:
12766 Modify the hue and/or the saturation and/or brightness of the input video.
12767 The command accepts the same syntax of the corresponding option.
12769 If the specified expression is not valid, it is kept at its current
12773 @section hysteresis
12775 Grow first stream into second stream by connecting components.
12776 This makes it possible to build more robust edge masks.
12778 This filter accepts the following options:
12782 Set which planes will be processed as bitmap, unprocessed planes will be
12783 copied from first stream.
12784 By default value 0xf, all planes will be processed.
12787 Set threshold which is used in filtering. If pixel component value is higher than
12788 this value filter algorithm for connecting components is activated.
12789 By default value is 0.
12792 The @code{hysteresis} filter also supports the @ref{framesync} options.
12796 Detect video interlacing type.
12798 This filter tries to detect if the input frames are interlaced, progressive,
12799 top or bottom field first. It will also try to detect fields that are
12800 repeated between adjacent frames (a sign of telecine).
12802 Single frame detection considers only immediately adjacent frames when classifying each frame.
12803 Multiple frame detection incorporates the classification history of previous frames.
12805 The filter will log these metadata values:
12808 @item single.current_frame
12809 Detected type of current frame using single-frame detection. One of:
12810 ``tff'' (top field first), ``bff'' (bottom field first),
12811 ``progressive'', or ``undetermined''
12814 Cumulative number of frames detected as top field first using single-frame detection.
12817 Cumulative number of frames detected as top field first using multiple-frame detection.
12820 Cumulative number of frames detected as bottom field first using single-frame detection.
12822 @item multiple.current_frame
12823 Detected type of current frame using multiple-frame detection. One of:
12824 ``tff'' (top field first), ``bff'' (bottom field first),
12825 ``progressive'', or ``undetermined''
12828 Cumulative number of frames detected as bottom field first using multiple-frame detection.
12830 @item single.progressive
12831 Cumulative number of frames detected as progressive using single-frame detection.
12833 @item multiple.progressive
12834 Cumulative number of frames detected as progressive using multiple-frame detection.
12836 @item single.undetermined
12837 Cumulative number of frames that could not be classified using single-frame detection.
12839 @item multiple.undetermined
12840 Cumulative number of frames that could not be classified using multiple-frame detection.
12842 @item repeated.current_frame
12843 Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
12845 @item repeated.neither
12846 Cumulative number of frames with no repeated field.
12849 Cumulative number of frames with the top field repeated from the previous frame's top field.
12851 @item repeated.bottom
12852 Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
12855 The filter accepts the following options:
12859 Set interlacing threshold.
12861 Set progressive threshold.
12863 Threshold for repeated field detection.
12865 Number of frames after which a given frame's contribution to the
12866 statistics is halved (i.e., it contributes only 0.5 to its
12867 classification). The default of 0 means that all frames seen are given
12868 full weight of 1.0 forever.
12869 @item analyze_interlaced_flag
12870 When this is not 0 then idet will use the specified number of frames to determine
12871 if the interlaced flag is accurate, it will not count undetermined frames.
12872 If the flag is found to be accurate it will be used without any further
12873 computations, if it is found to be inaccurate it will be cleared without any
12874 further computations. This allows inserting the idet filter as a low computational
12875 method to clean up the interlaced flag
12880 Deinterleave or interleave fields.
12882 This filter allows one to process interlaced images fields without
12883 deinterlacing them. Deinterleaving splits the input frame into 2
12884 fields (so called half pictures). Odd lines are moved to the top
12885 half of the output image, even lines to the bottom half.
12886 You can process (filter) them independently and then re-interleave them.
12888 The filter accepts the following options:
12892 @item chroma_mode, c
12893 @item alpha_mode, a
12894 Available values for @var{luma_mode}, @var{chroma_mode} and
12895 @var{alpha_mode} are:
12901 @item deinterleave, d
12902 Deinterleave fields, placing one above the other.
12904 @item interleave, i
12905 Interleave fields. Reverse the effect of deinterleaving.
12907 Default value is @code{none}.
12909 @item luma_swap, ls
12910 @item chroma_swap, cs
12911 @item alpha_swap, as
12912 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
12915 @subsection Commands
12917 This filter supports the all above options as @ref{commands}.
12921 Apply inflate effect to the video.
12923 This filter replaces the pixel by the local(3x3) average by taking into account
12924 only values higher than the pixel.
12926 It accepts the following options:
12933 Limit the maximum change for each plane, default is 65535.
12934 If 0, plane will remain unchanged.
12937 @subsection Commands
12939 This filter supports the all above options as @ref{commands}.
12943 Simple interlacing filter from progressive contents. This interleaves upper (or
12944 lower) lines from odd frames with lower (or upper) lines from even frames,
12945 halving the frame rate and preserving image height.
12948 Original Original New Frame
12949 Frame 'j' Frame 'j+1' (tff)
12950 ========== =========== ==================
12951 Line 0 --------------------> Frame 'j' Line 0
12952 Line 1 Line 1 ----> Frame 'j+1' Line 1
12953 Line 2 ---------------------> Frame 'j' Line 2
12954 Line 3 Line 3 ----> Frame 'j+1' Line 3
12956 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
12959 It accepts the following optional parameters:
12963 This determines whether the interlaced frame is taken from the even
12964 (tff - default) or odd (bff) lines of the progressive frame.
12967 Vertical lowpass filter to avoid twitter interlacing and
12968 reduce moire patterns.
12972 Disable vertical lowpass filter
12975 Enable linear filter (default)
12978 Enable complex filter. This will slightly less reduce twitter and moire
12979 but better retain detail and subjective sharpness impression.
12986 Deinterlace input video by applying Donald Graft's adaptive kernel
12987 deinterling. Work on interlaced parts of a video to produce
12988 progressive frames.
12990 The description of the accepted parameters follows.
12994 Set the threshold which affects the filter's tolerance when
12995 determining if a pixel line must be processed. It must be an integer
12996 in the range [0,255] and defaults to 10. A value of 0 will result in
12997 applying the process on every pixels.
13000 Paint pixels exceeding the threshold value to white if set to 1.
13004 Set the fields order. Swap fields if set to 1, leave fields alone if
13008 Enable additional sharpening if set to 1. Default is 0.
13011 Enable twoway sharpening if set to 1. Default is 0.
13014 @subsection Examples
13018 Apply default values:
13020 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
13024 Enable additional sharpening:
13030 Paint processed pixels in white:
13038 Slowly update darker pixels.
13040 This filter makes short flashes of light appear longer.
13041 This filter accepts the following options:
13045 Set factor for decaying. Default is .95. Allowed range is from 0 to 1.
13048 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
13051 @section lenscorrection
13053 Correct radial lens distortion
13055 This filter can be used to correct for radial distortion as can result from the use
13056 of wide angle lenses, and thereby re-rectify the image. To find the right parameters
13057 one can use tools available for example as part of opencv or simply trial-and-error.
13058 To use opencv use the calibration sample (under samples/cpp) from the opencv sources
13059 and extract the k1 and k2 coefficients from the resulting matrix.
13061 Note that effectively the same filter is available in the open-source tools Krita and
13062 Digikam from the KDE project.
13064 In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
13065 this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
13066 brightness distribution, so you may want to use both filters together in certain
13067 cases, though you will have to take care of ordering, i.e. whether vignetting should
13068 be applied before or after lens correction.
13070 @subsection Options
13072 The filter accepts the following options:
13076 Relative x-coordinate of the focal point of the image, and thereby the center of the
13077 distortion. This value has a range [0,1] and is expressed as fractions of the image
13078 width. Default is 0.5.
13080 Relative y-coordinate of the focal point of the image, and thereby the center of the
13081 distortion. This value has a range [0,1] and is expressed as fractions of the image
13082 height. Default is 0.5.
13084 Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means
13085 no correction. Default is 0.
13087 Coefficient of the double quadratic correction term. This value has a range [-1,1].
13088 0 means no correction. Default is 0.
13091 The formula that generates the correction is:
13093 @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)
13095 where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
13096 distances from the focal point in the source and target images, respectively.
13100 Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}).
13102 The @code{lensfun} filter requires the camera make, camera model, and lens model
13103 to apply the lens correction. The filter will load the lensfun database and
13104 query it to find the corresponding camera and lens entries in the database. As
13105 long as these entries can be found with the given options, the filter can
13106 perform corrections on frames. Note that incomplete strings will result in the
13107 filter choosing the best match with the given options, and the filter will
13108 output the chosen camera and lens models (logged with level "info"). You must
13109 provide the make, camera model, and lens model as they are required.
13111 The filter accepts the following options:
13115 The make of the camera (for example, "Canon"). This option is required.
13118 The model of the camera (for example, "Canon EOS 100D"). This option is
13122 The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This
13123 option is required.
13126 The type of correction to apply. The following values are valid options:
13130 Enables fixing lens vignetting.
13133 Enables fixing lens geometry. This is the default.
13136 Enables fixing chromatic aberrations.
13139 Enables fixing lens vignetting and lens geometry.
13142 Enables fixing lens vignetting and chromatic aberrations.
13145 Enables fixing both lens geometry and chromatic aberrations.
13148 Enables all possible corrections.
13152 The focal length of the image/video (zoom; expected constant for video). For
13153 example, a 18--55mm lens has focal length range of [18--55], so a value in that
13154 range should be chosen when using that lens. Default 18.
13157 The aperture of the image/video (expected constant for video). Note that
13158 aperture is only used for vignetting correction. Default 3.5.
13160 @item focus_distance
13161 The focus distance of the image/video (expected constant for video). Note that
13162 focus distance is only used for vignetting and only slightly affects the
13163 vignetting correction process. If unknown, leave it at the default value (which
13167 The scale factor which is applied after transformation. After correction the
13168 video is no longer necessarily rectangular. This parameter controls how much of
13169 the resulting image is visible. The value 0 means that a value will be chosen
13170 automatically such that there is little or no unmapped area in the output
13171 image. 1.0 means that no additional scaling is done. Lower values may result
13172 in more of the corrected image being visible, while higher values may avoid
13173 unmapped areas in the output.
13175 @item target_geometry
13176 The target geometry of the output image/video. The following values are valid
13180 @item rectilinear (default)
13183 @item equirectangular
13184 @item fisheye_orthographic
13185 @item fisheye_stereographic
13186 @item fisheye_equisolid
13187 @item fisheye_thoby
13190 Apply the reverse of image correction (instead of correcting distortion, apply
13193 @item interpolation
13194 The type of interpolation used when correcting distortion. The following values
13199 @item linear (default)
13204 @subsection Examples
13208 Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens
13209 model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and
13213 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
13217 Apply the same as before, but only for the first 5 seconds of video.
13220 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
13227 Obtain the VMAF (Video Multi-Method Assessment Fusion)
13228 score between two input videos.
13230 The obtained VMAF score is printed through the logging system.
13232 It requires Netflix's vmaf library (libvmaf) as a pre-requisite.
13233 After installing the library it can be enabled using:
13234 @code{./configure --enable-libvmaf}.
13235 If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}.
13237 The filter has following options:
13241 Set the model path which is to be used for SVM.
13242 Default value: @code{"/usr/local/share/model/vmaf_v0.6.1.pkl"}
13245 Set the file path to be used to store logs.
13248 Set the format of the log file (csv, json or xml).
13250 @item enable_transform
13251 This option can enable/disable the @code{score_transform} applied to the final predicted VMAF score,
13252 if you have specified score_transform option in the input parameter file passed to @code{run_vmaf_training.py}
13253 Default value: @code{false}
13256 Invokes the phone model which will generate VMAF scores higher than in the
13257 regular model, which is more suitable for laptop, TV, etc. viewing conditions.
13258 Default value: @code{false}
13261 Enables computing psnr along with vmaf.
13262 Default value: @code{false}
13265 Enables computing ssim along with vmaf.
13266 Default value: @code{false}
13269 Enables computing ms_ssim along with vmaf.
13270 Default value: @code{false}
13273 Set the pool method to be used for computing vmaf.
13274 Options are @code{min}, @code{harmonic_mean} or @code{mean} (default).
13277 Set number of threads to be used when computing vmaf.
13278 Default value: @code{0}, which makes use of all available logical processors.
13281 Set interval for frame subsampling used when computing vmaf.
13282 Default value: @code{1}
13284 @item enable_conf_interval
13285 Enables confidence interval.
13286 Default value: @code{false}
13289 This filter also supports the @ref{framesync} options.
13291 @subsection Examples
13294 On the below examples the input file @file{main.mpg} being processed is
13295 compared with the reference file @file{ref.mpg}.
13298 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
13302 Example with options:
13304 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:log_fmt=json" -f null -
13308 Example with options and different containers:
13310 ffmpeg -i main.mpg -i ref.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]libvmaf=psnr=1:log_fmt=json" -f null -
13316 Limits the pixel components values to the specified range [min, max].
13318 The filter accepts the following options:
13322 Lower bound. Defaults to the lowest allowed value for the input.
13325 Upper bound. Defaults to the highest allowed value for the input.
13328 Specify which planes will be processed. Defaults to all available.
13335 The filter accepts the following options:
13339 Set the number of loops. Setting this value to -1 will result in infinite loops.
13343 Set maximal size in number of frames. Default is 0.
13346 Set first frame of loop. Default is 0.
13349 @subsection Examples
13353 Loop single first frame infinitely:
13355 loop=loop=-1:size=1:start=0
13359 Loop single first frame 10 times:
13361 loop=loop=10:size=1:start=0
13365 Loop 10 first frames 5 times:
13367 loop=loop=5:size=10:start=0
13373 Apply a 1D LUT to an input video.
13375 The filter accepts the following options:
13379 Set the 1D LUT file name.
13381 Currently supported formats:
13390 Select interpolation mode.
13392 Available values are:
13396 Use values from the nearest defined point.
13398 Interpolate values using the linear interpolation.
13400 Interpolate values using the cosine interpolation.
13402 Interpolate values using the cubic interpolation.
13404 Interpolate values using the spline interpolation.
13411 Apply a 3D LUT to an input video.
13413 The filter accepts the following options:
13417 Set the 3D LUT file name.
13419 Currently supported formats:
13433 Select interpolation mode.
13435 Available values are:
13439 Use values from the nearest defined point.
13441 Interpolate values using the 8 points defining a cube.
13443 Interpolate values using a tetrahedron.
13449 Turn certain luma values into transparency.
13451 The filter accepts the following options:
13455 Set the luma which will be used as base for transparency.
13456 Default value is @code{0}.
13459 Set the range of luma values to be keyed out.
13460 Default value is @code{0.01}.
13463 Set the range of softness. Default value is @code{0}.
13464 Use this to control gradual transition from zero to full transparency.
13467 @subsection Commands
13468 This filter supports same @ref{commands} as options.
13469 The command accepts the same syntax of the corresponding option.
13471 If the specified expression is not valid, it is kept at its current
13474 @section lut, lutrgb, lutyuv
13476 Compute a look-up table for binding each pixel component input value
13477 to an output value, and apply it to the input video.
13479 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
13480 to an RGB input video.
13482 These filters accept the following parameters:
13485 set first pixel component expression
13487 set second pixel component expression
13489 set third pixel component expression
13491 set fourth pixel component expression, corresponds to the alpha component
13494 set red component expression
13496 set green component expression
13498 set blue component expression
13500 alpha component expression
13503 set Y/luminance component expression
13505 set U/Cb component expression
13507 set V/Cr component expression
13510 Each of them specifies the expression to use for computing the lookup table for
13511 the corresponding pixel component values.
13513 The exact component associated to each of the @var{c*} options depends on the
13516 The @var{lut} filter requires either YUV or RGB pixel formats in input,
13517 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
13519 The expressions can contain the following constants and functions:
13524 The input width and height.
13527 The input value for the pixel component.
13530 The input value, clipped to the @var{minval}-@var{maxval} range.
13533 The maximum value for the pixel component.
13536 The minimum value for the pixel component.
13539 The negated value for the pixel component value, clipped to the
13540 @var{minval}-@var{maxval} range; it corresponds to the expression
13541 "maxval-clipval+minval".
13544 The computed value in @var{val}, clipped to the
13545 @var{minval}-@var{maxval} range.
13547 @item gammaval(gamma)
13548 The computed gamma correction value of the pixel component value,
13549 clipped to the @var{minval}-@var{maxval} range. It corresponds to the
13551 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
13555 All expressions default to "val".
13557 @subsection Examples
13561 Negate input video:
13563 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
13564 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
13567 The above is the same as:
13569 lutrgb="r=negval:g=negval:b=negval"
13570 lutyuv="y=negval:u=negval:v=negval"
13580 Remove chroma components, turning the video into a graytone image:
13582 lutyuv="u=128:v=128"
13586 Apply a luma burning effect:
13592 Remove green and blue components:
13598 Set a constant alpha channel value on input:
13600 format=rgba,lutrgb=a="maxval-minval/2"
13604 Correct luminance gamma by a factor of 0.5:
13606 lutyuv=y=gammaval(0.5)
13610 Discard least significant bits of luma:
13612 lutyuv=y='bitand(val, 128+64+32)'
13616 Technicolor like effect:
13618 lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
13622 @section lut2, tlut2
13624 The @code{lut2} filter takes two input streams and outputs one
13627 The @code{tlut2} (time lut2) filter takes two consecutive frames
13628 from one single stream.
13630 This filter accepts the following parameters:
13633 set first pixel component expression
13635 set second pixel component expression
13637 set third pixel component expression
13639 set fourth pixel component expression, corresponds to the alpha component
13642 set output bit depth, only available for @code{lut2} filter. By default is 0,
13643 which means bit depth is automatically picked from first input format.
13646 The @code{lut2} filter also supports the @ref{framesync} options.
13648 Each of them specifies the expression to use for computing the lookup table for
13649 the corresponding pixel component values.
13651 The exact component associated to each of the @var{c*} options depends on the
13654 The expressions can contain the following constants:
13659 The input width and height.
13662 The first input value for the pixel component.
13665 The second input value for the pixel component.
13668 The first input video bit depth.
13671 The second input video bit depth.
13674 All expressions default to "x".
13676 @subsection Examples
13680 Highlight differences between two RGB video streams:
13682 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)'
13686 Highlight differences between two YUV video streams:
13688 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)'
13692 Show max difference between two video streams:
13694 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)))'
13698 @section maskedclamp
13700 Clamp the first input stream with the second input and third input stream.
13702 Returns the value of first stream to be between second input
13703 stream - @code{undershoot} and third input stream + @code{overshoot}.
13705 This filter accepts the following options:
13708 Default value is @code{0}.
13711 Default value is @code{0}.
13714 Set which planes will be processed as bitmap, unprocessed planes will be
13715 copied from first stream.
13716 By default value 0xf, all planes will be processed.
13721 Merge the second and third input stream into output stream using absolute differences
13722 between second input stream and first input stream and absolute difference between
13723 third input stream and first input stream. The picked value will be from second input
13724 stream if second absolute difference is greater than first one or from third input stream
13727 This filter accepts the following options:
13730 Set which planes will be processed as bitmap, unprocessed planes will be
13731 copied from first stream.
13732 By default value 0xf, all planes will be processed.
13735 @section maskedmerge
13737 Merge the first input stream with the second input stream using per pixel
13738 weights in the third input stream.
13740 A value of 0 in the third stream pixel component means that pixel component
13741 from first stream is returned unchanged, while maximum value (eg. 255 for
13742 8-bit videos) means that pixel component from second stream is returned
13743 unchanged. Intermediate values define the amount of merging between both
13744 input stream's pixel components.
13746 This filter accepts the following options:
13749 Set which planes will be processed as bitmap, unprocessed planes will be
13750 copied from first stream.
13751 By default value 0xf, all planes will be processed.
13756 Merge the second and third input stream into output stream using absolute differences
13757 between second input stream and first input stream and absolute difference between
13758 third input stream and first input stream. The picked value will be from second input
13759 stream if second absolute difference is less than first one or from third input stream
13762 This filter accepts the following options:
13765 Set which planes will be processed as bitmap, unprocessed planes will be
13766 copied from first stream.
13767 By default value 0xf, all planes will be processed.
13770 @section maskedthreshold
13771 Pick pixels comparing absolute difference of two video streams with fixed
13774 If absolute difference between pixel component of first and second video
13775 stream is equal or lower than user supplied threshold than pixel component
13776 from first video stream is picked, otherwise pixel component from second
13777 video stream is picked.
13779 This filter accepts the following options:
13782 Set threshold used when picking pixels from absolute difference from two input
13786 Set which planes will be processed as bitmap, unprocessed planes will be
13787 copied from second stream.
13788 By default value 0xf, all planes will be processed.
13792 Create mask from input video.
13794 For example it is useful to create motion masks after @code{tblend} filter.
13796 This filter accepts the following options:
13800 Set low threshold. Any pixel component lower or exact than this value will be set to 0.
13803 Set high threshold. Any pixel component higher than this value will be set to max value
13804 allowed for current pixel format.
13807 Set planes to filter, by default all available planes are filtered.
13810 Fill all frame pixels with this value.
13813 Set max average pixel value for frame. If sum of all pixel components is higher that this
13814 average, output frame will be completely filled with value set by @var{fill} option.
13815 Typically useful for scene changes when used in combination with @code{tblend} filter.
13820 Apply motion-compensation deinterlacing.
13822 It needs one field per frame as input and must thus be used together
13823 with yadif=1/3 or equivalent.
13825 This filter accepts the following options:
13828 Set the deinterlacing mode.
13830 It accepts one of the following values:
13835 use iterative motion estimation
13837 like @samp{slow}, but use multiple reference frames.
13839 Default value is @samp{fast}.
13842 Set the picture field parity assumed for the input video. It must be
13843 one of the following values:
13847 assume top field first
13849 assume bottom field first
13852 Default value is @samp{bff}.
13855 Set per-block quantization parameter (QP) used by the internal
13858 Higher values should result in a smoother motion vector field but less
13859 optimal individual vectors. Default value is 1.
13864 Pick median pixel from certain rectangle defined by radius.
13866 This filter accepts the following options:
13870 Set horizontal radius size. Default value is @code{1}.
13871 Allowed range is integer from 1 to 127.
13874 Set which planes to process. Default is @code{15}, which is all available planes.
13877 Set vertical radius size. Default value is @code{0}.
13878 Allowed range is integer from 0 to 127.
13879 If it is 0, value will be picked from horizontal @code{radius} option.
13882 Set median percentile. Default value is @code{0.5}.
13883 Default value of @code{0.5} will pick always median values, while @code{0} will pick
13884 minimum values, and @code{1} maximum values.
13887 @subsection Commands
13888 This filter supports same @ref{commands} as options.
13889 The command accepts the same syntax of the corresponding option.
13891 If the specified expression is not valid, it is kept at its current
13894 @section mergeplanes
13896 Merge color channel components from several video streams.
13898 The filter accepts up to 4 input streams, and merge selected input
13899 planes to the output video.
13901 This filter accepts the following options:
13904 Set input to output plane mapping. Default is @code{0}.
13906 The mappings is specified as a bitmap. It should be specified as a
13907 hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
13908 mapping for the first plane of the output stream. 'A' sets the number of
13909 the input stream to use (from 0 to 3), and 'a' the plane number of the
13910 corresponding input to use (from 0 to 3). The rest of the mappings is
13911 similar, 'Bb' describes the mapping for the output stream second
13912 plane, 'Cc' describes the mapping for the output stream third plane and
13913 'Dd' describes the mapping for the output stream fourth plane.
13916 Set output pixel format. Default is @code{yuva444p}.
13919 @subsection Examples
13923 Merge three gray video streams of same width and height into single video stream:
13925 [a0][a1][a2]mergeplanes=0x001020:yuv444p
13929 Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
13931 [a0][a1]mergeplanes=0x00010210:yuva444p
13935 Swap Y and A plane in yuva444p stream:
13937 format=yuva444p,mergeplanes=0x03010200:yuva444p
13941 Swap U and V plane in yuv420p stream:
13943 format=yuv420p,mergeplanes=0x000201:yuv420p
13947 Cast a rgb24 clip to yuv444p:
13949 format=rgb24,mergeplanes=0x000102:yuv444p
13955 Estimate and export motion vectors using block matching algorithms.
13956 Motion vectors are stored in frame side data to be used by other filters.
13958 This filter accepts the following options:
13961 Specify the motion estimation method. Accepts one of the following values:
13965 Exhaustive search algorithm.
13967 Three step search algorithm.
13969 Two dimensional logarithmic search algorithm.
13971 New three step search algorithm.
13973 Four step search algorithm.
13975 Diamond search algorithm.
13977 Hexagon-based search algorithm.
13979 Enhanced predictive zonal search algorithm.
13981 Uneven multi-hexagon search algorithm.
13983 Default value is @samp{esa}.
13986 Macroblock size. Default @code{16}.
13989 Search parameter. Default @code{7}.
13992 @section midequalizer
13994 Apply Midway Image Equalization effect using two video streams.
13996 Midway Image Equalization adjusts a pair of images to have the same
13997 histogram, while maintaining their dynamics as much as possible. It's
13998 useful for e.g. matching exposures from a pair of stereo cameras.
14000 This filter has two inputs and one output, which must be of same pixel format, but
14001 may be of different sizes. The output of filter is first input adjusted with
14002 midway histogram of both inputs.
14004 This filter accepts the following option:
14008 Set which planes to process. Default is @code{15}, which is all available planes.
14011 @section minterpolate
14013 Convert the video to specified frame rate using motion interpolation.
14015 This filter accepts the following options:
14018 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}.
14021 Motion interpolation mode. Following values are accepted:
14024 Duplicate previous or next frame for interpolating new ones.
14026 Blend source frames. Interpolated frame is mean of previous and next frames.
14028 Motion compensated interpolation. Following options are effective when this mode is selected:
14032 Motion compensation mode. Following values are accepted:
14035 Overlapped block motion compensation.
14037 Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
14039 Default mode is @samp{obmc}.
14042 Motion estimation mode. Following values are accepted:
14045 Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
14047 Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
14049 Default mode is @samp{bilat}.
14052 The algorithm to be used for motion estimation. Following values are accepted:
14055 Exhaustive search algorithm.
14057 Three step search algorithm.
14059 Two dimensional logarithmic search algorithm.
14061 New three step search algorithm.
14063 Four step search algorithm.
14065 Diamond search algorithm.
14067 Hexagon-based search algorithm.
14069 Enhanced predictive zonal search algorithm.
14071 Uneven multi-hexagon search algorithm.
14073 Default algorithm is @samp{epzs}.
14076 Macroblock size. Default @code{16}.
14079 Motion estimation search parameter. Default @code{32}.
14082 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).
14087 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:
14090 Disable scene change detection.
14092 Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected.
14094 Default method is @samp{fdiff}.
14096 @item scd_threshold
14097 Scene change detection threshold. Default is @code{10.}.
14102 Mix several video input streams into one video stream.
14104 A description of the accepted options follows.
14108 The number of inputs. If unspecified, it defaults to 2.
14111 Specify weight of each input video stream as sequence.
14112 Each weight is separated by space. If number of weights
14113 is smaller than number of @var{frames} last specified
14114 weight will be used for all remaining unset weights.
14117 Specify scale, if it is set it will be multiplied with sum
14118 of each weight multiplied with pixel values to give final destination
14119 pixel value. By default @var{scale} is auto scaled to sum of weights.
14122 Specify how end of stream is determined.
14125 The duration of the longest input. (default)
14128 The duration of the shortest input.
14131 The duration of the first input.
14135 @section mpdecimate
14137 Drop frames that do not differ greatly from the previous frame in
14138 order to reduce frame rate.
14140 The main use of this filter is for very-low-bitrate encoding
14141 (e.g. streaming over dialup modem), but it could in theory be used for
14142 fixing movies that were inverse-telecined incorrectly.
14144 A description of the accepted options follows.
14148 Set the maximum number of consecutive frames which can be dropped (if
14149 positive), or the minimum interval between dropped frames (if
14150 negative). If the value is 0, the frame is dropped disregarding the
14151 number of previous sequentially dropped frames.
14153 Default value is 0.
14158 Set the dropping threshold values.
14160 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
14161 represent actual pixel value differences, so a threshold of 64
14162 corresponds to 1 unit of difference for each pixel, or the same spread
14163 out differently over the block.
14165 A frame is a candidate for dropping if no 8x8 blocks differ by more
14166 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
14167 meaning the whole image) differ by more than a threshold of @option{lo}.
14169 Default value for @option{hi} is 64*12, default value for @option{lo} is
14170 64*5, and default value for @option{frac} is 0.33.
14176 Negate (invert) the input video.
14178 It accepts the following option:
14183 With value 1, it negates the alpha component, if present. Default value is 0.
14189 Denoise frames using Non-Local Means algorithm.
14191 Each pixel is adjusted by looking for other pixels with similar contexts. This
14192 context similarity is defined by comparing their surrounding patches of size
14193 @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
14196 Note that the research area defines centers for patches, which means some
14197 patches will be made of pixels outside that research area.
14199 The filter accepts the following options.
14203 Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0].
14206 Set patch size. Default is 7. Must be odd number in range [0, 99].
14209 Same as @option{p} but for chroma planes.
14211 The default value is @var{0} and means automatic.
14214 Set research size. Default is 15. Must be odd number in range [0, 99].
14217 Same as @option{r} but for chroma planes.
14219 The default value is @var{0} and means automatic.
14224 Deinterlace video using neural network edge directed interpolation.
14226 This filter accepts the following options:
14230 Mandatory option, without binary file filter can not work.
14231 Currently file can be found here:
14232 https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
14235 Set which frames to deinterlace, by default it is @code{all}.
14236 Can be @code{all} or @code{interlaced}.
14239 Set mode of operation.
14241 Can be one of the following:
14245 Use frame flags, both fields.
14247 Use frame flags, single field.
14249 Use top field only.
14251 Use bottom field only.
14253 Use both fields, top first.
14255 Use both fields, bottom first.
14259 Set which planes to process, by default filter process all frames.
14262 Set size of local neighborhood around each pixel, used by the predictor neural
14265 Can be one of the following:
14278 Set the number of neurons in predictor neural network.
14279 Can be one of the following:
14290 Controls the number of different neural network predictions that are blended
14291 together to compute the final output value. Can be @code{fast}, default or
14295 Set which set of weights to use in the predictor.
14296 Can be one of the following:
14300 weights trained to minimize absolute error
14302 weights trained to minimize squared error
14306 Controls whether or not the prescreener neural network is used to decide
14307 which pixels should be processed by the predictor neural network and which
14308 can be handled by simple cubic interpolation.
14309 The prescreener is trained to know whether cubic interpolation will be
14310 sufficient for a pixel or whether it should be predicted by the predictor nn.
14311 The computational complexity of the prescreener nn is much less than that of
14312 the predictor nn. Since most pixels can be handled by cubic interpolation,
14313 using the prescreener generally results in much faster processing.
14314 The prescreener is pretty accurate, so the difference between using it and not
14315 using it is almost always unnoticeable.
14317 Can be one of the following:
14325 Default is @code{new}.
14328 Set various debugging flags.
14333 Force libavfilter not to use any of the specified pixel formats for the
14334 input to the next filter.
14336 It accepts the following parameters:
14340 A '|'-separated list of pixel format names, such as
14341 pix_fmts=yuv420p|monow|rgb24".
14345 @subsection Examples
14349 Force libavfilter to use a format different from @var{yuv420p} for the
14350 input to the vflip filter:
14352 noformat=pix_fmts=yuv420p,vflip
14356 Convert the input video to any of the formats not contained in the list:
14358 noformat=yuv420p|yuv444p|yuv410p
14364 Add noise on video input frame.
14366 The filter accepts the following options:
14374 Set noise seed for specific pixel component or all pixel components in case
14375 of @var{all_seed}. Default value is @code{123457}.
14377 @item all_strength, alls
14378 @item c0_strength, c0s
14379 @item c1_strength, c1s
14380 @item c2_strength, c2s
14381 @item c3_strength, c3s
14382 Set noise strength for specific pixel component or all pixel components in case
14383 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
14385 @item all_flags, allf
14386 @item c0_flags, c0f
14387 @item c1_flags, c1f
14388 @item c2_flags, c2f
14389 @item c3_flags, c3f
14390 Set pixel component flags or set flags for all components if @var{all_flags}.
14391 Available values for component flags are:
14394 averaged temporal noise (smoother)
14396 mix random noise with a (semi)regular pattern
14398 temporal noise (noise pattern changes between frames)
14400 uniform noise (gaussian otherwise)
14404 @subsection Examples
14406 Add temporal and uniform noise to input video:
14408 noise=alls=20:allf=t+u
14413 Normalize RGB video (aka histogram stretching, contrast stretching).
14414 See: https://en.wikipedia.org/wiki/Normalization_(image_processing)
14416 For each channel of each frame, the filter computes the input range and maps
14417 it linearly to the user-specified output range. The output range defaults
14418 to the full dynamic range from pure black to pure white.
14420 Temporal smoothing can be used on the input range to reduce flickering (rapid
14421 changes in brightness) caused when small dark or bright objects enter or leave
14422 the scene. This is similar to the auto-exposure (automatic gain control) on a
14423 video camera, and, like a video camera, it may cause a period of over- or
14424 under-exposure of the video.
14426 The R,G,B channels can be normalized independently, which may cause some
14427 color shifting, or linked together as a single channel, which prevents
14428 color shifting. Linked normalization preserves hue. Independent normalization
14429 does not, so it can be used to remove some color casts. Independent and linked
14430 normalization can be combined in any ratio.
14432 The normalize filter accepts the following options:
14437 Colors which define the output range. The minimum input value is mapped to
14438 the @var{blackpt}. The maximum input value is mapped to the @var{whitept}.
14439 The defaults are black and white respectively. Specifying white for
14440 @var{blackpt} and black for @var{whitept} will give color-inverted,
14441 normalized video. Shades of grey can be used to reduce the dynamic range
14442 (contrast). Specifying saturated colors here can create some interesting
14446 The number of previous frames to use for temporal smoothing. The input range
14447 of each channel is smoothed using a rolling average over the current frame
14448 and the @var{smoothing} previous frames. The default is 0 (no temporal
14452 Controls the ratio of independent (color shifting) channel normalization to
14453 linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully
14454 independent. Defaults to 1.0 (fully independent).
14457 Overall strength of the filter. 1.0 is full strength. 0.0 is a rather
14458 expensive no-op. Defaults to 1.0 (full strength).
14462 @subsection Commands
14463 This filter supports same @ref{commands} as options, excluding @var{smoothing} option.
14464 The command accepts the same syntax of the corresponding option.
14466 If the specified expression is not valid, it is kept at its current
14469 @subsection Examples
14471 Stretch video contrast to use the full dynamic range, with no temporal
14472 smoothing; may flicker depending on the source content:
14474 normalize=blackpt=black:whitept=white:smoothing=0
14477 As above, but with 50 frames of temporal smoothing; flicker should be
14478 reduced, depending on the source content:
14480 normalize=blackpt=black:whitept=white:smoothing=50
14483 As above, but with hue-preserving linked channel normalization:
14485 normalize=blackpt=black:whitept=white:smoothing=50:independence=0
14488 As above, but with half strength:
14490 normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
14493 Map the darkest input color to red, the brightest input color to cyan:
14495 normalize=blackpt=red:whitept=cyan
14500 Pass the video source unchanged to the output.
14503 Optical Character Recognition
14505 This filter uses Tesseract for optical character recognition. To enable
14506 compilation of this filter, you need to configure FFmpeg with
14507 @code{--enable-libtesseract}.
14509 It accepts the following options:
14513 Set datapath to tesseract data. Default is to use whatever was
14514 set at installation.
14517 Set language, default is "eng".
14520 Set character whitelist.
14523 Set character blacklist.
14526 The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
14527 The filter exports confidence of recognized words as the frame metadata @code{lavfi.ocr.confidence}.
14531 Apply a video transform using libopencv.
14533 To enable this filter, install the libopencv library and headers and
14534 configure FFmpeg with @code{--enable-libopencv}.
14536 It accepts the following parameters:
14541 The name of the libopencv filter to apply.
14543 @item filter_params
14544 The parameters to pass to the libopencv filter. If not specified, the default
14545 values are assumed.
14549 Refer to the official libopencv documentation for more precise
14551 @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
14553 Several libopencv filters are supported; see the following subsections.
14558 Dilate an image by using a specific structuring element.
14559 It corresponds to the libopencv function @code{cvDilate}.
14561 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
14563 @var{struct_el} represents a structuring element, and has the syntax:
14564 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
14566 @var{cols} and @var{rows} represent the number of columns and rows of
14567 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
14568 point, and @var{shape} the shape for the structuring element. @var{shape}
14569 must be "rect", "cross", "ellipse", or "custom".
14571 If the value for @var{shape} is "custom", it must be followed by a
14572 string of the form "=@var{filename}". The file with name
14573 @var{filename} is assumed to represent a binary image, with each
14574 printable character corresponding to a bright pixel. When a custom
14575 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
14576 or columns and rows of the read file are assumed instead.
14578 The default value for @var{struct_el} is "3x3+0x0/rect".
14580 @var{nb_iterations} specifies the number of times the transform is
14581 applied to the image, and defaults to 1.
14585 # Use the default values
14588 # Dilate using a structuring element with a 5x5 cross, iterating two times
14589 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
14591 # Read the shape from the file diamond.shape, iterating two times.
14592 # The file diamond.shape may contain a pattern of characters like this
14598 # The specified columns and rows are ignored
14599 # but the anchor point coordinates are not
14600 ocv=dilate:0x0+2x2/custom=diamond.shape|2
14605 Erode an image by using a specific structuring element.
14606 It corresponds to the libopencv function @code{cvErode}.
14608 It accepts the parameters: @var{struct_el}:@var{nb_iterations},
14609 with the same syntax and semantics as the @ref{dilate} filter.
14613 Smooth the input video.
14615 The filter takes the following parameters:
14616 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
14618 @var{type} is the type of smooth filter to apply, and must be one of
14619 the following values: "blur", "blur_no_scale", "median", "gaussian",
14620 or "bilateral". The default value is "gaussian".
14622 The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
14623 depends on the smooth type. @var{param1} and
14624 @var{param2} accept integer positive values or 0. @var{param3} and
14625 @var{param4} accept floating point values.
14627 The default value for @var{param1} is 3. The default value for the
14628 other parameters is 0.
14630 These parameters correspond to the parameters assigned to the
14631 libopencv function @code{cvSmooth}.
14633 @section oscilloscope
14635 2D Video Oscilloscope.
14637 Useful to measure spatial impulse, step responses, chroma delays, etc.
14639 It accepts the following parameters:
14643 Set scope center x position.
14646 Set scope center y position.
14649 Set scope size, relative to frame diagonal.
14652 Set scope tilt/rotation.
14658 Set trace center x position.
14661 Set trace center y position.
14664 Set trace width, relative to width of frame.
14667 Set trace height, relative to height of frame.
14670 Set which components to trace. By default it traces first three components.
14673 Draw trace grid. By default is enabled.
14676 Draw some statistics. By default is enabled.
14679 Draw scope. By default is enabled.
14682 @subsection Commands
14683 This filter supports same @ref{commands} as options.
14684 The command accepts the same syntax of the corresponding option.
14686 If the specified expression is not valid, it is kept at its current
14689 @subsection Examples
14693 Inspect full first row of video frame.
14695 oscilloscope=x=0.5:y=0:s=1
14699 Inspect full last row of video frame.
14701 oscilloscope=x=0.5:y=1:s=1
14705 Inspect full 5th line of video frame of height 1080.
14707 oscilloscope=x=0.5:y=5/1080:s=1
14711 Inspect full last column of video frame.
14713 oscilloscope=x=1:y=0.5:s=1:t=1
14721 Overlay one video on top of another.
14723 It takes two inputs and has one output. The first input is the "main"
14724 video on which the second input is overlaid.
14726 It accepts the following parameters:
14728 A description of the accepted options follows.
14733 Set the expression for the x and y coordinates of the overlaid video
14734 on the main video. Default value is "0" for both expressions. In case
14735 the expression is invalid, it is set to a huge value (meaning that the
14736 overlay will not be displayed within the output visible area).
14739 See @ref{framesync}.
14742 Set when the expressions for @option{x}, and @option{y} are evaluated.
14744 It accepts the following values:
14747 only evaluate expressions once during the filter initialization or
14748 when a command is processed
14751 evaluate expressions for each incoming frame
14754 Default value is @samp{frame}.
14757 See @ref{framesync}.
14760 Set the format for the output video.
14762 It accepts the following values:
14765 force YUV420 output
14768 force YUV420p10 output
14771 force YUV422 output
14774 force YUV422p10 output
14777 force YUV444 output
14780 force packed RGB output
14783 force planar RGB output
14786 automatically pick format
14789 Default value is @samp{yuv420}.
14792 See @ref{framesync}.
14795 Set format of alpha of the overlaid video, it can be @var{straight} or
14796 @var{premultiplied}. Default is @var{straight}.
14799 The @option{x}, and @option{y} expressions can contain the following
14805 The main input width and height.
14809 The overlay input width and height.
14813 The computed values for @var{x} and @var{y}. They are evaluated for
14818 horizontal and vertical chroma subsample values of the output
14819 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
14823 the number of input frame, starting from 0
14826 the position in the file of the input frame, NAN if unknown
14829 The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
14833 This filter also supports the @ref{framesync} options.
14835 Note that the @var{n}, @var{pos}, @var{t} variables are available only
14836 when evaluation is done @emph{per frame}, and will evaluate to NAN
14837 when @option{eval} is set to @samp{init}.
14839 Be aware that frames are taken from each input video in timestamp
14840 order, hence, if their initial timestamps differ, it is a good idea
14841 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
14842 have them begin in the same zero timestamp, as the example for
14843 the @var{movie} filter does.
14845 You can chain together more overlays but you should test the
14846 efficiency of such approach.
14848 @subsection Commands
14850 This filter supports the following commands:
14854 Modify the x and y of the overlay input.
14855 The command accepts the same syntax of the corresponding option.
14857 If the specified expression is not valid, it is kept at its current
14861 @subsection Examples
14865 Draw the overlay at 10 pixels from the bottom right corner of the main
14868 overlay=main_w-overlay_w-10:main_h-overlay_h-10
14871 Using named options the example above becomes:
14873 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
14877 Insert a transparent PNG logo in the bottom left corner of the input,
14878 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
14880 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
14884 Insert 2 different transparent PNG logos (second logo on bottom
14885 right corner) using the @command{ffmpeg} tool:
14887 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
14891 Add a transparent color layer on top of the main video; @code{WxH}
14892 must specify the size of the main input to the overlay filter:
14894 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
14898 Play an original video and a filtered version (here with the deshake
14899 filter) side by side using the @command{ffplay} tool:
14901 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
14904 The above command is the same as:
14906 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
14910 Make a sliding overlay appearing from the left to the right top part of the
14911 screen starting since time 2:
14913 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
14917 Compose output by putting two input videos side to side:
14919 ffmpeg -i left.avi -i right.avi -filter_complex "
14920 nullsrc=size=200x100 [background];
14921 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
14922 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
14923 [background][left] overlay=shortest=1 [background+left];
14924 [background+left][right] overlay=shortest=1:x=100 [left+right]
14929 Mask 10-20 seconds of a video by applying the delogo filter to a section
14931 ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
14932 -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]'
14937 Chain several overlays in cascade:
14939 nullsrc=s=200x200 [bg];
14940 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
14941 [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
14942 [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
14943 [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
14944 [in3] null, [mid2] overlay=100:100 [out0]
14949 @anchor{overlay_cuda}
14950 @section overlay_cuda
14952 Overlay one video on top of another.
14954 This is the CUDA variant of the @ref{overlay} filter.
14955 It only accepts CUDA frames. The underlying input pixel formats have to match.
14957 It takes two inputs and has one output. The first input is the "main"
14958 video on which the second input is overlaid.
14960 It accepts the following parameters:
14965 Set the x and y coordinates of the overlaid video on the main video.
14966 Default value is "0" for both expressions.
14969 See @ref{framesync}.
14972 See @ref{framesync}.
14975 See @ref{framesync}.
14979 This filter also supports the @ref{framesync} options.
14983 Apply Overcomplete Wavelet denoiser.
14985 The filter accepts the following options:
14991 Larger depth values will denoise lower frequency components more, but
14992 slow down filtering.
14994 Must be an int in the range 8-16, default is @code{8}.
14996 @item luma_strength, ls
14999 Must be a double value in the range 0-1000, default is @code{1.0}.
15001 @item chroma_strength, cs
15002 Set chroma strength.
15004 Must be a double value in the range 0-1000, default is @code{1.0}.
15010 Add paddings to the input image, and place the original input at the
15011 provided @var{x}, @var{y} coordinates.
15013 It accepts the following parameters:
15018 Specify an expression for the size of the output image with the
15019 paddings added. If the value for @var{width} or @var{height} is 0, the
15020 corresponding input size is used for the output.
15022 The @var{width} expression can reference the value set by the
15023 @var{height} expression, and vice versa.
15025 The default value of @var{width} and @var{height} is 0.
15029 Specify the offsets to place the input image at within the padded area,
15030 with respect to the top/left border of the output image.
15032 The @var{x} expression can reference the value set by the @var{y}
15033 expression, and vice versa.
15035 The default value of @var{x} and @var{y} is 0.
15037 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
15038 so the input image is centered on the padded area.
15041 Specify the color of the padded area. For the syntax of this option,
15042 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
15043 manual,ffmpeg-utils}.
15045 The default value of @var{color} is "black".
15048 Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression.
15050 It accepts the following values:
15054 Only evaluate expressions once during the filter initialization or when
15055 a command is processed.
15058 Evaluate expressions for each incoming frame.
15062 Default value is @samp{init}.
15065 Pad to aspect instead to a resolution.
15069 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
15070 options are expressions containing the following constants:
15075 The input video width and height.
15079 These are the same as @var{in_w} and @var{in_h}.
15083 The output width and height (the size of the padded area), as
15084 specified by the @var{width} and @var{height} expressions.
15088 These are the same as @var{out_w} and @var{out_h}.
15092 The x and y offsets as specified by the @var{x} and @var{y}
15093 expressions, or NAN if not yet specified.
15096 same as @var{iw} / @var{ih}
15099 input sample aspect ratio
15102 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
15106 The horizontal and vertical chroma subsample values. For example for the
15107 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
15110 @subsection Examples
15114 Add paddings with the color "violet" to the input video. The output video
15115 size is 640x480, and the top-left corner of the input video is placed at
15118 pad=640:480:0:40:violet
15121 The example above is equivalent to the following command:
15123 pad=width=640:height=480:x=0:y=40:color=violet
15127 Pad the input to get an output with dimensions increased by 3/2,
15128 and put the input video at the center of the padded area:
15130 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
15134 Pad the input to get a squared output with size equal to the maximum
15135 value between the input width and height, and put the input video at
15136 the center of the padded area:
15138 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
15142 Pad the input to get a final w/h ratio of 16:9:
15144 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
15148 In case of anamorphic video, in order to set the output display aspect
15149 correctly, it is necessary to use @var{sar} in the expression,
15150 according to the relation:
15152 (ih * X / ih) * sar = output_dar
15153 X = output_dar / sar
15156 Thus the previous example needs to be modified to:
15158 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
15162 Double the output size and put the input video in the bottom-right
15163 corner of the output padded area:
15165 pad="2*iw:2*ih:ow-iw:oh-ih"
15169 @anchor{palettegen}
15170 @section palettegen
15172 Generate one palette for a whole video stream.
15174 It accepts the following options:
15178 Set the maximum number of colors to quantize in the palette.
15179 Note: the palette will still contain 256 colors; the unused palette entries
15182 @item reserve_transparent
15183 Create a palette of 255 colors maximum and reserve the last one for
15184 transparency. Reserving the transparency color is useful for GIF optimization.
15185 If not set, the maximum of colors in the palette will be 256. You probably want
15186 to disable this option for a standalone image.
15189 @item transparency_color
15190 Set the color that will be used as background for transparency.
15193 Set statistics mode.
15195 It accepts the following values:
15198 Compute full frame histograms.
15200 Compute histograms only for the part that differs from previous frame. This
15201 might be relevant to give more importance to the moving part of your input if
15202 the background is static.
15204 Compute new histogram for each frame.
15207 Default value is @var{full}.
15210 The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
15211 (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
15212 color quantization of the palette. This information is also visible at
15213 @var{info} logging level.
15215 @subsection Examples
15219 Generate a representative palette of a given video using @command{ffmpeg}:
15221 ffmpeg -i input.mkv -vf palettegen palette.png
15225 @section paletteuse
15227 Use a palette to downsample an input video stream.
15229 The filter takes two inputs: one video stream and a palette. The palette must
15230 be a 256 pixels image.
15232 It accepts the following options:
15236 Select dithering mode. Available algorithms are:
15239 Ordered 8x8 bayer dithering (deterministic)
15241 Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
15242 Note: this dithering is sometimes considered "wrong" and is included as a
15244 @item floyd_steinberg
15245 Floyd and Steingberg dithering (error diffusion)
15247 Frankie Sierra dithering v2 (error diffusion)
15249 Frankie Sierra dithering v2 "Lite" (error diffusion)
15252 Default is @var{sierra2_4a}.
15255 When @var{bayer} dithering is selected, this option defines the scale of the
15256 pattern (how much the crosshatch pattern is visible). A low value means more
15257 visible pattern for less banding, and higher value means less visible pattern
15258 at the cost of more banding.
15260 The option must be an integer value in the range [0,5]. Default is @var{2}.
15263 If set, define the zone to process
15267 Only the changing rectangle will be reprocessed. This is similar to GIF
15268 cropping/offsetting compression mechanism. This option can be useful for speed
15269 if only a part of the image is changing, and has use cases such as limiting the
15270 scope of the error diffusal @option{dither} to the rectangle that bounds the
15271 moving scene (it leads to more deterministic output if the scene doesn't change
15272 much, and as a result less moving noise and better GIF compression).
15275 Default is @var{none}.
15278 Take new palette for each output frame.
15280 @item alpha_threshold
15281 Sets the alpha threshold for transparency. Alpha values above this threshold
15282 will be treated as completely opaque, and values below this threshold will be
15283 treated as completely transparent.
15285 The option must be an integer value in the range [0,255]. Default is @var{128}.
15288 @subsection Examples
15292 Use a palette (generated for example with @ref{palettegen}) to encode a GIF
15293 using @command{ffmpeg}:
15295 ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
15299 @section perspective
15301 Correct perspective of video not recorded perpendicular to the screen.
15303 A description of the accepted parameters follows.
15314 Set coordinates expression for top left, top right, bottom left and bottom right corners.
15315 Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
15316 If the @code{sense} option is set to @code{source}, then the specified points will be sent
15317 to the corners of the destination. If the @code{sense} option is set to @code{destination},
15318 then the corners of the source will be sent to the specified coordinates.
15320 The expressions can use the following variables:
15325 the width and height of video frame.
15329 Output frame count.
15332 @item interpolation
15333 Set interpolation for perspective correction.
15335 It accepts the following values:
15341 Default value is @samp{linear}.
15344 Set interpretation of coordinate options.
15346 It accepts the following values:
15350 Send point in the source specified by the given coordinates to
15351 the corners of the destination.
15353 @item 1, destination
15355 Send the corners of the source to the point in the destination specified
15356 by the given coordinates.
15358 Default value is @samp{source}.
15362 Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
15364 It accepts the following values:
15367 only evaluate expressions once during the filter initialization or
15368 when a command is processed
15371 evaluate expressions for each incoming frame
15374 Default value is @samp{init}.
15379 Delay interlaced video by one field time so that the field order changes.
15381 The intended use is to fix PAL movies that have been captured with the
15382 opposite field order to the film-to-video transfer.
15384 A description of the accepted parameters follows.
15390 It accepts the following values:
15393 Capture field order top-first, transfer bottom-first.
15394 Filter will delay the bottom field.
15397 Capture field order bottom-first, transfer top-first.
15398 Filter will delay the top field.
15401 Capture and transfer with the same field order. This mode only exists
15402 for the documentation of the other options to refer to, but if you
15403 actually select it, the filter will faithfully do nothing.
15406 Capture field order determined automatically by field flags, transfer
15408 Filter selects among @samp{t} and @samp{b} modes on a frame by frame
15409 basis using field flags. If no field information is available,
15410 then this works just like @samp{u}.
15413 Capture unknown or varying, transfer opposite.
15414 Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
15415 analyzing the images and selecting the alternative that produces best
15416 match between the fields.
15419 Capture top-first, transfer unknown or varying.
15420 Filter selects among @samp{t} and @samp{p} using image analysis.
15423 Capture bottom-first, transfer unknown or varying.
15424 Filter selects among @samp{b} and @samp{p} using image analysis.
15427 Capture determined by field flags, transfer unknown or varying.
15428 Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
15429 image analysis. If no field information is available, then this works just
15430 like @samp{U}. This is the default mode.
15433 Both capture and transfer unknown or varying.
15434 Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
15438 @section photosensitivity
15439 Reduce various flashes in video, so to help users with epilepsy.
15441 It accepts the following options:
15444 Set how many frames to use when filtering. Default is 30.
15447 Set detection threshold factor. Default is 1.
15451 Set how many pixels to skip when sampling frames. Default is 1.
15452 Allowed range is from 1 to 1024.
15455 Leave frames unchanged. Default is disabled.
15458 @section pixdesctest
15460 Pixel format descriptor test filter, mainly useful for internal
15461 testing. The output video should be equal to the input video.
15465 format=monow, pixdesctest
15468 can be used to test the monowhite pixel format descriptor definition.
15472 Display sample values of color channels. Mainly useful for checking color
15473 and levels. Minimum supported resolution is 640x480.
15475 The filters accept the following options:
15479 Set scope X position, relative offset on X axis.
15482 Set scope Y position, relative offset on Y axis.
15491 Set window opacity. This window also holds statistics about pixel area.
15494 Set window X position, relative offset on X axis.
15497 Set window Y position, relative offset on Y axis.
15502 Enable the specified chain of postprocessing subfilters using libpostproc. This
15503 library should be automatically selected with a GPL build (@code{--enable-gpl}).
15504 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
15505 Each subfilter and some options have a short and a long name that can be used
15506 interchangeably, i.e. dr/dering are the same.
15508 The filters accept the following options:
15512 Set postprocessing subfilters string.
15515 All subfilters share common options to determine their scope:
15519 Honor the quality commands for this subfilter.
15522 Do chrominance filtering, too (default).
15525 Do luminance filtering only (no chrominance).
15528 Do chrominance filtering only (no luminance).
15531 These options can be appended after the subfilter name, separated by a '|'.
15533 Available subfilters are:
15536 @item hb/hdeblock[|difference[|flatness]]
15537 Horizontal deblocking filter
15540 Difference factor where higher values mean more deblocking (default: @code{32}).
15542 Flatness threshold where lower values mean more deblocking (default: @code{39}).
15545 @item vb/vdeblock[|difference[|flatness]]
15546 Vertical deblocking filter
15549 Difference factor where higher values mean more deblocking (default: @code{32}).
15551 Flatness threshold where lower values mean more deblocking (default: @code{39}).
15554 @item ha/hadeblock[|difference[|flatness]]
15555 Accurate horizontal deblocking filter
15558 Difference factor where higher values mean more deblocking (default: @code{32}).
15560 Flatness threshold where lower values mean more deblocking (default: @code{39}).
15563 @item va/vadeblock[|difference[|flatness]]
15564 Accurate vertical deblocking filter
15567 Difference factor where higher values mean more deblocking (default: @code{32}).
15569 Flatness threshold where lower values mean more deblocking (default: @code{39}).
15573 The horizontal and vertical deblocking filters share the difference and
15574 flatness values so you cannot set different horizontal and vertical
15578 @item h1/x1hdeblock
15579 Experimental horizontal deblocking filter
15581 @item v1/x1vdeblock
15582 Experimental vertical deblocking filter
15587 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
15590 larger -> stronger filtering
15592 larger -> stronger filtering
15594 larger -> stronger filtering
15597 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
15600 Stretch luminance to @code{0-255}.
15603 @item lb/linblenddeint
15604 Linear blend deinterlacing filter that deinterlaces the given block by
15605 filtering all lines with a @code{(1 2 1)} filter.
15607 @item li/linipoldeint
15608 Linear interpolating deinterlacing filter that deinterlaces the given block by
15609 linearly interpolating every second line.
15611 @item ci/cubicipoldeint
15612 Cubic interpolating deinterlacing filter deinterlaces the given block by
15613 cubically interpolating every second line.
15615 @item md/mediandeint
15616 Median deinterlacing filter that deinterlaces the given block by applying a
15617 median filter to every second line.
15619 @item fd/ffmpegdeint
15620 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
15621 second line with a @code{(-1 4 2 4 -1)} filter.
15624 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
15625 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
15627 @item fq/forceQuant[|quantizer]
15628 Overrides the quantizer table from the input with the constant quantizer you
15636 Default pp filter combination (@code{hb|a,vb|a,dr|a})
15639 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
15642 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
15645 @subsection Examples
15649 Apply horizontal and vertical deblocking, deringing and automatic
15650 brightness/contrast:
15656 Apply default filters without brightness/contrast correction:
15662 Apply default filters and temporal denoiser:
15664 pp=default/tmpnoise|1|2|3
15668 Apply deblocking on luminance only, and switch vertical deblocking on or off
15669 automatically depending on available CPU time:
15676 Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
15677 similar to spp = 6 with 7 point DCT, where only the center sample is
15680 The filter accepts the following options:
15684 Force a constant quantization parameter. It accepts an integer in range
15685 0 to 63. If not set, the filter will use the QP from the video stream
15689 Set thresholding mode. Available modes are:
15693 Set hard thresholding.
15695 Set soft thresholding (better de-ringing effect, but likely blurrier).
15697 Set medium thresholding (good results, default).
15701 @section premultiply
15702 Apply alpha premultiply effect to input video stream using first plane
15703 of second stream as alpha.
15705 Both streams must have same dimensions and same pixel format.
15707 The filter accepts the following option:
15711 Set which planes will be processed, unprocessed planes will be copied.
15712 By default value 0xf, all planes will be processed.
15715 Do not require 2nd input for processing, instead use alpha plane from input stream.
15719 Apply prewitt operator to input video stream.
15721 The filter accepts the following option:
15725 Set which planes will be processed, unprocessed planes will be copied.
15726 By default value 0xf, all planes will be processed.
15729 Set value which will be multiplied with filtered result.
15732 Set value which will be added to filtered result.
15735 @section pseudocolor
15737 Alter frame colors in video with pseudocolors.
15739 This filter accepts the following options:
15743 set pixel first component expression
15746 set pixel second component expression
15749 set pixel third component expression
15752 set pixel fourth component expression, corresponds to the alpha component
15755 set component to use as base for altering colors
15758 Each of them specifies the expression to use for computing the lookup table for
15759 the corresponding pixel component values.
15761 The expressions can contain the following constants and functions:
15766 The input width and height.
15769 The input value for the pixel component.
15771 @item ymin, umin, vmin, amin
15772 The minimum allowed component value.
15774 @item ymax, umax, vmax, amax
15775 The maximum allowed component value.
15778 All expressions default to "val".
15780 @subsection Examples
15784 Change too high luma values to gradient:
15786 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'"
15792 Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
15793 Ratio) between two input videos.
15795 This filter takes in input two input videos, the first input is
15796 considered the "main" source and is passed unchanged to the
15797 output. The second input is used as a "reference" video for computing
15800 Both video inputs must have the same resolution and pixel format for
15801 this filter to work correctly. Also it assumes that both inputs
15802 have the same number of frames, which are compared one by one.
15804 The obtained average PSNR is printed through the logging system.
15806 The filter stores the accumulated MSE (mean squared error) of each
15807 frame, and at the end of the processing it is averaged across all frames
15808 equally, and the following formula is applied to obtain the PSNR:
15811 PSNR = 10*log10(MAX^2/MSE)
15814 Where MAX is the average of the maximum values of each component of the
15817 The description of the accepted parameters follows.
15820 @item stats_file, f
15821 If specified the filter will use the named file to save the PSNR of
15822 each individual frame. When filename equals "-" the data is sent to
15825 @item stats_version
15826 Specifies which version of the stats file format to use. Details of
15827 each format are written below.
15828 Default value is 1.
15830 @item stats_add_max
15831 Determines whether the max value is output to the stats log.
15832 Default value is 0.
15833 Requires stats_version >= 2. If this is set and stats_version < 2,
15834 the filter will return an error.
15837 This filter also supports the @ref{framesync} options.
15839 The file printed if @var{stats_file} is selected, contains a sequence of
15840 key/value pairs of the form @var{key}:@var{value} for each compared
15843 If a @var{stats_version} greater than 1 is specified, a header line precedes
15844 the list of per-frame-pair stats, with key value pairs following the frame
15845 format with the following parameters:
15848 @item psnr_log_version
15849 The version of the log file format. Will match @var{stats_version}.
15852 A comma separated list of the per-frame-pair parameters included in
15856 A description of each shown per-frame-pair parameter follows:
15860 sequential number of the input frame, starting from 1
15863 Mean Square Error pixel-by-pixel average difference of the compared
15864 frames, averaged over all the image components.
15866 @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
15867 Mean Square Error pixel-by-pixel average difference of the compared
15868 frames for the component specified by the suffix.
15870 @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
15871 Peak Signal to Noise ratio of the compared frames for the component
15872 specified by the suffix.
15874 @item max_avg, max_y, max_u, max_v
15875 Maximum allowed value for each channel, and average over all
15879 @subsection Examples
15884 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
15885 [main][ref] psnr="stats_file=stats.log" [out]
15888 On this example the input file being processed is compared with the
15889 reference file @file{ref_movie.mpg}. The PSNR of each individual frame
15890 is stored in @file{stats.log}.
15893 Another example with different containers:
15895 ffmpeg -i main.mpg -i ref.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]psnr" -f null -
15902 Pulldown reversal (inverse telecine) filter, capable of handling mixed
15903 hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
15906 The pullup filter is designed to take advantage of future context in making
15907 its decisions. This filter is stateless in the sense that it does not lock
15908 onto a pattern to follow, but it instead looks forward to the following
15909 fields in order to identify matches and rebuild progressive frames.
15911 To produce content with an even framerate, insert the fps filter after
15912 pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
15913 @code{fps=24} for 30fps and the (rare) telecined 25fps input.
15915 The filter accepts the following options:
15922 These options set the amount of "junk" to ignore at the left, right, top, and
15923 bottom of the image, respectively. Left and right are in units of 8 pixels,
15924 while top and bottom are in units of 2 lines.
15925 The default is 8 pixels on each side.
15928 Set the strict breaks. Setting this option to 1 will reduce the chances of
15929 filter generating an occasional mismatched frame, but it may also cause an
15930 excessive number of frames to be dropped during high motion sequences.
15931 Conversely, setting it to -1 will make filter match fields more easily.
15932 This may help processing of video where there is slight blurring between
15933 the fields, but may also cause there to be interlaced frames in the output.
15934 Default value is @code{0}.
15937 Set the metric plane to use. It accepts the following values:
15943 Use chroma blue plane.
15946 Use chroma red plane.
15949 This option may be set to use chroma plane instead of the default luma plane
15950 for doing filter's computations. This may improve accuracy on very clean
15951 source material, but more likely will decrease accuracy, especially if there
15952 is chroma noise (rainbow effect) or any grayscale video.
15953 The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
15954 load and make pullup usable in realtime on slow machines.
15957 For best results (without duplicated frames in the output file) it is
15958 necessary to change the output frame rate. For example, to inverse
15959 telecine NTSC input:
15961 ffmpeg -i input -vf pullup -r 24000/1001 ...
15966 Change video quantization parameters (QP).
15968 The filter accepts the following option:
15972 Set expression for quantization parameter.
15975 The expression is evaluated through the eval API and can contain, among others,
15976 the following constants:
15980 1 if index is not 129, 0 otherwise.
15983 Sequential index starting from -129 to 128.
15986 @subsection Examples
15990 Some equation like:
15998 Flush video frames from internal cache of frames into a random order.
15999 No frame is discarded.
16000 Inspired by @ref{frei0r} nervous filter.
16004 Set size in number of frames of internal cache, in range from @code{2} to
16005 @code{512}. Default is @code{30}.
16008 Set seed for random number generator, must be an integer included between
16009 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
16010 less than @code{0}, the filter will try to use a good random seed on a
16014 @section readeia608
16016 Read closed captioning (EIA-608) information from the top lines of a video frame.
16018 This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and
16019 @code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line
16020 with EIA-608 data (starting from 0). A description of each metadata value follows:
16023 @item lavfi.readeia608.X.cc
16024 The two bytes stored as EIA-608 data (printed in hexadecimal).
16026 @item lavfi.readeia608.X.line
16027 The number of the line on which the EIA-608 data was identified and read.
16030 This filter accepts the following options:
16034 Set the line to start scanning for EIA-608 data. Default is @code{0}.
16037 Set the line to end scanning for EIA-608 data. Default is @code{29}.
16040 Set the ratio of width reserved for sync code detection.
16041 Default is @code{0.27}. Allowed range is @code{[0.1 - 0.7]}.
16044 Enable checking the parity bit. In the event of a parity error, the filter will output
16045 @code{0x00} for that character. Default is false.
16048 Lowpass lines prior to further processing. Default is enabled.
16051 @subsection Commands
16053 This filter supports the all above options as @ref{commands}.
16055 @subsection Examples
16059 Output a csv with presentation time and the first two lines of identified EIA-608 captioning data.
16061 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
16067 Read vertical interval timecode (VITC) information from the top lines of a
16070 The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
16071 timecode value, if a valid timecode has been detected. Further metadata key
16072 @code{lavfi.readvitc.found} is set to 0/1 depending on whether
16073 timecode data has been found or not.
16075 This filter accepts the following options:
16079 Set the maximum number of lines to scan for VITC data. If the value is set to
16080 @code{-1} the full video frame is scanned. Default is @code{45}.
16083 Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
16084 default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
16087 Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
16088 default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
16091 @subsection Examples
16095 Detect and draw VITC data onto the video frame; if no valid VITC is detected,
16096 draw @code{--:--:--:--} as a placeholder:
16098 ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
16104 Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
16106 Destination pixel at position (X, Y) will be picked from source (x, y) position
16107 where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
16108 value for pixel will be used for destination pixel.
16110 Xmap and Ymap input video streams must be of same dimensions. Output video stream
16111 will have Xmap/Ymap video stream dimensions.
16112 Xmap and Ymap input video streams are 16bit depth, single channel.
16116 Specify pixel format of output from this filter. Can be @code{color} or @code{gray}.
16117 Default is @code{color}.
16120 Specify the color of the unmapped pixels. For the syntax of this option,
16121 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
16122 manual,ffmpeg-utils}. Default color is @code{black}.
16125 @section removegrain
16127 The removegrain filter is a spatial denoiser for progressive video.
16131 Set mode for the first plane.
16134 Set mode for the second plane.
16137 Set mode for the third plane.
16140 Set mode for the fourth plane.
16143 Range of mode is from 0 to 24. Description of each mode follows:
16147 Leave input plane unchanged. Default.
16150 Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
16153 Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
16156 Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
16159 Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
16160 This is equivalent to a median filter.
16163 Line-sensitive clipping giving the minimal change.
16166 Line-sensitive clipping, intermediate.
16169 Line-sensitive clipping, intermediate.
16172 Line-sensitive clipping, intermediate.
16175 Line-sensitive clipping on a line where the neighbours pixels are the closest.
16178 Replaces the target pixel with the closest neighbour.
16181 [1 2 1] horizontal and vertical kernel blur.
16187 Bob mode, interpolates top field from the line where the neighbours
16188 pixels are the closest.
16191 Bob mode, interpolates bottom field from the line where the neighbours
16192 pixels are the closest.
16195 Bob mode, interpolates top field. Same as 13 but with a more complicated
16196 interpolation formula.
16199 Bob mode, interpolates bottom field. Same as 14 but with a more complicated
16200 interpolation formula.
16203 Clips the pixel with the minimum and maximum of respectively the maximum and
16204 minimum of each pair of opposite neighbour pixels.
16207 Line-sensitive clipping using opposite neighbours whose greatest distance from
16208 the current pixel is minimal.
16211 Replaces the pixel with the average of its 8 neighbours.
16214 Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
16217 Clips pixels using the averages of opposite neighbour.
16220 Same as mode 21 but simpler and faster.
16223 Small edge and halo removal, but reputed useless.
16229 @section removelogo
16231 Suppress a TV station logo, using an image file to determine which
16232 pixels comprise the logo. It works by filling in the pixels that
16233 comprise the logo with neighboring pixels.
16235 The filter accepts the following options:
16239 Set the filter bitmap file, which can be any image format supported by
16240 libavformat. The width and height of the image file must match those of the
16241 video stream being processed.
16244 Pixels in the provided bitmap image with a value of zero are not
16245 considered part of the logo, non-zero pixels are considered part of
16246 the logo. If you use white (255) for the logo and black (0) for the
16247 rest, you will be safe. For making the filter bitmap, it is
16248 recommended to take a screen capture of a black frame with the logo
16249 visible, and then using a threshold filter followed by the erode
16250 filter once or twice.
16252 If needed, little splotches can be fixed manually. Remember that if
16253 logo pixels are not covered, the filter quality will be much
16254 reduced. Marking too many pixels as part of the logo does not hurt as
16255 much, but it will increase the amount of blurring needed to cover over
16256 the image and will destroy more information than necessary, and extra
16257 pixels will slow things down on a large logo.
16259 @section repeatfields
16261 This filter uses the repeat_field flag from the Video ES headers and hard repeats
16262 fields based on its value.
16266 Reverse a video clip.
16268 Warning: This filter requires memory to buffer the entire clip, so trimming
16271 @subsection Examples
16275 Take the first 5 seconds of a clip, and reverse it.
16282 Shift R/G/B/A pixels horizontally and/or vertically.
16284 The filter accepts the following options:
16287 Set amount to shift red horizontally.
16289 Set amount to shift red vertically.
16291 Set amount to shift green horizontally.
16293 Set amount to shift green vertically.
16295 Set amount to shift blue horizontally.
16297 Set amount to shift blue vertically.
16299 Set amount to shift alpha horizontally.
16301 Set amount to shift alpha vertically.
16303 Set edge mode, can be @var{smear}, default, or @var{warp}.
16306 @subsection Commands
16308 This filter supports the all above options as @ref{commands}.
16311 Apply roberts cross operator to input video stream.
16313 The filter accepts the following option:
16317 Set which planes will be processed, unprocessed planes will be copied.
16318 By default value 0xf, all planes will be processed.
16321 Set value which will be multiplied with filtered result.
16324 Set value which will be added to filtered result.
16329 Rotate video by an arbitrary angle expressed in radians.
16331 The filter accepts the following options:
16333 A description of the optional parameters follows.
16336 Set an expression for the angle by which to rotate the input video
16337 clockwise, expressed as a number of radians. A negative value will
16338 result in a counter-clockwise rotation. By default it is set to "0".
16340 This expression is evaluated for each frame.
16343 Set the output width expression, default value is "iw".
16344 This expression is evaluated just once during configuration.
16347 Set the output height expression, default value is "ih".
16348 This expression is evaluated just once during configuration.
16351 Enable bilinear interpolation if set to 1, a value of 0 disables
16352 it. Default value is 1.
16355 Set the color used to fill the output area not covered by the rotated
16356 image. For the general syntax of this option, check the
16357 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
16358 If the special value "none" is selected then no
16359 background is printed (useful for example if the background is never shown).
16361 Default value is "black".
16364 The expressions for the angle and the output size can contain the
16365 following constants and functions:
16369 sequential number of the input frame, starting from 0. It is always NAN
16370 before the first frame is filtered.
16373 time in seconds of the input frame, it is set to 0 when the filter is
16374 configured. It is always NAN before the first frame is filtered.
16378 horizontal and vertical chroma subsample values. For example for the
16379 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16383 the input video width and height
16387 the output width and height, that is the size of the padded area as
16388 specified by the @var{width} and @var{height} expressions
16392 the minimal width/height required for completely containing the input
16393 video rotated by @var{a} radians.
16395 These are only available when computing the @option{out_w} and
16396 @option{out_h} expressions.
16399 @subsection Examples
16403 Rotate the input by PI/6 radians clockwise:
16409 Rotate the input by PI/6 radians counter-clockwise:
16415 Rotate the input by 45 degrees clockwise:
16421 Apply a constant rotation with period T, starting from an angle of PI/3:
16423 rotate=PI/3+2*PI*t/T
16427 Make the input video rotation oscillating with a period of T
16428 seconds and an amplitude of A radians:
16430 rotate=A*sin(2*PI/T*t)
16434 Rotate the video, output size is chosen so that the whole rotating
16435 input video is always completely contained in the output:
16437 rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
16441 Rotate the video, reduce the output size so that no background is ever
16444 rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
16448 @subsection Commands
16450 The filter supports the following commands:
16454 Set the angle expression.
16455 The command accepts the same syntax of the corresponding option.
16457 If the specified expression is not valid, it is kept at its current
16463 Apply Shape Adaptive Blur.
16465 The filter accepts the following options:
16468 @item luma_radius, lr
16469 Set luma blur filter strength, must be a value in range 0.1-4.0, default
16470 value is 1.0. A greater value will result in a more blurred image, and
16471 in slower processing.
16473 @item luma_pre_filter_radius, lpfr
16474 Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
16477 @item luma_strength, ls
16478 Set luma maximum difference between pixels to still be considered, must
16479 be a value in the 0.1-100.0 range, default value is 1.0.
16481 @item chroma_radius, cr
16482 Set chroma blur filter strength, must be a value in range -0.9-4.0. A
16483 greater value will result in a more blurred image, and in slower
16486 @item chroma_pre_filter_radius, cpfr
16487 Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
16489 @item chroma_strength, cs
16490 Set chroma maximum difference between pixels to still be considered,
16491 must be a value in the -0.9-100.0 range.
16494 Each chroma option value, if not explicitly specified, is set to the
16495 corresponding luma option value.
16500 Scale (resize) the input video, using the libswscale library.
16502 The scale filter forces the output display aspect ratio to be the same
16503 of the input, by changing the output sample aspect ratio.
16505 If the input image format is different from the format requested by
16506 the next filter, the scale filter will convert the input to the
16509 @subsection Options
16510 The filter accepts the following options, or any of the options
16511 supported by the libswscale scaler.
16513 See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
16514 the complete list of scaler options.
16519 Set the output video dimension expression. Default value is the input
16522 If the @var{width} or @var{w} value is 0, the input width is used for
16523 the output. If the @var{height} or @var{h} value is 0, the input height
16524 is used for the output.
16526 If one and only one of the values is -n with n >= 1, the scale filter
16527 will use a value that maintains the aspect ratio of the input image,
16528 calculated from the other specified dimension. After that it will,
16529 however, make sure that the calculated dimension is divisible by n and
16530 adjust the value if necessary.
16532 If both values are -n with n >= 1, the behavior will be identical to
16533 both values being set to 0 as previously detailed.
16535 See below for the list of accepted constants for use in the dimension
16539 Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
16543 Only evaluate expressions once during the filter initialization or when a command is processed.
16546 Evaluate expressions for each incoming frame.
16550 Default value is @samp{init}.
16554 Set the interlacing mode. It accepts the following values:
16558 Force interlaced aware scaling.
16561 Do not apply interlaced scaling.
16564 Select interlaced aware scaling depending on whether the source frames
16565 are flagged as interlaced or not.
16568 Default value is @samp{0}.
16571 Set libswscale scaling flags. See
16572 @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
16573 complete list of values. If not explicitly specified the filter applies
16577 @item param0, param1
16578 Set libswscale input parameters for scaling algorithms that need them. See
16579 @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
16580 complete documentation. If not explicitly specified the filter applies
16586 Set the video size. For the syntax of this option, check the
16587 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16589 @item in_color_matrix
16590 @item out_color_matrix
16591 Set in/output YCbCr color space type.
16593 This allows the autodetected value to be overridden as well as allows forcing
16594 a specific value used for the output and encoder.
16596 If not specified, the color space type depends on the pixel format.
16602 Choose automatically.
16605 Format conforming to International Telecommunication Union (ITU)
16606 Recommendation BT.709.
16609 Set color space conforming to the United States Federal Communications
16610 Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
16615 Set color space conforming to:
16619 ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
16622 ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
16625 Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
16630 Set color space conforming to SMPTE ST 240:1999.
16633 Set color space conforming to ITU-R BT.2020 non-constant luminance system.
16638 Set in/output YCbCr sample range.
16640 This allows the autodetected value to be overridden as well as allows forcing
16641 a specific value used for the output and encoder. If not specified, the
16642 range depends on the pixel format. Possible values:
16646 Choose automatically.
16649 Set full range (0-255 in case of 8-bit luma).
16651 @item mpeg/limited/tv
16652 Set "MPEG" range (16-235 in case of 8-bit luma).
16655 @item force_original_aspect_ratio
16656 Enable decreasing or increasing output video width or height if necessary to
16657 keep the original aspect ratio. Possible values:
16661 Scale the video as specified and disable this feature.
16664 The output video dimensions will automatically be decreased if needed.
16667 The output video dimensions will automatically be increased if needed.
16671 One useful instance of this option is that when you know a specific device's
16672 maximum allowed resolution, you can use this to limit the output video to
16673 that, while retaining the aspect ratio. For example, device A allows
16674 1280x720 playback, and your video is 1920x800. Using this option (set it to
16675 decrease) and specifying 1280x720 to the command line makes the output
16678 Please note that this is a different thing than specifying -1 for @option{w}
16679 or @option{h}, you still need to specify the output resolution for this option
16682 @item force_divisible_by
16683 Ensures that both the output dimensions, width and height, are divisible by the
16684 given integer when used together with @option{force_original_aspect_ratio}. This
16685 works similar to using @code{-n} in the @option{w} and @option{h} options.
16687 This option respects the value set for @option{force_original_aspect_ratio},
16688 increasing or decreasing the resolution accordingly. The video's aspect ratio
16689 may be slightly modified.
16691 This option can be handy if you need to have a video fit within or exceed
16692 a defined resolution using @option{force_original_aspect_ratio} but also have
16693 encoder restrictions on width or height divisibility.
16697 The values of the @option{w} and @option{h} options are expressions
16698 containing the following constants:
16703 The input width and height
16707 These are the same as @var{in_w} and @var{in_h}.
16711 The output (scaled) width and height
16715 These are the same as @var{out_w} and @var{out_h}
16718 The same as @var{iw} / @var{ih}
16721 input sample aspect ratio
16724 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
16728 horizontal and vertical input chroma subsample values. For example for the
16729 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16733 horizontal and vertical output chroma subsample values. For example for the
16734 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16737 The (sequential) number of the input frame, starting from 0.
16738 Only available with @code{eval=frame}.
16741 The presentation timestamp of the input frame, expressed as a number of
16742 seconds. Only available with @code{eval=frame}.
16745 The position (byte offset) of the frame in the input stream, or NaN if
16746 this information is unavailable and/or meaningless (for example in case of synthetic video).
16747 Only available with @code{eval=frame}.
16750 @subsection Examples
16754 Scale the input video to a size of 200x100
16759 This is equivalent to:
16770 Specify a size abbreviation for the output size:
16775 which can also be written as:
16781 Scale the input to 2x:
16783 scale=w=2*iw:h=2*ih
16787 The above is the same as:
16789 scale=2*in_w:2*in_h
16793 Scale the input to 2x with forced interlaced scaling:
16795 scale=2*iw:2*ih:interl=1
16799 Scale the input to half size:
16801 scale=w=iw/2:h=ih/2
16805 Increase the width, and set the height to the same size:
16811 Seek Greek harmony:
16818 Increase the height, and set the width to 3/2 of the height:
16820 scale=w=3/2*oh:h=3/5*ih
16824 Increase the size, making the size a multiple of the chroma
16827 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
16831 Increase the width to a maximum of 500 pixels,
16832 keeping the same aspect ratio as the input:
16834 scale=w='min(500\, iw*3/2):h=-1'
16838 Make pixels square by combining scale and setsar:
16840 scale='trunc(ih*dar):ih',setsar=1/1
16844 Make pixels square by combining scale and setsar,
16845 making sure the resulting resolution is even (required by some codecs):
16847 scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1
16851 @subsection Commands
16853 This filter supports the following commands:
16857 Set the output video dimension expression.
16858 The command accepts the same syntax of the corresponding option.
16860 If the specified expression is not valid, it is kept at its current
16866 Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
16867 format conversion on CUDA video frames. Setting the output width and height
16868 works in the same way as for the @var{scale} filter.
16870 The following additional options are accepted:
16873 The pixel format of the output CUDA frames. If set to the string "same" (the
16874 default), the input format will be kept. Note that automatic format negotiation
16875 and conversion is not yet supported for hardware frames
16878 The interpolation algorithm used for resizing. One of the following:
16885 @item cubic2p_bspline
16886 2-parameter cubic (B=1, C=0)
16888 @item cubic2p_catmullrom
16889 2-parameter cubic (B=0, C=1/2)
16891 @item cubic2p_b05c03
16892 2-parameter cubic (B=1/2, C=3/10)
16900 @item force_original_aspect_ratio
16901 Enable decreasing or increasing output video width or height if necessary to
16902 keep the original aspect ratio. Possible values:
16906 Scale the video as specified and disable this feature.
16909 The output video dimensions will automatically be decreased if needed.
16912 The output video dimensions will automatically be increased if needed.
16916 One useful instance of this option is that when you know a specific device's
16917 maximum allowed resolution, you can use this to limit the output video to
16918 that, while retaining the aspect ratio. For example, device A allows
16919 1280x720 playback, and your video is 1920x800. Using this option (set it to
16920 decrease) and specifying 1280x720 to the command line makes the output
16923 Please note that this is a different thing than specifying -1 for @option{w}
16924 or @option{h}, you still need to specify the output resolution for this option
16927 @item force_divisible_by
16928 Ensures that both the output dimensions, width and height, are divisible by the
16929 given integer when used together with @option{force_original_aspect_ratio}. This
16930 works similar to using @code{-n} in the @option{w} and @option{h} options.
16932 This option respects the value set for @option{force_original_aspect_ratio},
16933 increasing or decreasing the resolution accordingly. The video's aspect ratio
16934 may be slightly modified.
16936 This option can be handy if you need to have a video fit within or exceed
16937 a defined resolution using @option{force_original_aspect_ratio} but also have
16938 encoder restrictions on width or height divisibility.
16944 Scale (resize) the input video, based on a reference video.
16946 See the scale filter for available options, scale2ref supports the same but
16947 uses the reference video instead of the main input as basis. scale2ref also
16948 supports the following additional constants for the @option{w} and
16949 @option{h} options:
16954 The main input video's width and height
16957 The same as @var{main_w} / @var{main_h}
16960 The main input video's sample aspect ratio
16962 @item main_dar, mdar
16963 The main input video's display aspect ratio. Calculated from
16964 @code{(main_w / main_h) * main_sar}.
16968 The main input video's horizontal and vertical chroma subsample values.
16969 For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub}
16973 The (sequential) number of the main input frame, starting from 0.
16974 Only available with @code{eval=frame}.
16977 The presentation timestamp of the main input frame, expressed as a number of
16978 seconds. Only available with @code{eval=frame}.
16981 The position (byte offset) of the frame in the main input stream, or NaN if
16982 this information is unavailable and/or meaningless (for example in case of synthetic video).
16983 Only available with @code{eval=frame}.
16986 @subsection Examples
16990 Scale a subtitle stream (b) to match the main video (a) in size before overlaying
16992 'scale2ref[b][a];[a][b]overlay'
16996 Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio.
16998 [logo-in][video-in]scale2ref=w=oh*mdar:h=ih/10[logo-out][video-out]
17002 @subsection Commands
17004 This filter supports the following commands:
17008 Set the output video dimension expression.
17009 The command accepts the same syntax of the corresponding option.
17011 If the specified expression is not valid, it is kept at its current
17016 Scroll input video horizontally and/or vertically by constant speed.
17018 The filter accepts the following options:
17020 @item horizontal, h
17021 Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1.
17022 Negative values changes scrolling direction.
17025 Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1.
17026 Negative values changes scrolling direction.
17029 Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1.
17032 Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1.
17035 @subsection Commands
17037 This filter supports the following @ref{commands}:
17039 @item horizontal, h
17040 Set the horizontal scrolling speed.
17042 Set the vertical scrolling speed.
17048 Detect video scene change.
17050 This filter sets frame metadata with mafd between frame, the scene score, and
17051 forward the frame to the next filter, so they can use these metadata to detect
17052 scene change or others.
17054 In addition, this filter logs a message and sets frame metadata when it detects
17055 a scene change by @option{threshold}.
17057 @code{lavfi.scd.mafd} metadata keys are set with mafd for every frame.
17059 @code{lavfi.scd.score} metadata keys are set with scene change score for every frame
17060 to detect scene change.
17062 @code{lavfi.scd.time} metadata keys are set with current filtered frame time which
17063 detect scene change with @option{threshold}.
17065 The filter accepts the following options:
17069 Set the scene change detection threshold as a percentage of maximum change. Good
17070 values are in the @code{[8.0, 14.0]} range. The range for @option{threshold} is
17073 Default value is @code{10.}.
17076 Set the flag to pass scene change frames to the next filter. Default value is @code{0}
17077 You can enable it if you want to get snapshot of scene change frames only.
17080 @anchor{selectivecolor}
17081 @section selectivecolor
17083 Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
17084 as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
17085 by the "purity" of the color (that is, how saturated it already is).
17087 This filter is similar to the Adobe Photoshop Selective Color tool.
17089 The filter accepts the following options:
17092 @item correction_method
17093 Select color correction method.
17095 Available values are:
17098 Specified adjustments are applied "as-is" (added/subtracted to original pixel
17101 Specified adjustments are relative to the original component value.
17103 Default is @code{absolute}.
17105 Adjustments for red pixels (pixels where the red component is the maximum)
17107 Adjustments for yellow pixels (pixels where the blue component is the minimum)
17109 Adjustments for green pixels (pixels where the green component is the maximum)
17111 Adjustments for cyan pixels (pixels where the red component is the minimum)
17113 Adjustments for blue pixels (pixels where the blue component is the maximum)
17115 Adjustments for magenta pixels (pixels where the green component is the minimum)
17117 Adjustments for white pixels (pixels where all components are greater than 128)
17119 Adjustments for all pixels except pure black and pure white
17121 Adjustments for black pixels (pixels where all components are lesser than 128)
17123 Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
17126 All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
17127 4 space separated floating point adjustment values in the [-1,1] range,
17128 respectively to adjust the amount of cyan, magenta, yellow and black for the
17129 pixels of its range.
17131 @subsection Examples
17135 Increase cyan by 50% and reduce yellow by 33% in every green areas, and
17136 increase magenta by 27% in blue areas:
17138 selectivecolor=greens=.5 0 -.33 0:blues=0 .27
17142 Use a Photoshop selective color preset:
17144 selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
17148 @anchor{separatefields}
17149 @section separatefields
17151 The @code{separatefields} takes a frame-based video input and splits
17152 each frame into its components fields, producing a new half height clip
17153 with twice the frame rate and twice the frame count.
17155 This filter use field-dominance information in frame to decide which
17156 of each pair of fields to place first in the output.
17157 If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
17159 @section setdar, setsar
17161 The @code{setdar} filter sets the Display Aspect Ratio for the filter
17164 This is done by changing the specified Sample (aka Pixel) Aspect
17165 Ratio, according to the following equation:
17167 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
17170 Keep in mind that the @code{setdar} filter does not modify the pixel
17171 dimensions of the video frame. Also, the display aspect ratio set by
17172 this filter may be changed by later filters in the filterchain,
17173 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
17176 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
17177 the filter output video.
17179 Note that as a consequence of the application of this filter, the
17180 output display aspect ratio will change according to the equation
17183 Keep in mind that the sample aspect ratio set by the @code{setsar}
17184 filter may be changed by later filters in the filterchain, e.g. if
17185 another "setsar" or a "setdar" filter is applied.
17187 It accepts the following parameters:
17190 @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
17191 Set the aspect ratio used by the filter.
17193 The parameter can be a floating point number string, an expression, or
17194 a string of the form @var{num}:@var{den}, where @var{num} and
17195 @var{den} are the numerator and denominator of the aspect ratio. If
17196 the parameter is not specified, it is assumed the value "0".
17197 In case the form "@var{num}:@var{den}" is used, the @code{:} character
17201 Set the maximum integer value to use for expressing numerator and
17202 denominator when reducing the expressed aspect ratio to a rational.
17203 Default value is @code{100}.
17207 The parameter @var{sar} is an expression containing
17208 the following constants:
17212 These are approximated values for the mathematical constants e
17213 (Euler's number), pi (Greek pi), and phi (the golden ratio).
17216 The input width and height.
17219 These are the same as @var{w} / @var{h}.
17222 The input sample aspect ratio.
17225 The input display aspect ratio. It is the same as
17226 (@var{w} / @var{h}) * @var{sar}.
17229 Horizontal and vertical chroma subsample values. For example, for the
17230 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
17233 @subsection Examples
17238 To change the display aspect ratio to 16:9, specify one of the following:
17245 To change the sample aspect ratio to 10:11, specify:
17251 To set a display aspect ratio of 16:9, and specify a maximum integer value of
17252 1000 in the aspect ratio reduction, use the command:
17254 setdar=ratio=16/9:max=1000
17262 Force field for the output video frame.
17264 The @code{setfield} filter marks the interlace type field for the
17265 output frames. It does not change the input frame, but only sets the
17266 corresponding property, which affects how the frame is treated by
17267 following filters (e.g. @code{fieldorder} or @code{yadif}).
17269 The filter accepts the following options:
17274 Available values are:
17278 Keep the same field property.
17281 Mark the frame as bottom-field-first.
17284 Mark the frame as top-field-first.
17287 Mark the frame as progressive.
17294 Force frame parameter for the output video frame.
17296 The @code{setparams} filter marks interlace and color range for the
17297 output frames. It does not change the input frame, but only sets the
17298 corresponding property, which affects how the frame is treated by
17303 Available values are:
17307 Keep the same field property (default).
17310 Mark the frame as bottom-field-first.
17313 Mark the frame as top-field-first.
17316 Mark the frame as progressive.
17320 Available values are:
17324 Keep the same color range property (default).
17326 @item unspecified, unknown
17327 Mark the frame as unspecified color range.
17329 @item limited, tv, mpeg
17330 Mark the frame as limited range.
17332 @item full, pc, jpeg
17333 Mark the frame as full range.
17336 @item color_primaries
17337 Set the color primaries.
17338 Available values are:
17342 Keep the same color primaries property (default).
17359 Set the color transfer.
17360 Available values are:
17364 Keep the same color trc property (default).
17386 Set the colorspace.
17387 Available values are:
17391 Keep the same colorspace property (default).
17404 @item chroma-derived-nc
17405 @item chroma-derived-c
17412 Show a line containing various information for each input video frame.
17413 The input video is not modified.
17415 This filter supports the following options:
17419 Calculate checksums of each plane. By default enabled.
17422 The shown line contains a sequence of key/value pairs of the form
17423 @var{key}:@var{value}.
17425 The following values are shown in the output:
17429 The (sequential) number of the input frame, starting from 0.
17432 The Presentation TimeStamp of the input frame, expressed as a number of
17433 time base units. The time base unit depends on the filter input pad.
17436 The Presentation TimeStamp of the input frame, expressed as a number of
17440 The position of the frame in the input stream, or -1 if this information is
17441 unavailable and/or meaningless (for example in case of synthetic video).
17444 The pixel format name.
17447 The sample aspect ratio of the input frame, expressed in the form
17448 @var{num}/@var{den}.
17451 The size of the input frame. For the syntax of this option, check the
17452 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17455 The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
17456 for bottom field first).
17459 This is 1 if the frame is a key frame, 0 otherwise.
17462 The picture type of the input frame ("I" for an I-frame, "P" for a
17463 P-frame, "B" for a B-frame, or "?" for an unknown type).
17464 Also refer to the documentation of the @code{AVPictureType} enum and of
17465 the @code{av_get_picture_type_char} function defined in
17466 @file{libavutil/avutil.h}.
17469 The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
17471 @item plane_checksum
17472 The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
17473 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
17476 The mean value of pixels in each plane of the input frame, expressed in the form
17477 "[@var{mean0} @var{mean1} @var{mean2} @var{mean3}]".
17480 The standard deviation of pixel values in each plane of the input frame, expressed
17481 in the form "[@var{stdev0} @var{stdev1} @var{stdev2} @var{stdev3}]".
17485 @section showpalette
17487 Displays the 256 colors palette of each frame. This filter is only relevant for
17488 @var{pal8} pixel format frames.
17490 It accepts the following option:
17494 Set the size of the box used to represent one palette color entry. Default is
17495 @code{30} (for a @code{30x30} pixel box).
17498 @section shuffleframes
17500 Reorder and/or duplicate and/or drop video frames.
17502 It accepts the following parameters:
17506 Set the destination indexes of input frames.
17507 This is space or '|' separated list of indexes that maps input frames to output
17508 frames. Number of indexes also sets maximal value that each index may have.
17509 '-1' index have special meaning and that is to drop frame.
17512 The first frame has the index 0. The default is to keep the input unchanged.
17514 @subsection Examples
17518 Swap second and third frame of every three frames of the input:
17520 ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
17524 Swap 10th and 1st frame of every ten frames of the input:
17526 ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
17530 @section shuffleplanes
17532 Reorder and/or duplicate video planes.
17534 It accepts the following parameters:
17539 The index of the input plane to be used as the first output plane.
17542 The index of the input plane to be used as the second output plane.
17545 The index of the input plane to be used as the third output plane.
17548 The index of the input plane to be used as the fourth output plane.
17552 The first plane has the index 0. The default is to keep the input unchanged.
17554 @subsection Examples
17558 Swap the second and third planes of the input:
17560 ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
17564 @anchor{signalstats}
17565 @section signalstats
17566 Evaluate various visual metrics that assist in determining issues associated
17567 with the digitization of analog video media.
17569 By default the filter will log these metadata values:
17573 Display the minimal Y value contained within the input frame. Expressed in
17577 Display the Y value at the 10% percentile within the input frame. Expressed in
17581 Display the average Y value within the input frame. Expressed in range of
17585 Display the Y value at the 90% percentile within the input frame. Expressed in
17589 Display the maximum Y value contained within the input frame. Expressed in
17593 Display the minimal U value contained within the input frame. Expressed in
17597 Display the U value at the 10% percentile within the input frame. Expressed in
17601 Display the average U value within the input frame. Expressed in range of
17605 Display the U value at the 90% percentile within the input frame. Expressed in
17609 Display the maximum U value contained within the input frame. Expressed in
17613 Display the minimal V value contained within the input frame. Expressed in
17617 Display the V value at the 10% percentile within the input frame. Expressed in
17621 Display the average V value within the input frame. Expressed in range of
17625 Display the V value at the 90% percentile within the input frame. Expressed in
17629 Display the maximum V value contained within the input frame. Expressed in
17633 Display the minimal saturation value contained within the input frame.
17634 Expressed in range of [0-~181.02].
17637 Display the saturation value at the 10% percentile within the input frame.
17638 Expressed in range of [0-~181.02].
17641 Display the average saturation value within the input frame. Expressed in range
17645 Display the saturation value at the 90% percentile within the input frame.
17646 Expressed in range of [0-~181.02].
17649 Display the maximum saturation value contained within the input frame.
17650 Expressed in range of [0-~181.02].
17653 Display the median value for hue within the input frame. Expressed in range of
17657 Display the average value for hue within the input frame. Expressed in range of
17661 Display the average of sample value difference between all values of the Y
17662 plane in the current frame and corresponding values of the previous input frame.
17663 Expressed in range of [0-255].
17666 Display the average of sample value difference between all values of the U
17667 plane in the current frame and corresponding values of the previous input frame.
17668 Expressed in range of [0-255].
17671 Display the average of sample value difference between all values of the V
17672 plane in the current frame and corresponding values of the previous input frame.
17673 Expressed in range of [0-255].
17676 Display bit depth of Y plane in current frame.
17677 Expressed in range of [0-16].
17680 Display bit depth of U plane in current frame.
17681 Expressed in range of [0-16].
17684 Display bit depth of V plane in current frame.
17685 Expressed in range of [0-16].
17688 The filter accepts the following options:
17694 @option{stat} specify an additional form of image analysis.
17695 @option{out} output video with the specified type of pixel highlighted.
17697 Both options accept the following values:
17701 Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
17702 unlike the neighboring pixels of the same field. Examples of temporal outliers
17703 include the results of video dropouts, head clogs, or tape tracking issues.
17706 Identify @var{vertical line repetition}. Vertical line repetition includes
17707 similar rows of pixels within a frame. In born-digital video vertical line
17708 repetition is common, but this pattern is uncommon in video digitized from an
17709 analog source. When it occurs in video that results from the digitization of an
17710 analog source it can indicate concealment from a dropout compensator.
17713 Identify pixels that fall outside of legal broadcast range.
17717 Set the highlight color for the @option{out} option. The default color is
17721 @subsection Examples
17725 Output data of various video metrics:
17727 ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
17731 Output specific data about the minimum and maximum values of the Y plane per frame:
17733 ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
17737 Playback video while highlighting pixels that are outside of broadcast range in red.
17739 ffplay example.mov -vf signalstats="out=brng:color=red"
17743 Playback video with signalstats metadata drawn over the frame.
17745 ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
17748 The contents of signalstat_drawtext.txt used in the command are:
17751 Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
17752 U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
17753 V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
17754 saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
17762 Calculates the MPEG-7 Video Signature. The filter can handle more than one
17763 input. In this case the matching between the inputs can be calculated additionally.
17764 The filter always passes through the first input. The signature of each stream can
17765 be written into a file.
17767 It accepts the following options:
17771 Enable or disable the matching process.
17773 Available values are:
17777 Disable the calculation of a matching (default).
17779 Calculate the matching for the whole video and output whether the whole video
17780 matches or only parts.
17782 Calculate only until a matching is found or the video ends. Should be faster in
17787 Set the number of inputs. The option value must be a non negative integer.
17788 Default value is 1.
17791 Set the path to which the output is written. If there is more than one input,
17792 the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive
17793 integer), that will be replaced with the input number. If no filename is
17794 specified, no output will be written. This is the default.
17797 Choose the output format.
17799 Available values are:
17803 Use the specified binary representation (default).
17805 Use the specified xml representation.
17809 Set threshold to detect one word as similar. The option value must be an integer
17810 greater than zero. The default value is 9000.
17813 Set threshold to detect all words as similar. The option value must be an integer
17814 greater than zero. The default value is 60000.
17817 Set threshold to detect frames as similar. The option value must be an integer
17818 greater than zero. The default value is 116.
17821 Set the minimum length of a sequence in frames to recognize it as matching
17822 sequence. The option value must be a non negative integer value.
17823 The default value is 0.
17826 Set the minimum relation, that matching frames to all frames must have.
17827 The option value must be a double value between 0 and 1. The default value is 0.5.
17830 @subsection Examples
17834 To calculate the signature of an input video and store it in signature.bin:
17836 ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
17840 To detect whether two videos match and store the signatures in XML format in
17841 signature0.xml and signature1.xml:
17843 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 -
17851 Blur the input video without impacting the outlines.
17853 It accepts the following options:
17856 @item luma_radius, lr
17857 Set the luma radius. The option value must be a float number in
17858 the range [0.1,5.0] that specifies the variance of the gaussian filter
17859 used to blur the image (slower if larger). Default value is 1.0.
17861 @item luma_strength, ls
17862 Set the luma strength. The option value must be a float number
17863 in the range [-1.0,1.0] that configures the blurring. A value included
17864 in [0.0,1.0] will blur the image whereas a value included in
17865 [-1.0,0.0] will sharpen the image. Default value is 1.0.
17867 @item luma_threshold, lt
17868 Set the luma threshold used as a coefficient to determine
17869 whether a pixel should be blurred or not. The option value must be an
17870 integer in the range [-30,30]. A value of 0 will filter all the image,
17871 a value included in [0,30] will filter flat areas and a value included
17872 in [-30,0] will filter edges. Default value is 0.
17874 @item chroma_radius, cr
17875 Set the chroma radius. The option value must be a float number in
17876 the range [0.1,5.0] that specifies the variance of the gaussian filter
17877 used to blur the image (slower if larger). Default value is @option{luma_radius}.
17879 @item chroma_strength, cs
17880 Set the chroma strength. The option value must be a float number
17881 in the range [-1.0,1.0] that configures the blurring. A value included
17882 in [0.0,1.0] will blur the image whereas a value included in
17883 [-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}.
17885 @item chroma_threshold, ct
17886 Set the chroma threshold used as a coefficient to determine
17887 whether a pixel should be blurred or not. The option value must be an
17888 integer in the range [-30,30]. A value of 0 will filter all the image,
17889 a value included in [0,30] will filter flat areas and a value included
17890 in [-30,0] will filter edges. Default value is @option{luma_threshold}.
17893 If a chroma option is not explicitly set, the corresponding luma value
17897 Apply sobel operator to input video stream.
17899 The filter accepts the following option:
17903 Set which planes will be processed, unprocessed planes will be copied.
17904 By default value 0xf, all planes will be processed.
17907 Set value which will be multiplied with filtered result.
17910 Set value which will be added to filtered result.
17916 Apply a simple postprocessing filter that compresses and decompresses the image
17917 at several (or - in the case of @option{quality} level @code{6} - all) shifts
17918 and average the results.
17920 The filter accepts the following options:
17924 Set quality. This option defines the number of levels for averaging. It accepts
17925 an integer in the range 0-6. If set to @code{0}, the filter will have no
17926 effect. A value of @code{6} means the higher quality. For each increment of
17927 that value the speed drops by a factor of approximately 2. Default value is
17931 Force a constant quantization parameter. If not set, the filter will use the QP
17932 from the video stream (if available).
17935 Set thresholding mode. Available modes are:
17939 Set hard thresholding (default).
17941 Set soft thresholding (better de-ringing effect, but likely blurrier).
17944 @item use_bframe_qp
17945 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
17946 option may cause flicker since the B-Frames have often larger QP. Default is
17947 @code{0} (not enabled).
17950 @subsection Commands
17952 This filter supports the following commands:
17954 @item quality, level
17955 Set quality level. The value @code{max} can be used to set the maximum level,
17956 currently @code{6}.
17962 Scale the input by applying one of the super-resolution methods based on
17963 convolutional neural networks. Supported models:
17967 Super-Resolution Convolutional Neural Network model (SRCNN).
17968 See @url{https://arxiv.org/abs/1501.00092}.
17971 Efficient Sub-Pixel Convolutional Neural Network model (ESPCN).
17972 See @url{https://arxiv.org/abs/1609.05158}.
17975 Training scripts as well as scripts for model file (.pb) saving can be found at
17976 @url{https://github.com/XueweiMeng/sr/tree/sr_dnn_native}. Original repository
17977 is at @url{https://github.com/HighVoltageRocknRoll/sr.git}.
17979 Native model files (.model) can be generated from TensorFlow model
17980 files (.pb) by using tools/python/convert.py
17982 The filter accepts the following options:
17986 Specify which DNN backend to use for model loading and execution. This option accepts
17987 the following values:
17991 Native implementation of DNN loading and execution.
17994 TensorFlow backend. To enable this backend you
17995 need to install the TensorFlow for C library (see
17996 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
17997 @code{--enable-libtensorflow}
18000 Default value is @samp{native}.
18003 Set path to model file specifying network architecture and its parameters.
18004 Note that different backends use different file formats. TensorFlow backend
18005 can load files for both formats, while native backend can load files for only
18009 Set scale factor for SRCNN model. Allowed values are @code{2}, @code{3} and @code{4}.
18010 Default value is @code{2}. Scale factor is necessary for SRCNN model, because it accepts
18011 input upscaled using bicubic upscaling with proper scale factor.
18014 This feature can also be finished with @ref{dnn_processing} filter.
18018 Obtain the SSIM (Structural SImilarity Metric) between two input videos.
18020 This filter takes in input two input videos, the first input is
18021 considered the "main" source and is passed unchanged to the
18022 output. The second input is used as a "reference" video for computing
18025 Both video inputs must have the same resolution and pixel format for
18026 this filter to work correctly. Also it assumes that both inputs
18027 have the same number of frames, which are compared one by one.
18029 The filter stores the calculated SSIM of each frame.
18031 The description of the accepted parameters follows.
18034 @item stats_file, f
18035 If specified the filter will use the named file to save the SSIM of
18036 each individual frame. When filename equals "-" the data is sent to
18040 The file printed if @var{stats_file} is selected, contains a sequence of
18041 key/value pairs of the form @var{key}:@var{value} for each compared
18044 A description of each shown parameter follows:
18048 sequential number of the input frame, starting from 1
18050 @item Y, U, V, R, G, B
18051 SSIM of the compared frames for the component specified by the suffix.
18054 SSIM of the compared frames for the whole frame.
18057 Same as above but in dB representation.
18060 This filter also supports the @ref{framesync} options.
18062 @subsection Examples
18067 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
18068 [main][ref] ssim="stats_file=stats.log" [out]
18071 On this example the input file being processed is compared with the
18072 reference file @file{ref_movie.mpg}. The SSIM of each individual frame
18073 is stored in @file{stats.log}.
18076 Another example with both psnr and ssim at same time:
18078 ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
18082 Another example with different containers:
18084 ffmpeg -i main.mpg -i ref.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]ssim" -f null -
18090 Convert between different stereoscopic image formats.
18092 The filters accept the following options:
18096 Set stereoscopic image format of input.
18098 Available values for input image formats are:
18101 side by side parallel (left eye left, right eye right)
18104 side by side crosseye (right eye left, left eye right)
18107 side by side parallel with half width resolution
18108 (left eye left, right eye right)
18111 side by side crosseye with half width resolution
18112 (right eye left, left eye right)
18116 above-below (left eye above, right eye below)
18120 above-below (right eye above, left eye below)
18124 above-below with half height resolution
18125 (left eye above, right eye below)
18129 above-below with half height resolution
18130 (right eye above, left eye below)
18133 alternating frames (left eye first, right eye second)
18136 alternating frames (right eye first, left eye second)
18139 interleaved rows (left eye has top row, right eye starts on next row)
18142 interleaved rows (right eye has top row, left eye starts on next row)
18145 interleaved columns, left eye first
18148 interleaved columns, right eye first
18150 Default value is @samp{sbsl}.
18154 Set stereoscopic image format of output.
18158 side by side parallel (left eye left, right eye right)
18161 side by side crosseye (right eye left, left eye right)
18164 side by side parallel with half width resolution
18165 (left eye left, right eye right)
18168 side by side crosseye with half width resolution
18169 (right eye left, left eye right)
18173 above-below (left eye above, right eye below)
18177 above-below (right eye above, left eye below)
18181 above-below with half height resolution
18182 (left eye above, right eye below)
18186 above-below with half height resolution
18187 (right eye above, left eye below)
18190 alternating frames (left eye first, right eye second)
18193 alternating frames (right eye first, left eye second)
18196 interleaved rows (left eye has top row, right eye starts on next row)
18199 interleaved rows (right eye has top row, left eye starts on next row)
18202 anaglyph red/blue gray
18203 (red filter on left eye, blue filter on right eye)
18206 anaglyph red/green gray
18207 (red filter on left eye, green filter on right eye)
18210 anaglyph red/cyan gray
18211 (red filter on left eye, cyan filter on right eye)
18214 anaglyph red/cyan half colored
18215 (red filter on left eye, cyan filter on right eye)
18218 anaglyph red/cyan color
18219 (red filter on left eye, cyan filter on right eye)
18222 anaglyph red/cyan color optimized with the least squares projection of dubois
18223 (red filter on left eye, cyan filter on right eye)
18226 anaglyph green/magenta gray
18227 (green filter on left eye, magenta filter on right eye)
18230 anaglyph green/magenta half colored
18231 (green filter on left eye, magenta filter on right eye)
18234 anaglyph green/magenta colored
18235 (green filter on left eye, magenta filter on right eye)
18238 anaglyph green/magenta color optimized with the least squares projection of dubois
18239 (green filter on left eye, magenta filter on right eye)
18242 anaglyph yellow/blue gray
18243 (yellow filter on left eye, blue filter on right eye)
18246 anaglyph yellow/blue half colored
18247 (yellow filter on left eye, blue filter on right eye)
18250 anaglyph yellow/blue colored
18251 (yellow filter on left eye, blue filter on right eye)
18254 anaglyph yellow/blue color optimized with the least squares projection of dubois
18255 (yellow filter on left eye, blue filter on right eye)
18258 mono output (left eye only)
18261 mono output (right eye only)
18264 checkerboard, left eye first
18267 checkerboard, right eye first
18270 interleaved columns, left eye first
18273 interleaved columns, right eye first
18279 Default value is @samp{arcd}.
18282 @subsection Examples
18286 Convert input video from side by side parallel to anaglyph yellow/blue dubois:
18292 Convert input video from above below (left eye above, right eye below) to side by side crosseye.
18298 @section streamselect, astreamselect
18299 Select video or audio streams.
18301 The filter accepts the following options:
18305 Set number of inputs. Default is 2.
18308 Set input indexes to remap to outputs.
18311 @subsection Commands
18313 The @code{streamselect} and @code{astreamselect} filter supports the following
18318 Set input indexes to remap to outputs.
18321 @subsection Examples
18325 Select first 5 seconds 1st stream and rest of time 2nd stream:
18327 sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
18331 Same as above, but for audio:
18333 asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
18340 Draw subtitles on top of input video using the libass library.
18342 To enable compilation of this filter you need to configure FFmpeg with
18343 @code{--enable-libass}. This filter also requires a build with libavcodec and
18344 libavformat to convert the passed subtitles file to ASS (Advanced Substation
18345 Alpha) subtitles format.
18347 The filter accepts the following options:
18351 Set the filename of the subtitle file to read. It must be specified.
18353 @item original_size
18354 Specify the size of the original video, the video for which the ASS file
18355 was composed. For the syntax of this option, check the
18356 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18357 Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
18358 correctly scale the fonts if the aspect ratio has been changed.
18361 Set a directory path containing fonts that can be used by the filter.
18362 These fonts will be used in addition to whatever the font provider uses.
18365 Process alpha channel, by default alpha channel is untouched.
18368 Set subtitles input character encoding. @code{subtitles} filter only. Only
18369 useful if not UTF-8.
18371 @item stream_index, si
18372 Set subtitles stream index. @code{subtitles} filter only.
18375 Override default style or script info parameters of the subtitles. It accepts a
18376 string containing ASS style format @code{KEY=VALUE} couples separated by ",".
18379 If the first key is not specified, it is assumed that the first value
18380 specifies the @option{filename}.
18382 For example, to render the file @file{sub.srt} on top of the input
18383 video, use the command:
18388 which is equivalent to:
18390 subtitles=filename=sub.srt
18393 To render the default subtitles stream from file @file{video.mkv}, use:
18395 subtitles=video.mkv
18398 To render the second subtitles stream from that file, use:
18400 subtitles=video.mkv:si=1
18403 To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue
18404 @code{DejaVu Serif}, use:
18406 subtitles=sub.srt:force_style='Fontname=DejaVu Serif,PrimaryColour=&HCCFF0000'
18409 @section super2xsai
18411 Scale the input by 2x and smooth using the Super2xSaI (Scale and
18412 Interpolate) pixel art scaling algorithm.
18414 Useful for enlarging pixel art images without reducing sharpness.
18418 Swap two rectangular objects in video.
18420 This filter accepts the following options:
18430 Set 1st rect x coordinate.
18433 Set 1st rect y coordinate.
18436 Set 2nd rect x coordinate.
18439 Set 2nd rect y coordinate.
18441 All expressions are evaluated once for each frame.
18444 The all options are expressions containing the following constants:
18449 The input width and height.
18452 same as @var{w} / @var{h}
18455 input sample aspect ratio
18458 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
18461 The number of the input frame, starting from 0.
18464 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
18467 the position in the file of the input frame, NAN if unknown
18474 Blend successive video frames.
18480 Apply telecine process to the video.
18482 This filter accepts the following options:
18491 The default value is @code{top}.
18495 A string of numbers representing the pulldown pattern you wish to apply.
18496 The default value is @code{23}.
18500 Some typical patterns:
18505 24p: 2332 (preferred)
18512 24p: 222222222223 ("Euro pulldown")
18517 @section thistogram
18519 Compute and draw a color distribution histogram for the input video across time.
18521 Unlike @ref{histogram} video filter which only shows histogram of single input frame
18522 at certain time, this filter shows also past histograms of number of frames defined
18523 by @code{width} option.
18525 The computed histogram is a representation of the color component
18526 distribution in an image.
18528 The filter accepts the following options:
18532 Set width of single color component output. Default value is @code{0}.
18533 Value of @code{0} means width will be picked from input video.
18534 This also set number of passed histograms to keep.
18535 Allowed range is [0, 8192].
18537 @item display_mode, d
18539 It accepts the following values:
18542 Per color component graphs are placed below each other.
18545 Per color component graphs are placed side by side.
18548 Presents information identical to that in the @code{parade}, except
18549 that the graphs representing color components are superimposed directly
18552 Default is @code{stack}.
18554 @item levels_mode, m
18555 Set mode. Can be either @code{linear}, or @code{logarithmic}.
18556 Default is @code{linear}.
18558 @item components, c
18559 Set what color components to display.
18560 Default is @code{7}.
18563 Set background opacity. Default is @code{0.9}.
18566 Show envelope. Default is disabled.
18569 Set envelope color. Default is @code{gold}.
18574 Available values for slide is:
18577 Draw new frame when right border is reached.
18580 Replace old columns with new ones.
18583 Scroll from right to left.
18586 Scroll from left to right.
18589 Draw single picture.
18592 Default is @code{replace}.
18597 Apply threshold effect to video stream.
18599 This filter needs four video streams to perform thresholding.
18600 First stream is stream we are filtering.
18601 Second stream is holding threshold values, third stream is holding min values,
18602 and last, fourth stream is holding max values.
18604 The filter accepts the following option:
18608 Set which planes will be processed, unprocessed planes will be copied.
18609 By default value 0xf, all planes will be processed.
18612 For example if first stream pixel's component value is less then threshold value
18613 of pixel component from 2nd threshold stream, third stream value will picked,
18614 otherwise fourth stream pixel component value will be picked.
18616 Using color source filter one can perform various types of thresholding:
18618 @subsection Examples
18622 Binary threshold, using gray color as threshold:
18624 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
18628 Inverted binary threshold, using gray color as threshold:
18630 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
18634 Truncate binary threshold, using gray color as threshold:
18636 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
18640 Threshold to zero, using gray color as threshold:
18642 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
18646 Inverted threshold to zero, using gray color as threshold:
18648 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
18653 Select the most representative frame in a given sequence of consecutive frames.
18655 The filter accepts the following options:
18659 Set the frames batch size to analyze; in a set of @var{n} frames, the filter
18660 will pick one of them, and then handle the next batch of @var{n} frames until
18661 the end. Default is @code{100}.
18664 Since the filter keeps track of the whole frames sequence, a bigger @var{n}
18665 value will result in a higher memory usage, so a high value is not recommended.
18667 @subsection Examples
18671 Extract one picture each 50 frames:
18677 Complete example of a thumbnail creation with @command{ffmpeg}:
18679 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
18686 Tile several successive frames together.
18688 The @ref{untile} filter can do the reverse.
18690 The filter accepts the following options:
18695 Set the grid size (i.e. the number of lines and columns). For the syntax of
18696 this option, check the
18697 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18700 Set the maximum number of frames to render in the given area. It must be less
18701 than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
18702 the area will be used.
18705 Set the outer border margin in pixels.
18708 Set the inner border thickness (i.e. the number of pixels between frames). For
18709 more advanced padding options (such as having different values for the edges),
18710 refer to the pad video filter.
18713 Specify the color of the unused area. For the syntax of this option, check the
18714 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
18715 The default value of @var{color} is "black".
18718 Set the number of frames to overlap when tiling several successive frames together.
18719 The value must be between @code{0} and @var{nb_frames - 1}.
18722 Set the number of frames to initially be empty before displaying first output frame.
18723 This controls how soon will one get first output frame.
18724 The value must be between @code{0} and @var{nb_frames - 1}.
18727 @subsection Examples
18731 Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
18733 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
18735 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
18736 duplicating each output frame to accommodate the originally detected frame
18740 Display @code{5} pictures in an area of @code{3x2} frames,
18741 with @code{7} pixels between them, and @code{2} pixels of initial margin, using
18742 mixed flat and named options:
18744 tile=3x2:nb_frames=5:padding=7:margin=2
18748 @section tinterlace
18750 Perform various types of temporal field interlacing.
18752 Frames are counted starting from 1, so the first input frame is
18755 The filter accepts the following options:
18760 Specify the mode of the interlacing. This option can also be specified
18761 as a value alone. See below for a list of values for this option.
18763 Available values are:
18767 Move odd frames into the upper field, even into the lower field,
18768 generating a double height frame at half frame rate.
18772 Frame 1 Frame 2 Frame 3 Frame 4
18774 11111 22222 33333 44444
18775 11111 22222 33333 44444
18776 11111 22222 33333 44444
18777 11111 22222 33333 44444
18791 Only output odd frames, even frames are dropped, generating a frame with
18792 unchanged height at half frame rate.
18797 Frame 1 Frame 2 Frame 3 Frame 4
18799 11111 22222 33333 44444
18800 11111 22222 33333 44444
18801 11111 22222 33333 44444
18802 11111 22222 33333 44444
18812 Only output even frames, odd frames are dropped, generating a frame with
18813 unchanged height at half frame rate.
18818 Frame 1 Frame 2 Frame 3 Frame 4
18820 11111 22222 33333 44444
18821 11111 22222 33333 44444
18822 11111 22222 33333 44444
18823 11111 22222 33333 44444
18833 Expand each frame to full height, but pad alternate lines with black,
18834 generating a frame with double height at the same input frame rate.
18839 Frame 1 Frame 2 Frame 3 Frame 4
18841 11111 22222 33333 44444
18842 11111 22222 33333 44444
18843 11111 22222 33333 44444
18844 11111 22222 33333 44444
18847 11111 ..... 33333 .....
18848 ..... 22222 ..... 44444
18849 11111 ..... 33333 .....
18850 ..... 22222 ..... 44444
18851 11111 ..... 33333 .....
18852 ..... 22222 ..... 44444
18853 11111 ..... 33333 .....
18854 ..... 22222 ..... 44444
18858 @item interleave_top, 4
18859 Interleave the upper field from odd frames with the lower field from
18860 even frames, generating a frame with unchanged height at half frame rate.
18865 Frame 1 Frame 2 Frame 3 Frame 4
18867 11111<- 22222 33333<- 44444
18868 11111 22222<- 33333 44444<-
18869 11111<- 22222 33333<- 44444
18870 11111 22222<- 33333 44444<-
18880 @item interleave_bottom, 5
18881 Interleave the lower field from odd frames with the upper field from
18882 even frames, generating a frame with unchanged height at half frame rate.
18887 Frame 1 Frame 2 Frame 3 Frame 4
18889 11111 22222<- 33333 44444<-
18890 11111<- 22222 33333<- 44444
18891 11111 22222<- 33333 44444<-
18892 11111<- 22222 33333<- 44444
18902 @item interlacex2, 6
18903 Double frame rate with unchanged height. Frames are inserted each
18904 containing the second temporal field from the previous input frame and
18905 the first temporal field from the next input frame. This mode relies on
18906 the top_field_first flag. Useful for interlaced video displays with no
18907 field synchronisation.
18912 Frame 1 Frame 2 Frame 3 Frame 4
18914 11111 22222 33333 44444
18915 11111 22222 33333 44444
18916 11111 22222 33333 44444
18917 11111 22222 33333 44444
18920 11111 22222 22222 33333 33333 44444 44444
18921 11111 11111 22222 22222 33333 33333 44444
18922 11111 22222 22222 33333 33333 44444 44444
18923 11111 11111 22222 22222 33333 33333 44444
18928 Move odd frames into the upper field, even into the lower field,
18929 generating a double height frame at same frame rate.
18934 Frame 1 Frame 2 Frame 3 Frame 4
18936 11111 22222 33333 44444
18937 11111 22222 33333 44444
18938 11111 22222 33333 44444
18939 11111 22222 33333 44444
18942 11111 33333 33333 55555
18943 22222 22222 44444 44444
18944 11111 33333 33333 55555
18945 22222 22222 44444 44444
18946 11111 33333 33333 55555
18947 22222 22222 44444 44444
18948 11111 33333 33333 55555
18949 22222 22222 44444 44444
18954 Numeric values are deprecated but are accepted for backward
18955 compatibility reasons.
18957 Default mode is @code{merge}.
18960 Specify flags influencing the filter process.
18962 Available value for @var{flags} is:
18965 @item low_pass_filter, vlpf
18966 Enable linear vertical low-pass filtering in the filter.
18967 Vertical low-pass filtering is required when creating an interlaced
18968 destination from a progressive source which contains high-frequency
18969 vertical detail. Filtering will reduce interlace 'twitter' and Moire
18972 @item complex_filter, cvlpf
18973 Enable complex vertical low-pass filtering.
18974 This will slightly less reduce interlace 'twitter' and Moire
18975 patterning but better retain detail and subjective sharpness impression.
18978 Bypass already interlaced frames, only adjust the frame rate.
18981 Vertical low-pass filtering and bypassing already interlaced frames can only be
18982 enabled for @option{mode} @var{interleave_top} and @var{interleave_bottom}.
18987 Pick median pixels from several successive input video frames.
18989 The filter accepts the following options:
18993 Set radius of median filter.
18994 Default is 1. Allowed range is from 1 to 127.
18997 Set which planes to filter. Default value is @code{15}, by which all planes are processed.
19000 Set median percentile. Default value is @code{0.5}.
19001 Default value of @code{0.5} will pick always median values, while @code{0} will pick
19002 minimum values, and @code{1} maximum values.
19007 Mix successive video frames.
19009 A description of the accepted options follows.
19013 The number of successive frames to mix. If unspecified, it defaults to 3.
19016 Specify weight of each input video frame.
19017 Each weight is separated by space. If number of weights is smaller than
19018 number of @var{frames} last specified weight will be used for all remaining
19022 Specify scale, if it is set it will be multiplied with sum
19023 of each weight multiplied with pixel values to give final destination
19024 pixel value. By default @var{scale} is auto scaled to sum of weights.
19027 @subsection Examples
19031 Average 7 successive frames:
19033 tmix=frames=7:weights="1 1 1 1 1 1 1"
19037 Apply simple temporal convolution:
19039 tmix=frames=3:weights="-1 3 -1"
19043 Similar as above but only showing temporal differences:
19045 tmix=frames=3:weights="-1 2 -1":scale=1
19051 Tone map colors from different dynamic ranges.
19053 This filter expects data in single precision floating point, as it needs to
19054 operate on (and can output) out-of-range values. Another filter, such as
19055 @ref{zscale}, is needed to convert the resulting frame to a usable format.
19057 The tonemapping algorithms implemented only work on linear light, so input
19058 data should be linearized beforehand (and possibly correctly tagged).
19061 ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
19064 @subsection Options
19065 The filter accepts the following options.
19069 Set the tone map algorithm to use.
19071 Possible values are:
19074 Do not apply any tone map, only desaturate overbright pixels.
19077 Hard-clip any out-of-range values. Use it for perfect color accuracy for
19078 in-range values, while distorting out-of-range values.
19081 Stretch the entire reference gamut to a linear multiple of the display.
19084 Fit a logarithmic transfer between the tone curves.
19087 Preserve overall image brightness with a simple curve, using nonlinear
19088 contrast, which results in flattening details and degrading color accuracy.
19091 Preserve both dark and bright details better than @var{reinhard}, at the cost
19092 of slightly darkening everything. Use it when detail preservation is more
19093 important than color and brightness accuracy.
19096 Smoothly map out-of-range values, while retaining contrast and colors for
19097 in-range material as much as possible. Use it when color accuracy is more
19098 important than detail preservation.
19104 Tune the tone mapping algorithm.
19106 This affects the following algorithms:
19112 Specifies the scale factor to use while stretching.
19116 Specifies the exponent of the function.
19120 Specify an extra linear coefficient to multiply into the signal before clipping.
19124 Specify the local contrast coefficient at the display peak.
19125 Default to 0.5, which means that in-gamut values will be about half as bright
19132 Specify the transition point from linear to mobius transform. Every value
19133 below this point is guaranteed to be mapped 1:1. The higher the value, the
19134 more accurate the result will be, at the cost of losing bright details.
19135 Default to 0.3, which due to the steep initial slope still preserves in-range
19136 colors fairly accurately.
19140 Apply desaturation for highlights that exceed this level of brightness. The
19141 higher the parameter, the more color information will be preserved. This
19142 setting helps prevent unnaturally blown-out colors for super-highlights, by
19143 (smoothly) turning into white instead. This makes images feel more natural,
19144 at the cost of reducing information about out-of-range colors.
19146 The default of 2.0 is somewhat conservative and will mostly just apply to
19147 skies or directly sunlit surfaces. A setting of 0.0 disables this option.
19149 This option works only if the input frame has a supported color tag.
19152 Override signal/nominal/reference peak with this value. Useful when the
19153 embedded peak information in display metadata is not reliable or when tone
19154 mapping from a lower range to a higher range.
19159 Temporarily pad video frames.
19161 The filter accepts the following options:
19165 Specify number of delay frames before input video stream. Default is 0.
19168 Specify number of padding frames after input video stream.
19169 Set to -1 to pad indefinitely. Default is 0.
19172 Set kind of frames added to beginning of stream.
19173 Can be either @var{add} or @var{clone}.
19174 With @var{add} frames of solid-color are added.
19175 With @var{clone} frames are clones of first frame.
19176 Default is @var{add}.
19179 Set kind of frames added to end of stream.
19180 Can be either @var{add} or @var{clone}.
19181 With @var{add} frames of solid-color are added.
19182 With @var{clone} frames are clones of last frame.
19183 Default is @var{add}.
19185 @item start_duration, stop_duration
19186 Specify the duration of the start/stop delay. See
19187 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
19188 for the accepted syntax.
19189 These options override @var{start} and @var{stop}. Default is 0.
19192 Specify the color of the padded area. For the syntax of this option,
19193 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
19194 manual,ffmpeg-utils}.
19196 The default value of @var{color} is "black".
19202 Transpose rows with columns in the input video and optionally flip it.
19204 It accepts the following parameters:
19209 Specify the transposition direction.
19211 Can assume the following values:
19213 @item 0, 4, cclock_flip
19214 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
19222 Rotate by 90 degrees clockwise, that is:
19230 Rotate by 90 degrees counterclockwise, that is:
19237 @item 3, 7, clock_flip
19238 Rotate by 90 degrees clockwise and vertically flip, that is:
19246 For values between 4-7, the transposition is only done if the input
19247 video geometry is portrait and not landscape. These values are
19248 deprecated, the @code{passthrough} option should be used instead.
19250 Numerical values are deprecated, and should be dropped in favor of
19251 symbolic constants.
19254 Do not apply the transposition if the input geometry matches the one
19255 specified by the specified value. It accepts the following values:
19258 Always apply transposition.
19260 Preserve portrait geometry (when @var{height} >= @var{width}).
19262 Preserve landscape geometry (when @var{width} >= @var{height}).
19265 Default value is @code{none}.
19268 For example to rotate by 90 degrees clockwise and preserve portrait
19271 transpose=dir=1:passthrough=portrait
19274 The command above can also be specified as:
19276 transpose=1:portrait
19279 @section transpose_npp
19281 Transpose rows with columns in the input video and optionally flip it.
19282 For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options.
19284 It accepts the following parameters:
19289 Specify the transposition direction.
19291 Can assume the following values:
19294 Rotate by 90 degrees counterclockwise and vertically flip. (default)
19297 Rotate by 90 degrees clockwise.
19300 Rotate by 90 degrees counterclockwise.
19303 Rotate by 90 degrees clockwise and vertically flip.
19307 Do not apply the transposition if the input geometry matches the one
19308 specified by the specified value. It accepts the following values:
19311 Always apply transposition. (default)
19313 Preserve portrait geometry (when @var{height} >= @var{width}).
19315 Preserve landscape geometry (when @var{width} >= @var{height}).
19321 Trim the input so that the output contains one continuous subpart of the input.
19323 It accepts the following parameters:
19326 Specify the time of the start of the kept section, i.e. the frame with the
19327 timestamp @var{start} will be the first frame in the output.
19330 Specify the time of the first frame that will be dropped, i.e. the frame
19331 immediately preceding the one with the timestamp @var{end} will be the last
19332 frame in the output.
19335 This is the same as @var{start}, except this option sets the start timestamp
19336 in timebase units instead of seconds.
19339 This is the same as @var{end}, except this option sets the end timestamp
19340 in timebase units instead of seconds.
19343 The maximum duration of the output in seconds.
19346 The number of the first frame that should be passed to the output.
19349 The number of the first frame that should be dropped.
19352 @option{start}, @option{end}, and @option{duration} are expressed as time
19353 duration specifications; see
19354 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
19355 for the accepted syntax.
19357 Note that the first two sets of the start/end options and the @option{duration}
19358 option look at the frame timestamp, while the _frame variants simply count the
19359 frames that pass through the filter. Also note that this filter does not modify
19360 the timestamps. If you wish for the output timestamps to start at zero, insert a
19361 setpts filter after the trim filter.
19363 If multiple start or end options are set, this filter tries to be greedy and
19364 keep all the frames that match at least one of the specified constraints. To keep
19365 only the part that matches all the constraints at once, chain multiple trim
19368 The defaults are such that all the input is kept. So it is possible to set e.g.
19369 just the end values to keep everything before the specified time.
19374 Drop everything except the second minute of input:
19376 ffmpeg -i INPUT -vf trim=60:120
19380 Keep only the first second:
19382 ffmpeg -i INPUT -vf trim=duration=1
19387 @section unpremultiply
19388 Apply alpha unpremultiply effect to input video stream using first plane
19389 of second stream as alpha.
19391 Both streams must have same dimensions and same pixel format.
19393 The filter accepts the following option:
19397 Set which planes will be processed, unprocessed planes will be copied.
19398 By default value 0xf, all planes will be processed.
19400 If the format has 1 or 2 components, then luma is bit 0.
19401 If the format has 3 or 4 components:
19402 for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red;
19403 for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V.
19404 If present, the alpha channel is always the last bit.
19407 Do not require 2nd input for processing, instead use alpha plane from input stream.
19413 Sharpen or blur the input video.
19415 It accepts the following parameters:
19418 @item luma_msize_x, lx
19419 Set the luma matrix horizontal size. It must be an odd integer between
19420 3 and 23. The default value is 5.
19422 @item luma_msize_y, ly
19423 Set the luma matrix vertical size. It must be an odd integer between 3
19424 and 23. The default value is 5.
19426 @item luma_amount, la
19427 Set the luma effect strength. It must be a floating point number, reasonable
19428 values lay between -1.5 and 1.5.
19430 Negative values will blur the input video, while positive values will
19431 sharpen it, a value of zero will disable the effect.
19433 Default value is 1.0.
19435 @item chroma_msize_x, cx
19436 Set the chroma matrix horizontal size. It must be an odd integer
19437 between 3 and 23. The default value is 5.
19439 @item chroma_msize_y, cy
19440 Set the chroma matrix vertical size. It must be an odd integer
19441 between 3 and 23. The default value is 5.
19443 @item chroma_amount, ca
19444 Set the chroma effect strength. It must be a floating point number, reasonable
19445 values lay between -1.5 and 1.5.
19447 Negative values will blur the input video, while positive values will
19448 sharpen it, a value of zero will disable the effect.
19450 Default value is 0.0.
19454 All parameters are optional and default to the equivalent of the
19455 string '5:5:1.0:5:5:0.0'.
19457 @subsection Examples
19461 Apply strong luma sharpen effect:
19463 unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
19467 Apply a strong blur of both luma and chroma parameters:
19469 unsharp=7:7:-2:7:7:-2
19476 Decompose a video made of tiled images into the individual images.
19478 The frame rate of the output video is the frame rate of the input video
19479 multiplied by the number of tiles.
19481 This filter does the reverse of @ref{tile}.
19483 The filter accepts the following options:
19488 Set the grid size (i.e. the number of lines and columns). For the syntax of
19489 this option, check the
19490 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19493 @subsection Examples
19497 Produce a 1-second video from a still image file made of 25 frames stacked
19498 vertically, like an analogic film reel:
19500 ffmpeg -r 1 -i image.jpg -vf untile=1x25 movie.mkv
19506 Apply ultra slow/simple postprocessing filter that compresses and decompresses
19507 the image at several (or - in the case of @option{quality} level @code{8} - all)
19508 shifts and average the results.
19510 The way this differs from the behavior of spp is that uspp actually encodes &
19511 decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
19512 DCT similar to MJPEG.
19514 The filter accepts the following options:
19518 Set quality. This option defines the number of levels for averaging. It accepts
19519 an integer in the range 0-8. If set to @code{0}, the filter will have no
19520 effect. A value of @code{8} means the higher quality. For each increment of
19521 that value the speed drops by a factor of approximately 2. Default value is
19525 Force a constant quantization parameter. If not set, the filter will use the QP
19526 from the video stream (if available).
19531 Convert 360 videos between various formats.
19533 The filter accepts the following options:
19539 Set format of the input/output video.
19547 Equirectangular projection.
19552 Cubemap with 3x2/6x1/1x6 layout.
19554 Format specific options:
19559 Set padding proportion for the input/output cubemap. Values in decimals.
19566 1% of face is padding. For example, with 1920x1280 resolution face size would be 640x640 and padding would be 3 pixels from each side. (640 * 0.01 = 6 pixels)
19569 Default value is @b{@samp{0}}.
19570 Maximum value is @b{@samp{0.1}}.
19574 Set fixed padding for the input/output cubemap. Values in pixels.
19576 Default value is @b{@samp{0}}. If greater than zero it overrides other padding options.
19580 Set order of faces for the input/output cubemap. Choose one direction for each position.
19582 Designation of directions:
19598 Default value is @b{@samp{rludfb}}.
19602 Set rotation of faces for the input/output cubemap. Choose one angle for each position.
19604 Designation of angles:
19607 0 degrees clockwise
19609 90 degrees clockwise
19611 180 degrees clockwise
19613 270 degrees clockwise
19616 Default value is @b{@samp{000000}}.
19620 Equi-Angular Cubemap.
19627 Format specific options:
19632 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19634 If diagonal field of view is set it overrides horizontal and vertical field of view.
19639 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19641 If diagonal field of view is set it overrides horizontal and vertical field of view.
19647 Format specific options:
19652 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19654 If diagonal field of view is set it overrides horizontal and vertical field of view.
19659 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19661 If diagonal field of view is set it overrides horizontal and vertical field of view.
19667 Facebook's 360 formats.
19670 Stereographic format.
19672 Format specific options:
19677 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19679 If diagonal field of view is set it overrides horizontal and vertical field of view.
19684 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19686 If diagonal field of view is set it overrides horizontal and vertical field of view.
19693 Ball format, gives significant distortion toward the back.
19696 Hammer-Aitoff map projection format.
19699 Sinusoidal map projection format.
19702 Fisheye projection.
19704 Format specific options:
19709 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19711 If diagonal field of view is set it overrides horizontal and vertical field of view.
19716 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19718 If diagonal field of view is set it overrides horizontal and vertical field of view.
19722 Pannini projection.
19724 Format specific options:
19727 Set output pannini parameter.
19730 Set input pannini parameter.
19734 Cylindrical projection.
19736 Format specific options:
19741 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19743 If diagonal field of view is set it overrides horizontal and vertical field of view.
19748 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19750 If diagonal field of view is set it overrides horizontal and vertical field of view.
19754 Perspective projection. @i{(output only)}
19756 Format specific options:
19759 Set perspective parameter.
19763 Tetrahedron projection.
19766 Truncated square pyramid projection.
19770 Half equirectangular projection.
19775 Format specific options:
19780 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19782 If diagonal field of view is set it overrides horizontal and vertical field of view.
19787 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19789 If diagonal field of view is set it overrides horizontal and vertical field of view.
19793 Orthographic format.
19795 Format specific options:
19800 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19802 If diagonal field of view is set it overrides horizontal and vertical field of view.
19807 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19809 If diagonal field of view is set it overrides horizontal and vertical field of view.
19813 Octahedron projection.
19817 Set interpolation method.@*
19818 @i{Note: more complex interpolation methods require much more memory to run.}
19828 Bilinear interpolation.
19830 Lagrange9 interpolation.
19833 Bicubic interpolation.
19836 Lanczos interpolation.
19839 Spline16 interpolation.
19842 Gaussian interpolation.
19844 Mitchell interpolation.
19847 Default value is @b{@samp{line}}.
19851 Set the output video resolution.
19853 Default resolution depends on formats.
19857 Set the input/output stereo format.
19868 Default value is @b{@samp{2d}} for input and output format.
19873 Set rotation for the output video. Values in degrees.
19876 Set rotation order for the output video. Choose one item for each position.
19887 Default value is @b{@samp{ypr}}.
19892 Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values.
19896 Set if input video is flipped horizontally/vertically. Boolean values.
19899 Set if input video is transposed. Boolean value, by default disabled.
19902 Set if output video needs to be transposed. Boolean value, by default disabled.
19905 Build mask in alpha plane for all unmapped pixels by marking them fully transparent. Boolean value, by default disabled.
19908 @subsection Examples
19912 Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation:
19914 ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv
19917 Extract back view of Equi-Angular Cubemap:
19919 ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv
19922 Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format:
19924 v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb
19928 @subsection Commands
19930 This filter supports subset of above options as @ref{commands}.
19932 @section vaguedenoiser
19934 Apply a wavelet based denoiser.
19936 It transforms each frame from the video input into the wavelet domain,
19937 using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
19938 the obtained coefficients. It does an inverse wavelet transform after.
19939 Due to wavelet properties, it should give a nice smoothed result, and
19940 reduced noise, without blurring picture features.
19942 This filter accepts the following options:
19946 The filtering strength. The higher, the more filtered the video will be.
19947 Hard thresholding can use a higher threshold than soft thresholding
19948 before the video looks overfiltered. Default value is 2.
19951 The filtering method the filter will use.
19953 It accepts the following values:
19956 All values under the threshold will be zeroed.
19959 All values under the threshold will be zeroed. All values above will be
19960 reduced by the threshold.
19963 Scales or nullifies coefficients - intermediary between (more) soft and
19964 (less) hard thresholding.
19967 Default is garrote.
19970 Number of times, the wavelet will decompose the picture. Picture can't
19971 be decomposed beyond a particular point (typically, 8 for a 640x480
19972 frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6.
19975 Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85.
19978 A list of the planes to process. By default all planes are processed.
19981 The threshold type the filter will use.
19983 It accepts the following values:
19986 Threshold used is same for all decompositions.
19989 Threshold used depends also on each decomposition coefficients.
19992 Default is universal.
19995 @section vectorscope
19997 Display 2 color component values in the two dimensional graph (which is called
20000 This filter accepts the following options:
20004 Set vectorscope mode.
20006 It accepts the following values:
20010 Gray values are displayed on graph, higher brightness means more pixels have
20011 same component color value on location in graph. This is the default mode.
20014 Gray values are displayed on graph. Surrounding pixels values which are not
20015 present in video frame are drawn in gradient of 2 color components which are
20016 set by option @code{x} and @code{y}. The 3rd color component is static.
20019 Actual color components values present in video frame are displayed on graph.
20022 Similar as color2 but higher frequency of same values @code{x} and @code{y}
20023 on graph increases value of another color component, which is luminance by
20024 default values of @code{x} and @code{y}.
20027 Actual colors present in video frame are displayed on graph. If two different
20028 colors map to same position on graph then color with higher value of component
20029 not present in graph is picked.
20032 Gray values are displayed on graph. Similar to @code{color} but with 3rd color
20033 component picked from radial gradient.
20037 Set which color component will be represented on X-axis. Default is @code{1}.
20040 Set which color component will be represented on Y-axis. Default is @code{2}.
20043 Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
20044 of color component which represents frequency of (X, Y) location in graph.
20049 No envelope, this is default.
20052 Instant envelope, even darkest single pixel will be clearly highlighted.
20055 Hold maximum and minimum values presented in graph over time. This way you
20056 can still spot out of range values without constantly looking at vectorscope.
20059 Peak and instant envelope combined together.
20063 Set what kind of graticule to draw.
20072 Set graticule opacity.
20075 Set graticule flags.
20079 Draw graticule for white point.
20082 Draw graticule for black point.
20085 Draw color points short names.
20089 Set background opacity.
20091 @item lthreshold, l
20092 Set low threshold for color component not represented on X or Y axis.
20093 Values lower than this value will be ignored. Default is 0.
20094 Note this value is multiplied with actual max possible value one pixel component
20095 can have. So for 8-bit input and low threshold value of 0.1 actual threshold
20098 @item hthreshold, h
20099 Set high threshold for color component not represented on X or Y axis.
20100 Values higher than this value will be ignored. Default is 1.
20101 Note this value is multiplied with actual max possible value one pixel component
20102 can have. So for 8-bit input and high threshold value of 0.9 actual threshold
20103 is 0.9 * 255 = 230.
20105 @item colorspace, c
20106 Set what kind of colorspace to use when drawing graticule.
20116 Set color tint for gray/tint vectorscope mode. By default both options are zero.
20117 This means no tint, and output will remain gray.
20120 @anchor{vidstabdetect}
20121 @section vidstabdetect
20123 Analyze video stabilization/deshaking. Perform pass 1 of 2, see
20124 @ref{vidstabtransform} for pass 2.
20126 This filter generates a file with relative translation and rotation
20127 transform information about subsequent frames, which is then used by
20128 the @ref{vidstabtransform} filter.
20130 To enable compilation of this filter you need to configure FFmpeg with
20131 @code{--enable-libvidstab}.
20133 This filter accepts the following options:
20137 Set the path to the file used to write the transforms information.
20138 Default value is @file{transforms.trf}.
20141 Set how shaky the video is and how quick the camera is. It accepts an
20142 integer in the range 1-10, a value of 1 means little shakiness, a
20143 value of 10 means strong shakiness. Default value is 5.
20146 Set the accuracy of the detection process. It must be a value in the
20147 range 1-15. A value of 1 means low accuracy, a value of 15 means high
20148 accuracy. Default value is 15.
20151 Set stepsize of the search process. The region around minimum is
20152 scanned with 1 pixel resolution. Default value is 6.
20155 Set minimum contrast. Below this value a local measurement field is
20156 discarded. Must be a floating point value in the range 0-1. Default
20160 Set reference frame number for tripod mode.
20162 If enabled, the motion of the frames is compared to a reference frame
20163 in the filtered stream, identified by the specified number. The idea
20164 is to compensate all movements in a more-or-less static scene and keep
20165 the camera view absolutely still.
20167 If set to 0, it is disabled. The frames are counted starting from 1.
20170 Show fields and transforms in the resulting frames. It accepts an
20171 integer in the range 0-2. Default value is 0, which disables any
20175 @subsection Examples
20179 Use default values:
20185 Analyze strongly shaky movie and put the results in file
20186 @file{mytransforms.trf}:
20188 vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
20192 Visualize the result of internal transformations in the resulting
20195 vidstabdetect=show=1
20199 Analyze a video with medium shakiness using @command{ffmpeg}:
20201 ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
20205 @anchor{vidstabtransform}
20206 @section vidstabtransform
20208 Video stabilization/deshaking: pass 2 of 2,
20209 see @ref{vidstabdetect} for pass 1.
20211 Read a file with transform information for each frame and
20212 apply/compensate them. Together with the @ref{vidstabdetect}
20213 filter this can be used to deshake videos. See also
20214 @url{http://public.hronopik.de/vid.stab}. It is important to also use
20215 the @ref{unsharp} filter, see below.
20217 To enable compilation of this filter you need to configure FFmpeg with
20218 @code{--enable-libvidstab}.
20220 @subsection Options
20224 Set path to the file used to read the transforms. Default value is
20225 @file{transforms.trf}.
20228 Set the number of frames (value*2 + 1) used for lowpass filtering the
20229 camera movements. Default value is 10.
20231 For example a number of 10 means that 21 frames are used (10 in the
20232 past and 10 in the future) to smoothen the motion in the video. A
20233 larger value leads to a smoother video, but limits the acceleration of
20234 the camera (pan/tilt movements). 0 is a special case where a static
20235 camera is simulated.
20238 Set the camera path optimization algorithm.
20240 Accepted values are:
20243 gaussian kernel low-pass filter on camera motion (default)
20245 averaging on transformations
20249 Set maximal number of pixels to translate frames. Default value is -1,
20253 Set maximal angle in radians (degree*PI/180) to rotate frames. Default
20254 value is -1, meaning no limit.
20257 Specify how to deal with borders that may be visible due to movement
20260 Available values are:
20263 keep image information from previous frame (default)
20265 fill the border black
20269 Invert transforms if set to 1. Default value is 0.
20272 Consider transforms as relative to previous frame if set to 1,
20273 absolute if set to 0. Default value is 0.
20276 Set percentage to zoom. A positive value will result in a zoom-in
20277 effect, a negative value in a zoom-out effect. Default value is 0 (no
20281 Set optimal zooming to avoid borders.
20283 Accepted values are:
20288 optimal static zoom value is determined (only very strong movements
20289 will lead to visible borders) (default)
20291 optimal adaptive zoom value is determined (no borders will be
20292 visible), see @option{zoomspeed}
20295 Note that the value given at zoom is added to the one calculated here.
20298 Set percent to zoom maximally each frame (enabled when
20299 @option{optzoom} is set to 2). Range is from 0 to 5, default value is
20303 Specify type of interpolation.
20305 Available values are:
20310 linear only horizontal
20312 linear in both directions (default)
20314 cubic in both directions (slow)
20318 Enable virtual tripod mode if set to 1, which is equivalent to
20319 @code{relative=0:smoothing=0}. Default value is 0.
20321 Use also @code{tripod} option of @ref{vidstabdetect}.
20324 Increase log verbosity if set to 1. Also the detected global motions
20325 are written to the temporary file @file{global_motions.trf}. Default
20329 @subsection Examples
20333 Use @command{ffmpeg} for a typical stabilization with default values:
20335 ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
20338 Note the use of the @ref{unsharp} filter which is always recommended.
20341 Zoom in a bit more and load transform data from a given file:
20343 vidstabtransform=zoom=5:input="mytransforms.trf"
20347 Smoothen the video even more:
20349 vidstabtransform=smoothing=30
20355 Flip the input video vertically.
20357 For example, to vertically flip a video with @command{ffmpeg}:
20359 ffmpeg -i in.avi -vf "vflip" out.avi
20364 Detect variable frame rate video.
20366 This filter tries to detect if the input is variable or constant frame rate.
20368 At end it will output number of frames detected as having variable delta pts,
20369 and ones with constant delta pts.
20370 If there was frames with variable delta, than it will also show min, max and
20371 average delta encountered.
20375 Boost or alter saturation.
20377 The filter accepts the following options:
20380 Set strength of boost if positive value or strength of alter if negative value.
20381 Default is 0. Allowed range is from -2 to 2.
20384 Set the red balance. Default is 1. Allowed range is from -10 to 10.
20387 Set the green balance. Default is 1. Allowed range is from -10 to 10.
20390 Set the blue balance. Default is 1. Allowed range is from -10 to 10.
20393 Set the red luma coefficient.
20396 Set the green luma coefficient.
20399 Set the blue luma coefficient.
20402 If @code{intensity} is negative and this is set to 1, colors will change,
20403 otherwise colors will be less saturated, more towards gray.
20406 @subsection Commands
20408 This filter supports the all above options as @ref{commands}.
20413 Make or reverse a natural vignetting effect.
20415 The filter accepts the following options:
20419 Set lens angle expression as a number of radians.
20421 The value is clipped in the @code{[0,PI/2]} range.
20423 Default value: @code{"PI/5"}
20427 Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
20431 Set forward/backward mode.
20433 Available modes are:
20436 The larger the distance from the central point, the darker the image becomes.
20439 The larger the distance from the central point, the brighter the image becomes.
20440 This can be used to reverse a vignette effect, though there is no automatic
20441 detection to extract the lens @option{angle} and other settings (yet). It can
20442 also be used to create a burning effect.
20445 Default value is @samp{forward}.
20448 Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
20450 It accepts the following values:
20453 Evaluate expressions only once during the filter initialization.
20456 Evaluate expressions for each incoming frame. This is way slower than the
20457 @samp{init} mode since it requires all the scalers to be re-computed, but it
20458 allows advanced dynamic expressions.
20461 Default value is @samp{init}.
20464 Set dithering to reduce the circular banding effects. Default is @code{1}
20468 Set vignette aspect. This setting allows one to adjust the shape of the vignette.
20469 Setting this value to the SAR of the input will make a rectangular vignetting
20470 following the dimensions of the video.
20472 Default is @code{1/1}.
20475 @subsection Expressions
20477 The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
20478 following parameters.
20483 input width and height
20486 the number of input frame, starting from 0
20489 the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
20490 @var{TB} units, NAN if undefined
20493 frame rate of the input video, NAN if the input frame rate is unknown
20496 the PTS (Presentation TimeStamp) of the filtered video frame,
20497 expressed in seconds, NAN if undefined
20500 time base of the input video
20504 @subsection Examples
20508 Apply simple strong vignetting effect:
20514 Make a flickering vignetting:
20516 vignette='PI/4+random(1)*PI/50':eval=frame
20521 @section vmafmotion
20523 Obtain the average VMAF motion score of a video.
20524 It is one of the component metrics of VMAF.
20526 The obtained average motion score is printed through the logging system.
20528 The filter accepts the following options:
20532 If specified, the filter will use the named file to save the motion score of
20533 each frame with respect to the previous frame.
20534 When filename equals "-" the data is sent to standard output.
20539 ffmpeg -i ref.mpg -vf vmafmotion -f null -
20543 Stack input videos vertically.
20545 All streams must be of same pixel format and of same width.
20547 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
20548 to create same output.
20550 The filter accepts the following options:
20554 Set number of input streams. Default is 2.
20557 If set to 1, force the output to terminate when the shortest input
20558 terminates. Default value is 0.
20563 Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
20564 Deinterlacing Filter").
20566 Based on the process described by Martin Weston for BBC R&D, and
20567 implemented based on the de-interlace algorithm written by Jim
20568 Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
20569 uses filter coefficients calculated by BBC R&D.
20571 This filter uses field-dominance information in frame to decide which
20572 of each pair of fields to place first in the output.
20573 If it gets it wrong use @ref{setfield} filter before @code{w3fdif} filter.
20575 There are two sets of filter coefficients, so called "simple"
20576 and "complex". Which set of filter coefficients is used can
20577 be set by passing an optional parameter:
20581 Set the interlacing filter coefficients. Accepts one of the following values:
20585 Simple filter coefficient set.
20587 More-complex filter coefficient set.
20589 Default value is @samp{complex}.
20592 Specify which frames to deinterlace. Accepts one of the following values:
20596 Deinterlace all frames,
20598 Only deinterlace frames marked as interlaced.
20601 Default value is @samp{all}.
20605 Video waveform monitor.
20607 The waveform monitor plots color component intensity. By default luminance
20608 only. Each column of the waveform corresponds to a column of pixels in the
20611 It accepts the following options:
20615 Can be either @code{row}, or @code{column}. Default is @code{column}.
20616 In row mode, the graph on the left side represents color component value 0 and
20617 the right side represents value = 255. In column mode, the top side represents
20618 color component value = 0 and bottom side represents value = 255.
20621 Set intensity. Smaller values are useful to find out how many values of the same
20622 luminance are distributed across input rows/columns.
20623 Default value is @code{0.04}. Allowed range is [0, 1].
20626 Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
20627 In mirrored mode, higher values will be represented on the left
20628 side for @code{row} mode and at the top for @code{column} mode. Default is
20629 @code{1} (mirrored).
20633 It accepts the following values:
20636 Presents information identical to that in the @code{parade}, except
20637 that the graphs representing color components are superimposed directly
20640 This display mode makes it easier to spot relative differences or similarities
20641 in overlapping areas of the color components that are supposed to be identical,
20642 such as neutral whites, grays, or blacks.
20645 Display separate graph for the color components side by side in
20646 @code{row} mode or one below the other in @code{column} mode.
20649 Display separate graph for the color components side by side in
20650 @code{column} mode or one below the other in @code{row} mode.
20652 Using this display mode makes it easy to spot color casts in the highlights
20653 and shadows of an image, by comparing the contours of the top and the bottom
20654 graphs of each waveform. Since whites, grays, and blacks are characterized
20655 by exactly equal amounts of red, green, and blue, neutral areas of the picture
20656 should display three waveforms of roughly equal width/height. If not, the
20657 correction is easy to perform by making level adjustments the three waveforms.
20659 Default is @code{stack}.
20661 @item components, c
20662 Set which color components to display. Default is 1, which means only luminance
20663 or red color component if input is in RGB colorspace. If is set for example to
20664 7 it will display all 3 (if) available color components.
20669 No envelope, this is default.
20672 Instant envelope, minimum and maximum values presented in graph will be easily
20673 visible even with small @code{step} value.
20676 Hold minimum and maximum values presented in graph across time. This way you
20677 can still spot out of range values without constantly looking at waveforms.
20680 Peak and instant envelope combined together.
20686 No filtering, this is default.
20689 Luma and chroma combined together.
20692 Similar as above, but shows difference between blue and red chroma.
20695 Similar as above, but use different colors.
20698 Similar as above, but again with different colors.
20701 Displays only chroma.
20704 Displays actual color value on waveform.
20707 Similar as above, but with luma showing frequency of chroma values.
20711 Set which graticule to display.
20715 Do not display graticule.
20718 Display green graticule showing legal broadcast ranges.
20721 Display orange graticule showing legal broadcast ranges.
20724 Display invert graticule showing legal broadcast ranges.
20728 Set graticule opacity.
20731 Set graticule flags.
20735 Draw numbers above lines. By default enabled.
20738 Draw dots instead of lines.
20742 Set scale used for displaying graticule.
20749 Default is digital.
20752 Set background opacity.
20756 Set tint for output.
20757 Only used with lowpass filter and when display is not overlay and input
20758 pixel formats are not RGB.
20761 @section weave, doubleweave
20763 The @code{weave} takes a field-based video input and join
20764 each two sequential fields into single frame, producing a new double
20765 height clip with half the frame rate and half the frame count.
20767 The @code{doubleweave} works same as @code{weave} but without
20768 halving frame rate and frame count.
20770 It accepts the following option:
20774 Set first field. Available values are:
20778 Set the frame as top-field-first.
20781 Set the frame as bottom-field-first.
20785 @subsection Examples
20789 Interlace video using @ref{select} and @ref{separatefields} filter:
20791 separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
20796 Apply the xBR high-quality magnification filter which is designed for pixel
20797 art. It follows a set of edge-detection rules, see
20798 @url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}.
20800 It accepts the following option:
20804 Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
20805 @code{3xBR} and @code{4} for @code{4xBR}.
20806 Default is @code{3}.
20811 Apply cross fade from one input video stream to another input video stream.
20812 The cross fade is applied for specified duration.
20814 The filter accepts the following options:
20818 Set one of available transition effects:
20866 Default transition effect is fade.
20869 Set cross fade duration in seconds.
20870 Default duration is 1 second.
20873 Set cross fade start relative to first input stream in seconds.
20874 Default offset is 0.
20877 Set expression for custom transition effect.
20879 The expressions can use the following variables and functions:
20884 The coordinates of the current sample.
20888 The width and height of the image.
20891 Progress of transition effect.
20894 Currently processed plane.
20897 Return value of first input at current location and plane.
20900 Return value of second input at current location and plane.
20906 Return the value of the pixel at location (@var{x},@var{y}) of the
20907 first/second/third/fourth component of first input.
20913 Return the value of the pixel at location (@var{x},@var{y}) of the
20914 first/second/third/fourth component of second input.
20918 @subsection Examples
20922 Cross fade from one input video to another input video, with fade transition and duration of transition
20923 of 2 seconds starting at offset of 5 seconds:
20925 ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4
20930 Pick median pixels from several input videos.
20932 The filter accepts the following options:
20936 Set number of inputs.
20937 Default is 3. Allowed range is from 3 to 255.
20938 If number of inputs is even number, than result will be mean value between two median values.
20941 Set which planes to filter. Default value is @code{15}, by which all planes are processed.
20944 Set median percentile. Default value is @code{0.5}.
20945 Default value of @code{0.5} will pick always median values, while @code{0} will pick
20946 minimum values, and @code{1} maximum values.
20950 Stack video inputs into custom layout.
20952 All streams must be of same pixel format.
20954 The filter accepts the following options:
20958 Set number of input streams. Default is 2.
20961 Specify layout of inputs.
20962 This option requires the desired layout configuration to be explicitly set by the user.
20963 This sets position of each video input in output. Each input
20964 is separated by '|'.
20965 The first number represents the column, and the second number represents the row.
20966 Numbers start at 0 and are separated by '_'. Optionally one can use wX and hX,
20967 where X is video input from which to take width or height.
20968 Multiple values can be used when separated by '+'. In such
20969 case values are summed together.
20971 Note that if inputs are of different sizes gaps may appear, as not all of
20972 the output video frame will be filled. Similarly, videos can overlap each
20973 other if their position doesn't leave enough space for the full frame of
20976 For 2 inputs, a default layout of @code{0_0|w0_0} is set. In all other cases,
20977 a layout must be set by the user.
20980 If set to 1, force the output to terminate when the shortest input
20981 terminates. Default value is 0.
20984 If set to valid color, all unused pixels will be filled with that color.
20985 By default fill is set to none, so it is disabled.
20988 @subsection Examples
20992 Display 4 inputs into 2x2 grid.
20996 input1(0, 0) | input3(w0, 0)
20997 input2(0, h0) | input4(w0, h0)
21001 xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
21004 Note that if inputs are of different sizes, gaps or overlaps may occur.
21007 Display 4 inputs into 1x4 grid.
21014 input4(0, h0+h1+h2)
21018 xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
21021 Note that if inputs are of different widths, unused space will appear.
21024 Display 9 inputs into 3x3 grid.
21028 input1(0, 0) | input4(w0, 0) | input7(w0+w3, 0)
21029 input2(0, h0) | input5(w0, h0) | input8(w0+w3, h0)
21030 input3(0, h0+h1) | input6(w0, h0+h1) | input9(w0+w3, h0+h1)
21034 xstack=inputs=9:layout=0_0|0_h0|0_h0+h1|w0_0|w0_h0|w0_h0+h1|w0+w3_0|w0+w3_h0|w0+w3_h0+h1
21037 Note that if inputs are of different sizes, gaps or overlaps may occur.
21040 Display 16 inputs into 4x4 grid.
21044 input1(0, 0) | input5(w0, 0) | input9 (w0+w4, 0) | input13(w0+w4+w8, 0)
21045 input2(0, h0) | input6(w0, h0) | input10(w0+w4, h0) | input14(w0+w4+w8, h0)
21046 input3(0, h0+h1) | input7(w0, h0+h1) | input11(w0+w4, h0+h1) | input15(w0+w4+w8, h0+h1)
21047 input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2)
21051 xstack=inputs=16:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2|w0_0|w0_h0|w0_h0+h1|w0_h0+h1+h2|w0+w4_0|
21052 w0+w4_h0|w0+w4_h0+h1|w0+w4_h0+h1+h2|w0+w4+w8_0|w0+w4+w8_h0|w0+w4+w8_h0+h1|w0+w4+w8_h0+h1+h2
21055 Note that if inputs are of different sizes, gaps or overlaps may occur.
21062 Deinterlace the input video ("yadif" means "yet another deinterlacing
21065 It accepts the following parameters:
21071 The interlacing mode to adopt. It accepts one of the following values:
21074 @item 0, send_frame
21075 Output one frame for each frame.
21076 @item 1, send_field
21077 Output one frame for each field.
21078 @item 2, send_frame_nospatial
21079 Like @code{send_frame}, but it skips the spatial interlacing check.
21080 @item 3, send_field_nospatial
21081 Like @code{send_field}, but it skips the spatial interlacing check.
21084 The default value is @code{send_frame}.
21087 The picture field parity assumed for the input interlaced video. It accepts one
21088 of the following values:
21092 Assume the top field is first.
21094 Assume the bottom field is first.
21096 Enable automatic detection of field parity.
21099 The default value is @code{auto}.
21100 If the interlacing is unknown or the decoder does not export this information,
21101 top field first will be assumed.
21104 Specify which frames to deinterlace. Accepts one of the following
21109 Deinterlace all frames.
21110 @item 1, interlaced
21111 Only deinterlace frames marked as interlaced.
21114 The default value is @code{all}.
21117 @section yadif_cuda
21119 Deinterlace the input video using the @ref{yadif} algorithm, but implemented
21120 in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec
21123 It accepts the following parameters:
21129 The interlacing mode to adopt. It accepts one of the following values:
21132 @item 0, send_frame
21133 Output one frame for each frame.
21134 @item 1, send_field
21135 Output one frame for each field.
21136 @item 2, send_frame_nospatial
21137 Like @code{send_frame}, but it skips the spatial interlacing check.
21138 @item 3, send_field_nospatial
21139 Like @code{send_field}, but it skips the spatial interlacing check.
21142 The default value is @code{send_frame}.
21145 The picture field parity assumed for the input interlaced video. It accepts one
21146 of the following values:
21150 Assume the top field is first.
21152 Assume the bottom field is first.
21154 Enable automatic detection of field parity.
21157 The default value is @code{auto}.
21158 If the interlacing is unknown or the decoder does not export this information,
21159 top field first will be assumed.
21162 Specify which frames to deinterlace. Accepts one of the following
21167 Deinterlace all frames.
21168 @item 1, interlaced
21169 Only deinterlace frames marked as interlaced.
21172 The default value is @code{all}.
21177 Apply blur filter while preserving edges ("yaepblur" means "yet another edge preserving blur filter").
21178 The algorithm is described in
21179 "J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980."
21181 It accepts the following parameters:
21185 Set the window radius. Default value is 3.
21188 Set which planes to filter. Default is only the first plane.
21191 Set blur strength. Default value is 128.
21194 @subsection Commands
21195 This filter supports same @ref{commands} as options.
21199 Apply Zoom & Pan effect.
21201 This filter accepts the following options:
21205 Set the zoom expression. Range is 1-10. Default is 1.
21209 Set the x and y expression. Default is 0.
21212 Set the duration expression in number of frames.
21213 This sets for how many number of frames effect will last for
21214 single input image.
21217 Set the output image size, default is 'hd720'.
21220 Set the output frame rate, default is '25'.
21223 Each expression can contain the following constants:
21242 Output frame count.
21245 The input timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
21247 @item out_time, time, ot
21248 The output timestamp expressed in seconds.
21252 Last calculated 'x' and 'y' position from 'x' and 'y' expression
21253 for current input frame.
21257 'x' and 'y' of last output frame of previous input frame or 0 when there was
21258 not yet such frame (first input frame).
21261 Last calculated zoom from 'z' expression for current input frame.
21264 Last calculated zoom of last output frame of previous input frame.
21267 Number of output frames for current input frame. Calculated from 'd' expression
21268 for each input frame.
21271 number of output frames created for previous input frame
21274 Rational number: input width / input height
21277 sample aspect ratio
21280 display aspect ratio
21284 @subsection Examples
21288 Zoom in up to 1.5x and pan at same time to some spot near center of picture:
21290 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
21294 Zoom in up to 1.5x and pan always at center of picture:
21296 zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
21300 Same as above but without pausing:
21302 zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
21306 Zoom in 2x into center of picture only for the first second of the input video:
21308 zoompan=z='if(between(in_time,0,1),2,1)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
21315 Scale (resize) the input video, using the z.lib library:
21316 @url{https://github.com/sekrit-twc/zimg}. To enable compilation of this
21317 filter, you need to configure FFmpeg with @code{--enable-libzimg}.
21319 The zscale filter forces the output display aspect ratio to be the same
21320 as the input, by changing the output sample aspect ratio.
21322 If the input image format is different from the format requested by
21323 the next filter, the zscale filter will convert the input to the
21326 @subsection Options
21327 The filter accepts the following options.
21332 Set the output video dimension expression. Default value is the input
21335 If the @var{width} or @var{w} value is 0, the input width is used for
21336 the output. If the @var{height} or @var{h} value is 0, the input height
21337 is used for the output.
21339 If one and only one of the values is -n with n >= 1, the zscale filter
21340 will use a value that maintains the aspect ratio of the input image,
21341 calculated from the other specified dimension. After that it will,
21342 however, make sure that the calculated dimension is divisible by n and
21343 adjust the value if necessary.
21345 If both values are -n with n >= 1, the behavior will be identical to
21346 both values being set to 0 as previously detailed.
21348 See below for the list of accepted constants for use in the dimension
21352 Set the video size. For the syntax of this option, check the
21353 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21356 Set the dither type.
21358 Possible values are:
21363 @item error_diffusion
21369 Set the resize filter type.
21371 Possible values are:
21381 Default is bilinear.
21384 Set the color range.
21386 Possible values are:
21393 Default is same as input.
21396 Set the color primaries.
21398 Possible values are:
21408 Default is same as input.
21411 Set the transfer characteristics.
21413 Possible values are:
21427 Default is same as input.
21430 Set the colorspace matrix.
21432 Possible value are:
21443 Default is same as input.
21446 Set the input color range.
21448 Possible values are:
21455 Default is same as input.
21457 @item primariesin, pin
21458 Set the input color primaries.
21460 Possible values are:
21470 Default is same as input.
21472 @item transferin, tin
21473 Set the input transfer characteristics.
21475 Possible values are:
21486 Default is same as input.
21488 @item matrixin, min
21489 Set the input colorspace matrix.
21491 Possible value are:
21503 Set the output chroma location.
21505 Possible values are:
21516 @item chromalin, cin
21517 Set the input chroma location.
21519 Possible values are:
21531 Set the nominal peak luminance.
21534 The values of the @option{w} and @option{h} options are expressions
21535 containing the following constants:
21540 The input width and height
21544 These are the same as @var{in_w} and @var{in_h}.
21548 The output (scaled) width and height
21552 These are the same as @var{out_w} and @var{out_h}
21555 The same as @var{iw} / @var{ih}
21558 input sample aspect ratio
21561 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
21565 horizontal and vertical input chroma subsample values. For example for the
21566 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
21570 horizontal and vertical output chroma subsample values. For example for the
21571 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
21574 @subsection Commands
21576 This filter supports the following commands:
21580 Set the output video dimension expression.
21581 The command accepts the same syntax of the corresponding option.
21583 If the specified expression is not valid, it is kept at its current
21587 @c man end VIDEO FILTERS
21589 @chapter OpenCL Video Filters
21590 @c man begin OPENCL VIDEO FILTERS
21592 Below is a description of the currently available OpenCL video filters.
21594 To enable compilation of these filters you need to configure FFmpeg with
21595 @code{--enable-opencl}.
21597 Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph.
21600 @item -init_hw_device opencl[=@var{name}][:@var{device}[,@var{key=value}...]]
21601 Initialise a new hardware device of type @var{opencl} called @var{name}, using the
21602 given device parameters.
21604 @item -filter_hw_device @var{name}
21605 Pass the hardware device called @var{name} to all filters in any filter graph.
21609 For more detailed information see @url{https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options}
21613 Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it.
21615 -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
21619 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.
21621 @section avgblur_opencl
21623 Apply average blur filter.
21625 The filter accepts the following options:
21629 Set horizontal radius size.
21630 Range is @code{[1, 1024]} and default value is @code{1}.
21633 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
21636 Set vertical radius size. Range is @code{[1, 1024]} and default value is @code{0}. If zero, @code{sizeX} value will be used.
21639 @subsection Example
21643 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.
21645 -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
21649 @section boxblur_opencl
21651 Apply a boxblur algorithm to the input video.
21653 It accepts the following parameters:
21657 @item luma_radius, lr
21658 @item luma_power, lp
21659 @item chroma_radius, cr
21660 @item chroma_power, cp
21661 @item alpha_radius, ar
21662 @item alpha_power, ap
21666 A description of the accepted options follows.
21669 @item luma_radius, lr
21670 @item chroma_radius, cr
21671 @item alpha_radius, ar
21672 Set an expression for the box radius in pixels used for blurring the
21673 corresponding input plane.
21675 The radius value must be a non-negative number, and must not be
21676 greater than the value of the expression @code{min(w,h)/2} for the
21677 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
21680 Default value for @option{luma_radius} is "2". If not specified,
21681 @option{chroma_radius} and @option{alpha_radius} default to the
21682 corresponding value set for @option{luma_radius}.
21684 The expressions can contain the following constants:
21688 The input width and height in pixels.
21692 The input chroma image width and height in pixels.
21696 The horizontal and vertical chroma subsample values. For example, for the
21697 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
21700 @item luma_power, lp
21701 @item chroma_power, cp
21702 @item alpha_power, ap
21703 Specify how many times the boxblur filter is applied to the
21704 corresponding plane.
21706 Default value for @option{luma_power} is 2. If not specified,
21707 @option{chroma_power} and @option{alpha_power} default to the
21708 corresponding value set for @option{luma_power}.
21710 A value of 0 will disable the effect.
21713 @subsection Examples
21715 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.
21719 Apply a boxblur filter with the luma, chroma, and alpha radius
21720 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.
21722 -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
21723 -i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
21727 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.
21729 For the luma plane, a 2x2 box radius will be run once.
21731 For the chroma plane, a 4x4 box radius will be run 5 times.
21733 For the alpha plane, a 3x3 box radius will be run 7 times.
21735 -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
21739 @section colorkey_opencl
21740 RGB colorspace color keying.
21742 The filter accepts the following options:
21746 The color which will be replaced with transparency.
21749 Similarity percentage with the key color.
21751 0.01 matches only the exact key color, while 1.0 matches everything.
21756 0.0 makes pixels either fully transparent, or not transparent at all.
21758 Higher values result in semi-transparent pixels, with a higher transparency
21759 the more similar the pixels color is to the key color.
21762 @subsection Examples
21766 Make every semi-green pixel in the input transparent with some slight blending:
21768 -i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
21772 @section convolution_opencl
21774 Apply convolution of 3x3, 5x5, 7x7 matrix.
21776 The filter accepts the following options:
21783 Set matrix for each plane.
21784 Matrix is sequence of 9, 25 or 49 signed numbers.
21785 Default value for each plane is @code{0 0 0 0 1 0 0 0 0}.
21791 Set multiplier for calculated value for each plane.
21792 If unset or 0, it will be sum of all matrix elements.
21793 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{1.0}.
21799 Set bias for each plane. This value is added to the result of the multiplication.
21800 Useful for making the overall image brighter or darker.
21801 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{0.0}.
21805 @subsection Examples
21811 -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
21817 -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
21821 Apply edge enhance:
21823 -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
21829 -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
21833 Apply laplacian edge detector which includes diagonals:
21835 -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
21841 -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
21845 @section erosion_opencl
21847 Apply erosion effect to the video.
21849 This filter replaces the pixel by the local(3x3) minimum.
21851 It accepts the following options:
21858 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
21859 If @code{0}, plane will remain unchanged.
21862 Flag which specifies the pixel to refer to.
21863 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
21865 Flags to local 3x3 coordinates region centered on @code{x}:
21874 @subsection Example
21878 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.
21880 -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
21884 @section deshake_opencl
21885 Feature-point based video stabilization filter.
21887 The filter accepts the following options:
21891 Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to @code{0}.
21894 Whether or not additional debug info should be displayed, both in the processed output and in the console.
21896 Note that in order to see console debug output you will also need to pass @code{-v verbose} to ffmpeg.
21898 Viewing point matches in the output video is only supported for RGB input.
21900 Defaults to @code{0}.
21902 @item adaptive_crop
21903 Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels.
21905 Defaults to @code{1}.
21907 @item refine_features
21908 Whether or not feature points should be refined at a sub-pixel level.
21910 This can be turned off for a slight performance gain at the cost of precision.
21912 Defaults to @code{1}.
21914 @item smooth_strength
21915 The strength of the smoothing applied to the camera path from @code{0.0} to @code{1.0}.
21917 @code{1.0} is the maximum smoothing strength while values less than that result in less smoothing.
21919 @code{0.0} causes the filter to adaptively choose a smoothing strength on a per-frame basis.
21921 Defaults to @code{0.0}.
21923 @item smooth_window_multiplier
21924 Controls the size of the smoothing window (the number of frames buffered to determine motion information from).
21926 The size of the smoothing window is determined by multiplying the framerate of the video by this number.
21928 Acceptable values range from @code{0.1} to @code{10.0}.
21930 Larger values increase the amount of motion data available for determining how to smooth the camera path,
21931 potentially improving smoothness, but also increase latency and memory usage.
21933 Defaults to @code{2.0}.
21937 @subsection Examples
21941 Stabilize a video with a fixed, medium smoothing strength:
21943 -i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT
21947 Stabilize a video with debugging (both in console and in rendered video):
21949 -i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT
21953 @section dilation_opencl
21955 Apply dilation effect to the video.
21957 This filter replaces the pixel by the local(3x3) maximum.
21959 It accepts the following options:
21966 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
21967 If @code{0}, plane will remain unchanged.
21970 Flag which specifies the pixel to refer to.
21971 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
21973 Flags to local 3x3 coordinates region centered on @code{x}:
21982 @subsection Example
21986 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.
21988 -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
21992 @section nlmeans_opencl
21994 Non-local Means denoise filter through OpenCL, this filter accepts same options as @ref{nlmeans}.
21996 @section overlay_opencl
21998 Overlay one video on top of another.
22000 It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid.
22001 This filter requires same memory layout for all the inputs. So, format conversion may be needed.
22003 The filter accepts the following options:
22008 Set the x coordinate of the overlaid video on the main video.
22009 Default value is @code{0}.
22012 Set the y coordinate of the overlaid video on the main video.
22013 Default value is @code{0}.
22017 @subsection Examples
22021 Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format.
22023 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
22026 The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p.
22028 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
22033 @section pad_opencl
22035 Add paddings to the input image, and place the original input at the
22036 provided @var{x}, @var{y} coordinates.
22038 It accepts the following options:
22043 Specify an expression for the size of the output image with the
22044 paddings added. If the value for @var{width} or @var{height} is 0, the
22045 corresponding input size is used for the output.
22047 The @var{width} expression can reference the value set by the
22048 @var{height} expression, and vice versa.
22050 The default value of @var{width} and @var{height} is 0.
22054 Specify the offsets to place the input image at within the padded area,
22055 with respect to the top/left border of the output image.
22057 The @var{x} expression can reference the value set by the @var{y}
22058 expression, and vice versa.
22060 The default value of @var{x} and @var{y} is 0.
22062 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
22063 so the input image is centered on the padded area.
22066 Specify the color of the padded area. For the syntax of this option,
22067 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
22068 manual,ffmpeg-utils}.
22071 Pad to an aspect instead to a resolution.
22074 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
22075 options are expressions containing the following constants:
22080 The input video width and height.
22084 These are the same as @var{in_w} and @var{in_h}.
22088 The output width and height (the size of the padded area), as
22089 specified by the @var{width} and @var{height} expressions.
22093 These are the same as @var{out_w} and @var{out_h}.
22097 The x and y offsets as specified by the @var{x} and @var{y}
22098 expressions, or NAN if not yet specified.
22101 same as @var{iw} / @var{ih}
22104 input sample aspect ratio
22107 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
22110 @section prewitt_opencl
22112 Apply the Prewitt operator (@url{https://en.wikipedia.org/wiki/Prewitt_operator}) to input video stream.
22114 The filter accepts the following option:
22118 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
22121 Set value which will be multiplied with filtered result.
22122 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
22125 Set value which will be added to filtered result.
22126 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
22129 @subsection Example
22133 Apply the Prewitt operator with scale set to 2 and delta set to 10.
22135 -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
22139 @anchor{program_opencl}
22140 @section program_opencl
22142 Filter video using an OpenCL program.
22147 OpenCL program source file.
22150 Kernel name in program.
22153 Number of inputs to the filter. Defaults to 1.
22156 Size of output frames. Defaults to the same as the first input.
22160 The @code{program_opencl} filter also supports the @ref{framesync} options.
22162 The program source file must contain a kernel function with the given name,
22163 which will be run once for each plane of the output. Each run on a plane
22164 gets enqueued as a separate 2D global NDRange with one work-item for each
22165 pixel to be generated. The global ID offset for each work-item is therefore
22166 the coordinates of a pixel in the destination image.
22168 The kernel function needs to take the following arguments:
22171 Destination image, @var{__write_only image2d_t}.
22173 This image will become the output; the kernel should write all of it.
22175 Frame index, @var{unsigned int}.
22177 This is a counter starting from zero and increasing by one for each frame.
22179 Source images, @var{__read_only image2d_t}.
22181 These are the most recent images on each input. The kernel may read from
22182 them to generate the output, but they can't be written to.
22189 Copy the input to the output (output must be the same size as the input).
22191 __kernel void copy(__write_only image2d_t destination,
22192 unsigned int index,
22193 __read_only image2d_t source)
22195 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
22197 int2 location = (int2)(get_global_id(0), get_global_id(1));
22199 float4 value = read_imagef(source, sampler, location);
22201 write_imagef(destination, location, value);
22206 Apply a simple transformation, rotating the input by an amount increasing
22207 with the index counter. Pixel values are linearly interpolated by the
22208 sampler, and the output need not have the same dimensions as the input.
22210 __kernel void rotate_image(__write_only image2d_t dst,
22211 unsigned int index,
22212 __read_only image2d_t src)
22214 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
22215 CLK_FILTER_LINEAR);
22217 float angle = (float)index / 100.0f;
22219 float2 dst_dim = convert_float2(get_image_dim(dst));
22220 float2 src_dim = convert_float2(get_image_dim(src));
22222 float2 dst_cen = dst_dim / 2.0f;
22223 float2 src_cen = src_dim / 2.0f;
22225 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
22227 float2 dst_pos = convert_float2(dst_loc) - dst_cen;
22229 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
22230 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
22232 src_pos = src_pos * src_dim / dst_dim;
22234 float2 src_loc = src_pos + src_cen;
22236 if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
22237 src_loc.x > src_dim.x || src_loc.y > src_dim.y)
22238 write_imagef(dst, dst_loc, 0.5f);
22240 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
22245 Blend two inputs together, with the amount of each input used varying
22246 with the index counter.
22248 __kernel void blend_images(__write_only image2d_t dst,
22249 unsigned int index,
22250 __read_only image2d_t src1,
22251 __read_only image2d_t src2)
22253 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
22254 CLK_FILTER_LINEAR);
22256 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
22258 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
22259 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
22260 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
22262 float4 val1 = read_imagef(src1, sampler, src1_loc);
22263 float4 val2 = read_imagef(src2, sampler, src2_loc);
22265 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
22271 @section roberts_opencl
22272 Apply the Roberts cross operator (@url{https://en.wikipedia.org/wiki/Roberts_cross}) to input video stream.
22274 The filter accepts the following option:
22278 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
22281 Set value which will be multiplied with filtered result.
22282 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
22285 Set value which will be added to filtered result.
22286 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
22289 @subsection Example
22293 Apply the Roberts cross operator with scale set to 2 and delta set to 10
22295 -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
22299 @section sobel_opencl
22301 Apply the Sobel operator (@url{https://en.wikipedia.org/wiki/Sobel_operator}) to input video stream.
22303 The filter accepts the following option:
22307 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
22310 Set value which will be multiplied with filtered result.
22311 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
22314 Set value which will be added to filtered result.
22315 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
22318 @subsection Example
22322 Apply sobel operator with scale set to 2 and delta set to 10
22324 -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
22328 @section tonemap_opencl
22330 Perform HDR(PQ/HLG) to SDR conversion with tone-mapping.
22332 It accepts the following parameters:
22336 Specify the tone-mapping operator to be used. Same as tonemap option in @ref{tonemap}.
22339 Tune the tone mapping algorithm. same as param option in @ref{tonemap}.
22342 Apply desaturation for highlights that exceed this level of brightness. The
22343 higher the parameter, the more color information will be preserved. This
22344 setting helps prevent unnaturally blown-out colors for super-highlights, by
22345 (smoothly) turning into white instead. This makes images feel more natural,
22346 at the cost of reducing information about out-of-range colors.
22348 The default value is 0.5, and the algorithm here is a little different from
22349 the cpu version tonemap currently. A setting of 0.0 disables this option.
22352 The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold
22353 is used to detect whether the scene has changed or not. If the distance between
22354 the current frame average brightness and the current running average exceeds
22355 a threshold value, we would re-calculate scene average and peak brightness.
22356 The default value is 0.2.
22359 Specify the output pixel format.
22361 Currently supported formats are:
22368 Set the output color range.
22370 Possible values are:
22376 Default is same as input.
22379 Set the output color primaries.
22381 Possible values are:
22387 Default is same as input.
22390 Set the output transfer characteristics.
22392 Possible values are:
22401 Set the output colorspace matrix.
22403 Possible value are:
22409 Default is same as input.
22413 @subsection Example
22417 Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator.
22419 -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
22423 @section unsharp_opencl
22425 Sharpen or blur the input video.
22427 It accepts the following parameters:
22430 @item luma_msize_x, lx
22431 Set the luma matrix horizontal size.
22432 Range is @code{[1, 23]} and default value is @code{5}.
22434 @item luma_msize_y, ly
22435 Set the luma matrix vertical size.
22436 Range is @code{[1, 23]} and default value is @code{5}.
22438 @item luma_amount, la
22439 Set the luma effect strength.
22440 Range is @code{[-10, 10]} and default value is @code{1.0}.
22442 Negative values will blur the input video, while positive values will
22443 sharpen it, a value of zero will disable the effect.
22445 @item chroma_msize_x, cx
22446 Set the chroma matrix horizontal size.
22447 Range is @code{[1, 23]} and default value is @code{5}.
22449 @item chroma_msize_y, cy
22450 Set the chroma matrix vertical size.
22451 Range is @code{[1, 23]} and default value is @code{5}.
22453 @item chroma_amount, ca
22454 Set the chroma effect strength.
22455 Range is @code{[-10, 10]} and default value is @code{0.0}.
22457 Negative values will blur the input video, while positive values will
22458 sharpen it, a value of zero will disable the effect.
22462 All parameters are optional and default to the equivalent of the
22463 string '5:5:1.0:5:5:0.0'.
22465 @subsection Examples
22469 Apply strong luma sharpen effect:
22471 -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
22475 Apply a strong blur of both luma and chroma parameters:
22477 -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
22481 @section xfade_opencl
22483 Cross fade two videos with custom transition effect by using OpenCL.
22485 It accepts the following options:
22489 Set one of possible transition effects.
22493 Select custom transition effect, the actual transition description
22494 will be picked from source and kernel options.
22506 Default transition is fade.
22510 OpenCL program source file for custom transition.
22513 Set name of kernel to use for custom transition from program source file.
22516 Set duration of video transition.
22519 Set time of start of transition relative to first video.
22522 The program source file must contain a kernel function with the given name,
22523 which will be run once for each plane of the output. Each run on a plane
22524 gets enqueued as a separate 2D global NDRange with one work-item for each
22525 pixel to be generated. The global ID offset for each work-item is therefore
22526 the coordinates of a pixel in the destination image.
22528 The kernel function needs to take the following arguments:
22531 Destination image, @var{__write_only image2d_t}.
22533 This image will become the output; the kernel should write all of it.
22536 First Source image, @var{__read_only image2d_t}.
22537 Second Source image, @var{__read_only image2d_t}.
22539 These are the most recent images on each input. The kernel may read from
22540 them to generate the output, but they can't be written to.
22543 Transition progress, @var{float}. This value is always between 0 and 1 inclusive.
22550 Apply dots curtain transition effect:
22552 __kernel void blend_images(__write_only image2d_t dst,
22553 __read_only image2d_t src1,
22554 __read_only image2d_t src2,
22557 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
22558 CLK_FILTER_LINEAR);
22559 int2 p = (int2)(get_global_id(0), get_global_id(1));
22560 float2 rp = (float2)(get_global_id(0), get_global_id(1));
22561 float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y);
22564 float2 dots = (float2)(20.0, 20.0);
22565 float2 center = (float2)(0,0);
22568 float4 val1 = read_imagef(src1, sampler, p);
22569 float4 val2 = read_imagef(src2, sampler, p);
22570 bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center));
22572 write_imagef(dst, p, next ? val1 : val2);
22578 @c man end OPENCL VIDEO FILTERS
22580 @chapter VAAPI Video Filters
22581 @c man begin VAAPI VIDEO FILTERS
22583 VAAPI Video filters are usually used with VAAPI decoder and VAAPI encoder. Below is a description of VAAPI video filters.
22585 To enable compilation of these filters you need to configure FFmpeg with
22586 @code{--enable-vaapi}.
22588 To use vaapi filters, you need to setup the vaapi device correctly. For more information, please read @url{https://trac.ffmpeg.org/wiki/Hardware/VAAPI}
22590 @section tonemap_vaapi
22592 Perform HDR(High Dynamic Range) to SDR(Standard Dynamic Range) conversion with tone-mapping.
22593 It maps the dynamic range of HDR10 content to the SDR content.
22594 It currently only accepts HDR10 as input.
22596 It accepts the following parameters:
22600 Specify the output pixel format.
22602 Currently supported formats are:
22611 Set the output color primaries.
22613 Default is same as input.
22616 Set the output transfer characteristics.
22621 Set the output colorspace matrix.
22623 Default is same as input.
22627 @subsection Example
22631 Convert HDR(HDR10) video to bt2020-transfer-characteristic p010 format
22633 tonemap_vaapi=format=p010:t=bt2020-10
22637 @c man end VAAPI VIDEO FILTERS
22639 @chapter Video Sources
22640 @c man begin VIDEO SOURCES
22642 Below is a description of the currently available video sources.
22646 Buffer video frames, and make them available to the filter chain.
22648 This source is mainly intended for a programmatic use, in particular
22649 through the interface defined in @file{libavfilter/buffersrc.h}.
22651 It accepts the following parameters:
22656 Specify the size (width and height) of the buffered video frames. For the
22657 syntax of this option, check the
22658 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22661 The input video width.
22664 The input video height.
22667 A string representing the pixel format of the buffered video frames.
22668 It may be a number corresponding to a pixel format, or a pixel format
22672 Specify the timebase assumed by the timestamps of the buffered frames.
22675 Specify the frame rate expected for the video stream.
22677 @item pixel_aspect, sar
22678 The sample (pixel) aspect ratio of the input video.
22681 This option is deprecated and ignored. Prepend @code{sws_flags=@var{flags};}
22682 to the filtergraph description to specify swscale flags for automatically
22683 inserted scalers. See @ref{Filtergraph syntax}.
22685 @item hw_frames_ctx
22686 When using a hardware pixel format, this should be a reference to an
22687 AVHWFramesContext describing input frames.
22692 buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
22695 will instruct the source to accept video frames with size 320x240 and
22696 with format "yuv410p", assuming 1/24 as the timestamps timebase and
22697 square pixels (1:1 sample aspect ratio).
22698 Since the pixel format with name "yuv410p" corresponds to the number 6
22699 (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
22700 this example corresponds to:
22702 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
22705 Alternatively, the options can be specified as a flat string, but this
22706 syntax is deprecated:
22708 @var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den}
22712 Create a pattern generated by an elementary cellular automaton.
22714 The initial state of the cellular automaton can be defined through the
22715 @option{filename} and @option{pattern} options. If such options are
22716 not specified an initial state is created randomly.
22718 At each new frame a new row in the video is filled with the result of
22719 the cellular automaton next generation. The behavior when the whole
22720 frame is filled is defined by the @option{scroll} option.
22722 This source accepts the following options:
22726 Read the initial cellular automaton state, i.e. the starting row, from
22727 the specified file.
22728 In the file, each non-whitespace character is considered an alive
22729 cell, a newline will terminate the row, and further characters in the
22730 file will be ignored.
22733 Read the initial cellular automaton state, i.e. the starting row, from
22734 the specified string.
22736 Each non-whitespace character in the string is considered an alive
22737 cell, a newline will terminate the row, and further characters in the
22738 string will be ignored.
22741 Set the video rate, that is the number of frames generated per second.
22744 @item random_fill_ratio, ratio
22745 Set the random fill ratio for the initial cellular automaton row. It
22746 is a floating point number value ranging from 0 to 1, defaults to
22749 This option is ignored when a file or a pattern is specified.
22751 @item random_seed, seed
22752 Set the seed for filling randomly the initial row, must be an integer
22753 included between 0 and UINT32_MAX. If not specified, or if explicitly
22754 set to -1, the filter will try to use a good random seed on a best
22758 Set the cellular automaton rule, it is a number ranging from 0 to 255.
22759 Default value is 110.
22762 Set the size of the output video. For the syntax of this option, check the
22763 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22765 If @option{filename} or @option{pattern} is specified, the size is set
22766 by default to the width of the specified initial state row, and the
22767 height is set to @var{width} * PHI.
22769 If @option{size} is set, it must contain the width of the specified
22770 pattern string, and the specified pattern will be centered in the
22773 If a filename or a pattern string is not specified, the size value
22774 defaults to "320x518" (used for a randomly generated initial state).
22777 If set to 1, scroll the output upward when all the rows in the output
22778 have been already filled. If set to 0, the new generated row will be
22779 written over the top row just after the bottom row is filled.
22782 @item start_full, full
22783 If set to 1, completely fill the output with generated rows before
22784 outputting the first frame.
22785 This is the default behavior, for disabling set the value to 0.
22788 If set to 1, stitch the left and right row edges together.
22789 This is the default behavior, for disabling set the value to 0.
22792 @subsection Examples
22796 Read the initial state from @file{pattern}, and specify an output of
22799 cellauto=f=pattern:s=200x400
22803 Generate a random initial row with a width of 200 cells, with a fill
22806 cellauto=ratio=2/3:s=200x200
22810 Create a pattern generated by rule 18 starting by a single alive cell
22811 centered on an initial row with width 100:
22813 cellauto=p=@@:s=100x400:full=0:rule=18
22817 Specify a more elaborated initial pattern:
22819 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
22824 @anchor{coreimagesrc}
22825 @section coreimagesrc
22826 Video source generated on GPU using Apple's CoreImage API on OSX.
22828 This video source is a specialized version of the @ref{coreimage} video filter.
22829 Use a core image generator at the beginning of the applied filterchain to
22830 generate the content.
22832 The coreimagesrc video source accepts the following options:
22834 @item list_generators
22835 List all available generators along with all their respective options as well as
22836 possible minimum and maximum values along with the default values.
22838 list_generators=true
22842 Specify the size of the sourced video. For the syntax of this option, check the
22843 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22844 The default value is @code{320x240}.
22847 Specify the frame rate of the sourced video, as the number of frames
22848 generated per second. It has to be a string in the format
22849 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
22850 number or a valid video frame rate abbreviation. The default value is
22854 Set the sample aspect ratio of the sourced video.
22857 Set the duration of the sourced video. See
22858 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
22859 for the accepted syntax.
22861 If not specified, or the expressed duration is negative, the video is
22862 supposed to be generated forever.
22865 Additionally, all options of the @ref{coreimage} video filter are accepted.
22866 A complete filterchain can be used for further processing of the
22867 generated input without CPU-HOST transfer. See @ref{coreimage} documentation
22868 and examples for details.
22870 @subsection Examples
22875 Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
22876 given as complete and escaped command-line for Apple's standard bash shell:
22878 ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
22880 This example is equivalent to the QRCode example of @ref{coreimage} without the
22881 need for a nullsrc video source.
22886 Generate several gradients.
22890 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
22891 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
22894 Set frame rate, expressed as number of frames per second. Default
22897 @item c0, c1, c2, c3, c4, c5, c6, c7
22898 Set 8 colors. Default values for colors is to pick random one.
22900 @item x0, y0, y0, y1
22901 Set gradient line source and destination points. If negative or out of range, random ones
22905 Set number of colors to use at once. Allowed range is from 2 to 8. Default value is 2.
22908 Set seed for picking gradient line points.
22911 Set the duration of the sourced video. See
22912 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
22913 for the accepted syntax.
22915 If not specified, or the expressed duration is negative, the video is
22916 supposed to be generated forever.
22919 Set speed of gradients rotation.
22923 @section mandelbrot
22925 Generate a Mandelbrot set fractal, and progressively zoom towards the
22926 point specified with @var{start_x} and @var{start_y}.
22928 This source accepts the following options:
22933 Set the terminal pts value. Default value is 400.
22936 Set the terminal scale value.
22937 Must be a floating point value. Default value is 0.3.
22940 Set the inner coloring mode, that is the algorithm used to draw the
22941 Mandelbrot fractal internal region.
22943 It shall assume one of the following values:
22948 Show time until convergence.
22950 Set color based on point closest to the origin of the iterations.
22955 Default value is @var{mincol}.
22958 Set the bailout value. Default value is 10.0.
22961 Set the maximum of iterations performed by the rendering
22962 algorithm. Default value is 7189.
22965 Set outer coloring mode.
22966 It shall assume one of following values:
22968 @item iteration_count
22969 Set iteration count mode.
22970 @item normalized_iteration_count
22971 set normalized iteration count mode.
22973 Default value is @var{normalized_iteration_count}.
22976 Set frame rate, expressed as number of frames per second. Default
22980 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
22981 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
22984 Set the initial scale value. Default value is 3.0.
22987 Set the initial x position. Must be a floating point value between
22988 -100 and 100. Default value is -0.743643887037158704752191506114774.
22991 Set the initial y position. Must be a floating point value between
22992 -100 and 100. Default value is -0.131825904205311970493132056385139.
22997 Generate various test patterns, as generated by the MPlayer test filter.
22999 The size of the generated video is fixed, and is 256x256.
23000 This source is useful in particular for testing encoding features.
23002 This source accepts the following options:
23007 Specify the frame rate of the sourced video, as the number of frames
23008 generated per second. It has to be a string in the format
23009 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
23010 number or a valid video frame rate abbreviation. The default value is
23014 Set the duration of the sourced video. See
23015 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
23016 for the accepted syntax.
23018 If not specified, or the expressed duration is negative, the video is
23019 supposed to be generated forever.
23023 Set the number or the name of the test to perform. Supported tests are:
23037 @item max_frames, m
23038 Set the maximum number of frames generated for each test, default value is 30.
23042 Default value is "all", which will cycle through the list of all tests.
23047 mptestsrc=t=dc_luma
23050 will generate a "dc_luma" test pattern.
23052 @section frei0r_src
23054 Provide a frei0r source.
23056 To enable compilation of this filter you need to install the frei0r
23057 header and configure FFmpeg with @code{--enable-frei0r}.
23059 This source accepts the following parameters:
23064 The size of the video to generate. For the syntax of this option, check the
23065 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23068 The framerate of the generated video. It may be a string of the form
23069 @var{num}/@var{den} or a frame rate abbreviation.
23072 The name to the frei0r source to load. For more information regarding frei0r and
23073 how to set the parameters, read the @ref{frei0r} section in the video filters
23076 @item filter_params
23077 A '|'-separated list of parameters to pass to the frei0r source.
23081 For example, to generate a frei0r partik0l source with size 200x200
23082 and frame rate 10 which is overlaid on the overlay filter main input:
23084 frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
23089 Generate a life pattern.
23091 This source is based on a generalization of John Conway's life game.
23093 The sourced input represents a life grid, each pixel represents a cell
23094 which can be in one of two possible states, alive or dead. Every cell
23095 interacts with its eight neighbours, which are the cells that are
23096 horizontally, vertically, or diagonally adjacent.
23098 At each interaction the grid evolves according to the adopted rule,
23099 which specifies the number of neighbor alive cells which will make a
23100 cell stay alive or born. The @option{rule} option allows one to specify
23103 This source accepts the following options:
23107 Set the file from which to read the initial grid state. In the file,
23108 each non-whitespace character is considered an alive cell, and newline
23109 is used to delimit the end of each row.
23111 If this option is not specified, the initial grid is generated
23115 Set the video rate, that is the number of frames generated per second.
23118 @item random_fill_ratio, ratio
23119 Set the random fill ratio for the initial random grid. It is a
23120 floating point number value ranging from 0 to 1, defaults to 1/PHI.
23121 It is ignored when a file is specified.
23123 @item random_seed, seed
23124 Set the seed for filling the initial random grid, must be an integer
23125 included between 0 and UINT32_MAX. If not specified, or if explicitly
23126 set to -1, the filter will try to use a good random seed on a best
23132 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
23133 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
23134 @var{NS} specifies the number of alive neighbor cells which make a
23135 live cell stay alive, and @var{NB} the number of alive neighbor cells
23136 which make a dead cell to become alive (i.e. to "born").
23137 "s" and "b" can be used in place of "S" and "B", respectively.
23139 Alternatively a rule can be specified by an 18-bits integer. The 9
23140 high order bits are used to encode the next cell state if it is alive
23141 for each number of neighbor alive cells, the low order bits specify
23142 the rule for "borning" new cells. Higher order bits encode for an
23143 higher number of neighbor cells.
23144 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
23145 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
23147 Default value is "S23/B3", which is the original Conway's game of life
23148 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
23149 cells, and will born a new cell if there are three alive cells around
23153 Set the size of the output video. For the syntax of this option, check the
23154 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23156 If @option{filename} is specified, the size is set by default to the
23157 same size of the input file. If @option{size} is set, it must contain
23158 the size specified in the input file, and the initial grid defined in
23159 that file is centered in the larger resulting area.
23161 If a filename is not specified, the size value defaults to "320x240"
23162 (used for a randomly generated initial grid).
23165 If set to 1, stitch the left and right grid edges together, and the
23166 top and bottom edges also. Defaults to 1.
23169 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
23170 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
23171 value from 0 to 255.
23174 Set the color of living (or new born) cells.
23177 Set the color of dead cells. If @option{mold} is set, this is the first color
23178 used to represent a dead cell.
23181 Set mold color, for definitely dead and moldy cells.
23183 For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the
23184 ffmpeg-utils manual,ffmpeg-utils}.
23187 @subsection Examples
23191 Read a grid from @file{pattern}, and center it on a grid of size
23194 life=f=pattern:s=300x300
23198 Generate a random grid of size 200x200, with a fill ratio of 2/3:
23200 life=ratio=2/3:s=200x200
23204 Specify a custom rule for evolving a randomly generated grid:
23210 Full example with slow death effect (mold) using @command{ffplay}:
23212 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
23219 @anchor{haldclutsrc}
23222 @anchor{pal100bars}
23223 @anchor{rgbtestsrc}
23225 @anchor{smptehdbars}
23228 @anchor{yuvtestsrc}
23229 @section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
23231 The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
23233 The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
23235 The @code{color} source provides an uniformly colored input.
23237 The @code{haldclutsrc} source provides an identity Hald CLUT. See also
23238 @ref{haldclut} filter.
23240 The @code{nullsrc} source returns unprocessed video frames. It is
23241 mainly useful to be employed in analysis / debugging tools, or as the
23242 source for filters which ignore the input data.
23244 The @code{pal75bars} source generates a color bars pattern, based on
23245 EBU PAL recommendations with 75% color levels.
23247 The @code{pal100bars} source generates a color bars pattern, based on
23248 EBU PAL recommendations with 100% color levels.
23250 The @code{rgbtestsrc} source generates an RGB test pattern useful for
23251 detecting RGB vs BGR issues. You should see a red, green and blue
23252 stripe from top to bottom.
23254 The @code{smptebars} source generates a color bars pattern, based on
23255 the SMPTE Engineering Guideline EG 1-1990.
23257 The @code{smptehdbars} source generates a color bars pattern, based on
23258 the SMPTE RP 219-2002.
23260 The @code{testsrc} source generates a test video pattern, showing a
23261 color pattern, a scrolling gradient and a timestamp. This is mainly
23262 intended for testing purposes.
23264 The @code{testsrc2} source is similar to testsrc, but supports more
23265 pixel formats instead of just @code{rgb24}. This allows using it as an
23266 input for other tests without requiring a format conversion.
23268 The @code{yuvtestsrc} source generates an YUV test pattern. You should
23269 see a y, cb and cr stripe from top to bottom.
23271 The sources accept the following parameters:
23276 Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
23277 source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
23278 pixels to be used as identity matrix for 3D lookup tables. Each component is
23279 coded on a @code{1/(N*N)} scale.
23282 Specify the color of the source, only available in the @code{color}
23283 source. For the syntax of this option, check the
23284 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
23287 Specify the size of the sourced video. For the syntax of this option, check the
23288 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23289 The default value is @code{320x240}.
23291 This option is not available with the @code{allrgb}, @code{allyuv}, and
23292 @code{haldclutsrc} filters.
23295 Specify the frame rate of the sourced video, as the number of frames
23296 generated per second. It has to be a string in the format
23297 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
23298 number or a valid video frame rate abbreviation. The default value is
23302 Set the duration of the sourced video. See
23303 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
23304 for the accepted syntax.
23306 If not specified, or the expressed duration is negative, the video is
23307 supposed to be generated forever.
23309 Since the frame rate is used as time base, all frames including the last one
23310 will have their full duration. If the specified duration is not a multiple
23311 of the frame duration, it will be rounded up.
23314 Set the sample aspect ratio of the sourced video.
23317 Specify the alpha (opacity) of the background, only available in the
23318 @code{testsrc2} source. The value must be between 0 (fully transparent) and
23319 255 (fully opaque, the default).
23322 Set the number of decimals to show in the timestamp, only available in the
23323 @code{testsrc} source.
23325 The displayed timestamp value will correspond to the original
23326 timestamp value multiplied by the power of 10 of the specified
23327 value. Default value is 0.
23330 @subsection Examples
23334 Generate a video with a duration of 5.3 seconds, with size
23335 176x144 and a frame rate of 10 frames per second:
23337 testsrc=duration=5.3:size=qcif:rate=10
23341 The following graph description will generate a red source
23342 with an opacity of 0.2, with size "qcif" and a frame rate of 10
23345 color=c=red@@0.2:s=qcif:r=10
23349 If the input content is to be ignored, @code{nullsrc} can be used. The
23350 following command generates noise in the luminance plane by employing
23351 the @code{geq} filter:
23353 nullsrc=s=256x256, geq=random(1)*255:128:128
23357 @subsection Commands
23359 The @code{color} source supports the following commands:
23363 Set the color of the created image. Accepts the same syntax of the
23364 corresponding @option{color} option.
23369 Generate video using an OpenCL program.
23374 OpenCL program source file.
23377 Kernel name in program.
23380 Size of frames to generate. This must be set.
23383 Pixel format to use for the generated frames. This must be set.
23386 Number of frames generated every second. Default value is '25'.
23390 For details of how the program loading works, see the @ref{program_opencl}
23397 Generate a colour ramp by setting pixel values from the position of the pixel
23398 in the output image. (Note that this will work with all pixel formats, but
23399 the generated output will not be the same.)
23401 __kernel void ramp(__write_only image2d_t dst,
23402 unsigned int index)
23404 int2 loc = (int2)(get_global_id(0), get_global_id(1));
23407 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
23409 write_imagef(dst, loc, val);
23414 Generate a Sierpinski carpet pattern, panning by a single pixel each frame.
23416 __kernel void sierpinski_carpet(__write_only image2d_t dst,
23417 unsigned int index)
23419 int2 loc = (int2)(get_global_id(0), get_global_id(1));
23421 float4 value = 0.0f;
23422 int x = loc.x + index;
23423 int y = loc.y + index;
23424 while (x > 0 || y > 0) {
23425 if (x % 3 == 1 && y % 3 == 1) {
23433 write_imagef(dst, loc, value);
23439 @section sierpinski
23441 Generate a Sierpinski carpet/triangle fractal, and randomly pan around.
23443 This source accepts the following options:
23447 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
23448 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
23451 Set frame rate, expressed as number of frames per second. Default
23455 Set seed which is used for random panning.
23458 Set max jump for single pan destination. Allowed range is from 1 to 10000.
23461 Set fractal type, can be default @code{carpet} or @code{triangle}.
23464 @c man end VIDEO SOURCES
23466 @chapter Video Sinks
23467 @c man begin VIDEO SINKS
23469 Below is a description of the currently available video sinks.
23471 @section buffersink
23473 Buffer video frames, and make them available to the end of the filter
23476 This sink is mainly intended for programmatic use, in particular
23477 through the interface defined in @file{libavfilter/buffersink.h}
23478 or the options system.
23480 It accepts a pointer to an AVBufferSinkContext structure, which
23481 defines the incoming buffers' formats, to be passed as the opaque
23482 parameter to @code{avfilter_init_filter} for initialization.
23486 Null video sink: do absolutely nothing with the input video. It is
23487 mainly useful as a template and for use in analysis / debugging
23490 @c man end VIDEO SINKS
23492 @chapter Multimedia Filters
23493 @c man begin MULTIMEDIA FILTERS
23495 Below is a description of the currently available multimedia filters.
23499 Convert input audio to a video output, displaying the audio bit scope.
23501 The filter accepts the following options:
23505 Set frame rate, expressed as number of frames per second. Default
23509 Specify the video size for the output. For the syntax of this option, check the
23510 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23511 Default value is @code{1024x256}.
23514 Specify list of colors separated by space or by '|' which will be used to
23515 draw channels. Unrecognized or missing colors will be replaced
23519 @section adrawgraph
23520 Draw a graph using input audio metadata.
23522 See @ref{drawgraph}
23524 @section agraphmonitor
23526 See @ref{graphmonitor}.
23528 @section ahistogram
23530 Convert input audio to a video output, displaying the volume histogram.
23532 The filter accepts the following options:
23536 Specify how histogram is calculated.
23538 It accepts the following values:
23541 Use single histogram for all channels.
23543 Use separate histogram for each channel.
23545 Default is @code{single}.
23548 Set frame rate, expressed as number of frames per second. Default
23552 Specify the video size for the output. For the syntax of this option, check the
23553 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23554 Default value is @code{hd720}.
23559 It accepts the following values:
23570 reverse logarithmic
23572 Default is @code{log}.
23575 Set amplitude scale.
23577 It accepts the following values:
23584 Default is @code{log}.
23587 Set how much frames to accumulate in histogram.
23588 Default is 1. Setting this to -1 accumulates all frames.
23591 Set histogram ratio of window height.
23594 Set sonogram sliding.
23596 It accepts the following values:
23599 replace old rows with new ones.
23601 scroll from top to bottom.
23603 Default is @code{replace}.
23606 @section aphasemeter
23608 Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase},
23609 representing mean phase of current audio frame. A video output can also be produced and is
23610 enabled by default. The audio is passed through as first output.
23612 Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in
23613 range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase
23614 and @code{1} means channels are in phase.
23616 The filter accepts the following options, all related to its video output:
23620 Set the output frame rate. Default value is @code{25}.
23623 Set the video size for the output. For the syntax of this option, check the
23624 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23625 Default value is @code{800x400}.
23630 Specify the red, green, blue contrast. Default values are @code{2},
23631 @code{7} and @code{1}.
23632 Allowed range is @code{[0, 255]}.
23635 Set color which will be used for drawing median phase. If color is
23636 @code{none} which is default, no median phase value will be drawn.
23639 Enable video output. Default is enabled.
23642 @subsection phasing detection
23644 The filter also detects out of phase and mono sequences in stereo streams.
23645 It logs the sequence start, end and duration when it lasts longer or as long as the minimum set.
23647 The filter accepts the following options for this detection:
23651 Enable mono and out of phase detection. Default is disabled.
23654 Set phase tolerance for mono detection, in amplitude ratio. Default is @code{0}.
23655 Allowed range is @code{[0, 1]}.
23658 Set angle threshold for out of phase detection, in degree. Default is @code{170}.
23659 Allowed range is @code{[90, 180]}.
23662 Set mono or out of phase duration until notification, expressed in seconds. Default is @code{2}.
23665 @subsection Examples
23669 Complete example with @command{ffmpeg} to detect 1 second of mono with 0.001 phase tolerance:
23671 ffmpeg -i stereo.wav -af aphasemeter=video=0:phasing=1:duration=1:tolerance=0.001 -f null -
23675 @section avectorscope
23677 Convert input audio to a video output, representing the audio vector
23680 The filter is used to measure the difference between channels of stereo
23681 audio stream. A monaural signal, consisting of identical left and right
23682 signal, results in straight vertical line. Any stereo separation is visible
23683 as a deviation from this line, creating a Lissajous figure.
23684 If the straight (or deviation from it) but horizontal line appears this
23685 indicates that the left and right channels are out of phase.
23687 The filter accepts the following options:
23691 Set the vectorscope mode.
23693 Available values are:
23696 Lissajous rotated by 45 degrees.
23699 Same as above but not rotated.
23702 Shape resembling half of circle.
23705 Default value is @samp{lissajous}.
23708 Set the video size for the output. For the syntax of this option, check the
23709 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23710 Default value is @code{400x400}.
23713 Set the output frame rate. Default value is @code{25}.
23719 Specify the red, green, blue and alpha contrast. Default values are @code{40},
23720 @code{160}, @code{80} and @code{255}.
23721 Allowed range is @code{[0, 255]}.
23727 Specify the red, green, blue and alpha fade. Default values are @code{15},
23728 @code{10}, @code{5} and @code{5}.
23729 Allowed range is @code{[0, 255]}.
23732 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}.
23733 Values lower than @var{1} will auto adjust zoom factor to maximal possible value.
23736 Set the vectorscope drawing mode.
23738 Available values are:
23741 Draw dot for each sample.
23744 Draw line between previous and current sample.
23747 Default value is @samp{dot}.
23750 Specify amplitude scale of audio samples.
23752 Available values are:
23768 Swap left channel axis with right channel axis.
23778 Mirror only x axis.
23781 Mirror only y axis.
23789 @subsection Examples
23793 Complete example using @command{ffplay}:
23795 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
23796 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
23800 @section bench, abench
23802 Benchmark part of a filtergraph.
23804 The filter accepts the following options:
23808 Start or stop a timer.
23810 Available values are:
23813 Get the current time, set it as frame metadata (using the key
23814 @code{lavfi.bench.start_time}), and forward the frame to the next filter.
23817 Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
23818 the input frame metadata to get the time difference. Time difference, average,
23819 maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
23820 @code{min}) are then printed. The timestamps are expressed in seconds.
23824 @subsection Examples
23828 Benchmark @ref{selectivecolor} filter:
23830 bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
23836 Concatenate audio and video streams, joining them together one after the
23839 The filter works on segments of synchronized video and audio streams. All
23840 segments must have the same number of streams of each type, and that will
23841 also be the number of streams at output.
23843 The filter accepts the following options:
23848 Set the number of segments. Default is 2.
23851 Set the number of output video streams, that is also the number of video
23852 streams in each segment. Default is 1.
23855 Set the number of output audio streams, that is also the number of audio
23856 streams in each segment. Default is 0.
23859 Activate unsafe mode: do not fail if segments have a different format.
23863 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
23864 @var{a} audio outputs.
23866 There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
23867 segment, in the same order as the outputs, then the inputs for the second
23870 Related streams do not always have exactly the same duration, for various
23871 reasons including codec frame size or sloppy authoring. For that reason,
23872 related synchronized streams (e.g. a video and its audio track) should be
23873 concatenated at once. The concat filter will use the duration of the longest
23874 stream in each segment (except the last one), and if necessary pad shorter
23875 audio streams with silence.
23877 For this filter to work correctly, all segments must start at timestamp 0.
23879 All corresponding streams must have the same parameters in all segments; the
23880 filtering system will automatically select a common pixel format for video
23881 streams, and a common sample format, sample rate and channel layout for
23882 audio streams, but other settings, such as resolution, must be converted
23883 explicitly by the user.
23885 Different frame rates are acceptable but will result in variable frame rate
23886 at output; be sure to configure the output file to handle it.
23888 @subsection Examples
23892 Concatenate an opening, an episode and an ending, all in bilingual version
23893 (video in stream 0, audio in streams 1 and 2):
23895 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
23896 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
23897 concat=n=3:v=1:a=2 [v] [a1] [a2]' \
23898 -map '[v]' -map '[a1]' -map '[a2]' output.mkv
23902 Concatenate two parts, handling audio and video separately, using the
23903 (a)movie sources, and adjusting the resolution:
23905 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
23906 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
23907 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
23909 Note that a desync will happen at the stitch if the audio and video streams
23910 do not have exactly the same duration in the first file.
23914 @subsection Commands
23916 This filter supports the following commands:
23919 Close the current segment and step to the next one
23925 EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness
23926 level. By default, it logs a message at a frequency of 10Hz with the
23927 Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
23928 Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
23930 The filter can only analyze streams which have a sampling rate of 48000 Hz and whose
23931 sample format is double-precision floating point. The input stream will be converted to
23932 this specification, if needed. Users may need to insert aformat and/or aresample filters
23933 after this filter to obtain the original parameters.
23935 The filter also has a video output (see the @var{video} option) with a real
23936 time graph to observe the loudness evolution. The graphic contains the logged
23937 message mentioned above, so it is not printed anymore when this option is set,
23938 unless the verbose logging is set. The main graphing area contains the
23939 short-term loudness (3 seconds of analysis), and the gauge on the right is for
23940 the momentary loudness (400 milliseconds), but can optionally be configured
23941 to instead display short-term loudness (see @var{gauge}).
23943 The green area marks a +/- 1LU target range around the target loudness
23944 (-23LUFS by default, unless modified through @var{target}).
23946 More information about the Loudness Recommendation EBU R128 on
23947 @url{http://tech.ebu.ch/loudness}.
23949 The filter accepts the following options:
23954 Activate the video output. The audio stream is passed unchanged whether this
23955 option is set or no. The video stream will be the first output stream if
23956 activated. Default is @code{0}.
23959 Set the video size. This option is for video only. For the syntax of this
23961 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23962 Default and minimum resolution is @code{640x480}.
23965 Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
23966 @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
23967 other integer value between this range is allowed.
23970 Set metadata injection. If set to @code{1}, the audio input will be segmented
23971 into 100ms output frames, each of them containing various loudness information
23972 in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
23974 Default is @code{0}.
23977 Force the frame logging level.
23979 Available values are:
23982 information logging level
23984 verbose logging level
23987 By default, the logging level is set to @var{info}. If the @option{video} or
23988 the @option{metadata} options are set, it switches to @var{verbose}.
23993 Available modes can be cumulated (the option is a @code{flag} type). Possible
23997 Disable any peak mode (default).
23999 Enable sample-peak mode.
24001 Simple peak mode looking for the higher sample value. It logs a message
24002 for sample-peak (identified by @code{SPK}).
24004 Enable true-peak mode.
24006 If enabled, the peak lookup is done on an over-sampled version of the input
24007 stream for better peak accuracy. It logs a message for true-peak.
24008 (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
24009 This mode requires a build with @code{libswresample}.
24013 Treat mono input files as "dual mono". If a mono file is intended for playback
24014 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
24015 If set to @code{true}, this option will compensate for this effect.
24016 Multi-channel input files are not affected by this option.
24019 Set a specific pan law to be used for the measurement of dual mono files.
24020 This parameter is optional, and has a default value of -3.01dB.
24023 Set a specific target level (in LUFS) used as relative zero in the visualization.
24024 This parameter is optional and has a default value of -23LUFS as specified
24025 by EBU R128. However, material published online may prefer a level of -16LUFS
24026 (e.g. for use with podcasts or video platforms).
24029 Set the value displayed by the gauge. Valid values are @code{momentary} and s
24030 @code{shortterm}. By default the momentary value will be used, but in certain
24031 scenarios it may be more useful to observe the short term value instead (e.g.
24035 Sets the display scale for the loudness. Valid parameters are @code{absolute}
24036 (in LUFS) or @code{relative} (LU) relative to the target. This only affects the
24037 video output, not the summary or continuous log output.
24040 @subsection Examples
24044 Real-time graph using @command{ffplay}, with a EBU scale meter +18:
24046 ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
24050 Run an analysis with @command{ffmpeg}:
24052 ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
24056 @section interleave, ainterleave
24058 Temporally interleave frames from several inputs.
24060 @code{interleave} works with video inputs, @code{ainterleave} with audio.
24062 These filters read frames from several inputs and send the oldest
24063 queued frame to the output.
24065 Input streams must have well defined, monotonically increasing frame
24068 In order to submit one frame to output, these filters need to enqueue
24069 at least one frame for each input, so they cannot work in case one
24070 input is not yet terminated and will not receive incoming frames.
24072 For example consider the case when one input is a @code{select} filter
24073 which always drops input frames. The @code{interleave} filter will keep
24074 reading from that input, but it will never be able to send new frames
24075 to output until the input sends an end-of-stream signal.
24077 Also, depending on inputs synchronization, the filters will drop
24078 frames in case one input receives more frames than the other ones, and
24079 the queue is already filled.
24081 These filters accept the following options:
24085 Set the number of different inputs, it is 2 by default.
24088 How to determine the end-of-stream.
24092 The duration of the longest input. (default)
24095 The duration of the shortest input.
24098 The duration of the first input.
24103 @subsection Examples
24107 Interleave frames belonging to different streams using @command{ffmpeg}:
24109 ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
24113 Add flickering blur effect:
24115 select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
24119 @section metadata, ametadata
24121 Manipulate frame metadata.
24123 This filter accepts the following options:
24127 Set mode of operation of the filter.
24129 Can be one of the following:
24133 If both @code{value} and @code{key} is set, select frames
24134 which have such metadata. If only @code{key} is set, select
24135 every frame that has such key in metadata.
24138 Add new metadata @code{key} and @code{value}. If key is already available
24142 Modify value of already present key.
24145 If @code{value} is set, delete only keys that have such value.
24146 Otherwise, delete key. If @code{key} is not set, delete all metadata values in
24150 Print key and its value if metadata was found. If @code{key} is not set print all
24151 metadata values available in frame.
24155 Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}.
24158 Set metadata value which will be used. This option is mandatory for
24159 @code{modify} and @code{add} mode.
24162 Which function to use when comparing metadata value and @code{value}.
24164 Can be one of following:
24168 Values are interpreted as strings, returns true if metadata value is same as @code{value}.
24171 Values are interpreted as strings, returns true if metadata value starts with
24172 the @code{value} option string.
24175 Values are interpreted as floats, returns true if metadata value is less than @code{value}.
24178 Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
24181 Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
24184 Values are interpreted as floats, returns true if expression from option @code{expr}
24188 Values are interpreted as strings, returns true if metadata value ends with
24189 the @code{value} option string.
24193 Set expression which is used when @code{function} is set to @code{expr}.
24194 The expression is evaluated through the eval API and can contain the following
24199 Float representation of @code{value} from metadata key.
24202 Float representation of @code{value} as supplied by user in @code{value} option.
24206 If specified in @code{print} mode, output is written to the named file. Instead of
24207 plain filename any writable url can be specified. Filename ``-'' is a shorthand
24208 for standard output. If @code{file} option is not set, output is written to the log
24209 with AV_LOG_INFO loglevel.
24212 Reduces buffering in print mode when output is written to a URL set using @var{file}.
24216 @subsection Examples
24220 Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values
24223 signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
24226 Print silencedetect output to file @file{metadata.txt}.
24228 silencedetect,ametadata=mode=print:file=metadata.txt
24231 Direct all metadata to a pipe with file descriptor 4.
24233 metadata=mode=print:file='pipe\:4'
24237 @section perms, aperms
24239 Set read/write permissions for the output frames.
24241 These filters are mainly aimed at developers to test direct path in the
24242 following filter in the filtergraph.
24244 The filters accept the following options:
24248 Select the permissions mode.
24250 It accepts the following values:
24253 Do nothing. This is the default.
24255 Set all the output frames read-only.
24257 Set all the output frames directly writable.
24259 Make the frame read-only if writable, and writable if read-only.
24261 Set each output frame read-only or writable randomly.
24265 Set the seed for the @var{random} mode, must be an integer included between
24266 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
24267 @code{-1}, the filter will try to use a good random seed on a best effort
24271 Note: in case of auto-inserted filter between the permission filter and the
24272 following one, the permission might not be received as expected in that
24273 following filter. Inserting a @ref{format} or @ref{aformat} filter before the
24274 perms/aperms filter can avoid this problem.
24276 @section realtime, arealtime
24278 Slow down filtering to match real time approximately.
24280 These filters will pause the filtering for a variable amount of time to
24281 match the output rate with the input timestamps.
24282 They are similar to the @option{re} option to @code{ffmpeg}.
24284 They accept the following options:
24288 Time limit for the pauses. Any pause longer than that will be considered
24289 a timestamp discontinuity and reset the timer. Default is 2 seconds.
24291 Speed factor for processing. The value must be a float larger than zero.
24292 Values larger than 1.0 will result in faster than realtime processing,
24293 smaller will slow processing down. The @var{limit} is automatically adapted
24294 accordingly. Default is 1.0.
24296 A processing speed faster than what is possible without these filters cannot
24301 @section select, aselect
24303 Select frames to pass in output.
24305 This filter accepts the following options:
24310 Set expression, which is evaluated for each input frame.
24312 If the expression is evaluated to zero, the frame is discarded.
24314 If the evaluation result is negative or NaN, the frame is sent to the
24315 first output; otherwise it is sent to the output with index
24316 @code{ceil(val)-1}, assuming that the input index starts from 0.
24318 For example a value of @code{1.2} corresponds to the output with index
24319 @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
24322 Set the number of outputs. The output to which to send the selected
24323 frame is based on the result of the evaluation. Default value is 1.
24326 The expression can contain the following constants:
24330 The (sequential) number of the filtered frame, starting from 0.
24333 The (sequential) number of the selected frame, starting from 0.
24335 @item prev_selected_n
24336 The sequential number of the last selected frame. It's NAN if undefined.
24339 The timebase of the input timestamps.
24342 The PTS (Presentation TimeStamp) of the filtered video frame,
24343 expressed in @var{TB} units. It's NAN if undefined.
24346 The PTS of the filtered video frame,
24347 expressed in seconds. It's NAN if undefined.
24350 The PTS of the previously filtered video frame. It's NAN if undefined.
24352 @item prev_selected_pts
24353 The PTS of the last previously filtered video frame. It's NAN if undefined.
24355 @item prev_selected_t
24356 The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined.
24359 The PTS of the first video frame in the video. It's NAN if undefined.
24362 The time of the first video frame in the video. It's NAN if undefined.
24364 @item pict_type @emph{(video only)}
24365 The type of the filtered frame. It can assume one of the following
24377 @item interlace_type @emph{(video only)}
24378 The frame interlace type. It can assume one of the following values:
24381 The frame is progressive (not interlaced).
24383 The frame is top-field-first.
24385 The frame is bottom-field-first.
24388 @item consumed_sample_n @emph{(audio only)}
24389 the number of selected samples before the current frame
24391 @item samples_n @emph{(audio only)}
24392 the number of samples in the current frame
24394 @item sample_rate @emph{(audio only)}
24395 the input sample rate
24398 This is 1 if the filtered frame is a key-frame, 0 otherwise.
24401 the position in the file of the filtered frame, -1 if the information
24402 is not available (e.g. for synthetic video)
24404 @item scene @emph{(video only)}
24405 value between 0 and 1 to indicate a new scene; a low value reflects a low
24406 probability for the current frame to introduce a new scene, while a higher
24407 value means the current frame is more likely to be one (see the example below)
24409 @item concatdec_select
24410 The concat demuxer can select only part of a concat input file by setting an
24411 inpoint and an outpoint, but the output packets may not be entirely contained
24412 in the selected interval. By using this variable, it is possible to skip frames
24413 generated by the concat demuxer which are not exactly contained in the selected
24416 This works by comparing the frame pts against the @var{lavf.concat.start_time}
24417 and the @var{lavf.concat.duration} packet metadata values which are also
24418 present in the decoded frames.
24420 The @var{concatdec_select} variable is -1 if the frame pts is at least
24421 start_time and either the duration metadata is missing or the frame pts is less
24422 than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
24425 That basically means that an input frame is selected if its pts is within the
24426 interval set by the concat demuxer.
24430 The default value of the select expression is "1".
24432 @subsection Examples
24436 Select all frames in input:
24441 The example above is the same as:
24453 Select only I-frames:
24455 select='eq(pict_type\,I)'
24459 Select one frame every 100:
24461 select='not(mod(n\,100))'
24465 Select only frames contained in the 10-20 time interval:
24467 select=between(t\,10\,20)
24471 Select only I-frames contained in the 10-20 time interval:
24473 select=between(t\,10\,20)*eq(pict_type\,I)
24477 Select frames with a minimum distance of 10 seconds:
24479 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
24483 Use aselect to select only audio frames with samples number > 100:
24485 aselect='gt(samples_n\,100)'
24489 Create a mosaic of the first scenes:
24491 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
24494 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
24498 Send even and odd frames to separate outputs, and compose them:
24500 select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
24504 Select useful frames from an ffconcat file which is using inpoints and
24505 outpoints but where the source files are not intra frame only.
24507 ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
24511 @section sendcmd, asendcmd
24513 Send commands to filters in the filtergraph.
24515 These filters read commands to be sent to other filters in the
24518 @code{sendcmd} must be inserted between two video filters,
24519 @code{asendcmd} must be inserted between two audio filters, but apart
24520 from that they act the same way.
24522 The specification of commands can be provided in the filter arguments
24523 with the @var{commands} option, or in a file specified by the
24524 @var{filename} option.
24526 These filters accept the following options:
24529 Set the commands to be read and sent to the other filters.
24531 Set the filename of the commands to be read and sent to the other
24535 @subsection Commands syntax
24537 A commands description consists of a sequence of interval
24538 specifications, comprising a list of commands to be executed when a
24539 particular event related to that interval occurs. The occurring event
24540 is typically the current frame time entering or leaving a given time
24543 An interval is specified by the following syntax:
24545 @var{START}[-@var{END}] @var{COMMANDS};
24548 The time interval is specified by the @var{START} and @var{END} times.
24549 @var{END} is optional and defaults to the maximum time.
24551 The current frame time is considered within the specified interval if
24552 it is included in the interval [@var{START}, @var{END}), that is when
24553 the time is greater or equal to @var{START} and is lesser than
24556 @var{COMMANDS} consists of a sequence of one or more command
24557 specifications, separated by ",", relating to that interval. The
24558 syntax of a command specification is given by:
24560 [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
24563 @var{FLAGS} is optional and specifies the type of events relating to
24564 the time interval which enable sending the specified command, and must
24565 be a non-null sequence of identifier flags separated by "+" or "|" and
24566 enclosed between "[" and "]".
24568 The following flags are recognized:
24571 The command is sent when the current frame timestamp enters the
24572 specified interval. In other words, the command is sent when the
24573 previous frame timestamp was not in the given interval, and the
24577 The command is sent when the current frame timestamp leaves the
24578 specified interval. In other words, the command is sent when the
24579 previous frame timestamp was in the given interval, and the
24583 The command @var{ARG} is interpreted as expression and result of
24584 expression is passed as @var{ARG}.
24586 The expression is evaluated through the eval API and can contain the following
24591 Original position in the file of the frame, or undefined if undefined
24592 for the current frame.
24595 The presentation timestamp in input.
24598 The count of the input frame for video or audio, starting from 0.
24601 The time in seconds of the current frame.
24604 The start time in seconds of the current command interval.
24607 The end time in seconds of the current command interval.
24610 The interpolated time of the current command interval, TI = (T - TS) / (TE - TS).
24615 If @var{FLAGS} is not specified, a default value of @code{[enter]} is
24618 @var{TARGET} specifies the target of the command, usually the name of
24619 the filter class or a specific filter instance name.
24621 @var{COMMAND} specifies the name of the command for the target filter.
24623 @var{ARG} is optional and specifies the optional list of argument for
24624 the given @var{COMMAND}.
24626 Between one interval specification and another, whitespaces, or
24627 sequences of characters starting with @code{#} until the end of line,
24628 are ignored and can be used to annotate comments.
24630 A simplified BNF description of the commands specification syntax
24633 @var{COMMAND_FLAG} ::= "enter" | "leave"
24634 @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
24635 @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
24636 @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
24637 @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
24638 @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
24641 @subsection Examples
24645 Specify audio tempo change at second 4:
24647 asendcmd=c='4.0 atempo tempo 1.5',atempo
24651 Target a specific filter instance:
24653 asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my
24657 Specify a list of drawtext and hue commands in a file.
24659 # show text in the interval 5-10
24660 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
24661 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
24663 # desaturate the image in the interval 15-20
24664 15.0-20.0 [enter] hue s 0,
24665 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
24667 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
24669 # apply an exponential saturation fade-out effect, starting from time 25
24670 25 [enter] hue s exp(25-t)
24673 A filtergraph allowing to read and process the above command list
24674 stored in a file @file{test.cmd}, can be specified with:
24676 sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
24681 @section setpts, asetpts
24683 Change the PTS (presentation timestamp) of the input frames.
24685 @code{setpts} works on video frames, @code{asetpts} on audio frames.
24687 This filter accepts the following options:
24692 The expression which is evaluated for each frame to construct its timestamp.
24696 The expression is evaluated through the eval API and can contain the following
24700 @item FRAME_RATE, FR
24701 frame rate, only defined for constant frame-rate video
24704 The presentation timestamp in input
24707 The count of the input frame for video or the number of consumed samples,
24708 not including the current frame for audio, starting from 0.
24710 @item NB_CONSUMED_SAMPLES
24711 The number of consumed samples, not including the current frame (only
24714 @item NB_SAMPLES, S
24715 The number of samples in the current frame (only audio)
24717 @item SAMPLE_RATE, SR
24718 The audio sample rate.
24721 The PTS of the first frame.
24724 the time in seconds of the first frame
24727 State whether the current frame is interlaced.
24730 the time in seconds of the current frame
24733 original position in the file of the frame, or undefined if undefined
24734 for the current frame
24737 The previous input PTS.
24740 previous input time in seconds
24743 The previous output PTS.
24746 previous output time in seconds
24749 The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
24753 The wallclock (RTC) time at the start of the movie in microseconds.
24756 The timebase of the input timestamps.
24760 @subsection Examples
24764 Start counting PTS from zero
24766 setpts=PTS-STARTPTS
24770 Apply fast motion effect:
24776 Apply slow motion effect:
24782 Set fixed rate of 25 frames per second:
24788 Set fixed rate 25 fps with some jitter:
24790 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
24794 Apply an offset of 10 seconds to the input PTS:
24800 Generate timestamps from a "live source" and rebase onto the current timebase:
24802 setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
24806 Generate timestamps by counting samples:
24815 Force color range for the output video frame.
24817 The @code{setrange} filter marks the color range property for the
24818 output frames. It does not change the input frame, but only sets the
24819 corresponding property, which affects how the frame is treated by
24822 The filter accepts the following options:
24827 Available values are:
24831 Keep the same color range property.
24833 @item unspecified, unknown
24834 Set the color range as unspecified.
24836 @item limited, tv, mpeg
24837 Set the color range as limited.
24839 @item full, pc, jpeg
24840 Set the color range as full.
24844 @section settb, asettb
24846 Set the timebase to use for the output frames timestamps.
24847 It is mainly useful for testing timebase configuration.
24849 It accepts the following parameters:
24854 The expression which is evaluated into the output timebase.
24858 The value for @option{tb} is an arithmetic expression representing a
24859 rational. The expression can contain the constants "AVTB" (the default
24860 timebase), "intb" (the input timebase) and "sr" (the sample rate,
24861 audio only). Default value is "intb".
24863 @subsection Examples
24867 Set the timebase to 1/25:
24873 Set the timebase to 1/10:
24879 Set the timebase to 1001/1000:
24885 Set the timebase to 2*intb:
24891 Set the default timebase value:
24898 Convert input audio to a video output representing frequency spectrum
24899 logarithmically using Brown-Puckette constant Q transform algorithm with
24900 direct frequency domain coefficient calculation (but the transform itself
24901 is not really constant Q, instead the Q factor is actually variable/clamped),
24902 with musical tone scale, from E0 to D#10.
24904 The filter accepts the following options:
24908 Specify the video size for the output. It must be even. For the syntax of this option,
24909 check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24910 Default value is @code{1920x1080}.
24913 Set the output frame rate. Default value is @code{25}.
24916 Set the bargraph height. It must be even. Default value is @code{-1} which
24917 computes the bargraph height automatically.
24920 Set the axis height. It must be even. Default value is @code{-1} which computes
24921 the axis height automatically.
24924 Set the sonogram height. It must be even. Default value is @code{-1} which
24925 computes the sonogram height automatically.
24928 Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
24929 instead. Default value is @code{1}.
24931 @item sono_v, volume
24932 Specify the sonogram volume expression. It can contain variables:
24935 the @var{bar_v} evaluated expression
24936 @item frequency, freq, f
24937 the frequency where it is evaluated
24938 @item timeclamp, tc
24939 the value of @var{timeclamp} option
24943 @item a_weighting(f)
24944 A-weighting of equal loudness
24945 @item b_weighting(f)
24946 B-weighting of equal loudness
24947 @item c_weighting(f)
24948 C-weighting of equal loudness.
24950 Default value is @code{16}.
24952 @item bar_v, volume2
24953 Specify the bargraph volume expression. It can contain variables:
24956 the @var{sono_v} evaluated expression
24957 @item frequency, freq, f
24958 the frequency where it is evaluated
24959 @item timeclamp, tc
24960 the value of @var{timeclamp} option
24964 @item a_weighting(f)
24965 A-weighting of equal loudness
24966 @item b_weighting(f)
24967 B-weighting of equal loudness
24968 @item c_weighting(f)
24969 C-weighting of equal loudness.
24971 Default value is @code{sono_v}.
24973 @item sono_g, gamma
24974 Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
24975 higher gamma makes the spectrum having more range. Default value is @code{3}.
24976 Acceptable range is @code{[1, 7]}.
24978 @item bar_g, gamma2
24979 Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
24983 Specify the bargraph transparency level. Lower value makes the bargraph sharper.
24984 Default value is @code{1}. Acceptable range is @code{[0, 1]}.
24986 @item timeclamp, tc
24987 Specify the transform timeclamp. At low frequency, there is trade-off between
24988 accuracy in time domain and frequency domain. If timeclamp is lower,
24989 event in time domain is represented more accurately (such as fast bass drum),
24990 otherwise event in frequency domain is represented more accurately
24991 (such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}.
24994 Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it
24995 limits future samples by applying asymmetric windowing in time domain, useful
24996 when low latency is required. Accepted range is @code{[0, 1]}.
24999 Specify the transform base frequency. Default value is @code{20.01523126408007475},
25000 which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
25003 Specify the transform end frequency. Default value is @code{20495.59681441799654},
25004 which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
25007 This option is deprecated and ignored.
25010 Specify the transform length in time domain. Use this option to control accuracy
25011 trade-off between time domain and frequency domain at every frequency sample.
25012 It can contain variables:
25014 @item frequency, freq, f
25015 the frequency where it is evaluated
25016 @item timeclamp, tc
25017 the value of @var{timeclamp} option.
25019 Default value is @code{384*tc/(384+tc*f)}.
25022 Specify the transform count for every video frame. Default value is @code{6}.
25023 Acceptable range is @code{[1, 30]}.
25026 Specify the transform count for every single pixel. Default value is @code{0},
25027 which makes it computed automatically. Acceptable range is @code{[0, 10]}.
25030 Specify font file for use with freetype to draw the axis. If not specified,
25031 use embedded font. Note that drawing with font file or embedded font is not
25032 implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
25036 Specify fontconfig pattern. This has lower priority than @var{fontfile}. The
25037 @code{:} in the pattern may be replaced by @code{|} to avoid unnecessary
25041 Specify font color expression. This is arithmetic expression that should return
25042 integer value 0xRRGGBB. It can contain variables:
25044 @item frequency, freq, f
25045 the frequency where it is evaluated
25046 @item timeclamp, tc
25047 the value of @var{timeclamp} option
25052 midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
25053 @item r(x), g(x), b(x)
25054 red, green, and blue value of intensity x.
25056 Default value is @code{st(0, (midi(f)-59.5)/12);
25057 st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
25058 r(1-ld(1)) + b(ld(1))}.
25061 Specify image file to draw the axis. This option override @var{fontfile} and
25062 @var{fontcolor} option.
25065 Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
25066 the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
25067 Default value is @code{1}.
25070 Set colorspace. The accepted values are:
25073 Unspecified (default)
25082 BT.470BG or BT.601-6 625
25085 SMPTE-170M or BT.601-6 525
25091 BT.2020 with non-constant luminance
25096 Set spectrogram color scheme. This is list of floating point values with format
25097 @code{left_r|left_g|left_b|right_r|right_g|right_b}.
25098 The default is @code{1|0.5|0|0|0.5|1}.
25102 @subsection Examples
25106 Playing audio while showing the spectrum:
25108 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
25112 Same as above, but with frame rate 30 fps:
25114 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
25118 Playing at 1280x720:
25120 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
25124 Disable sonogram display:
25130 A1 and its harmonics: A1, A2, (near)E3, A3:
25132 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),
25133 asplit[a][out1]; [a] showcqt [out0]'
25137 Same as above, but with more accuracy in frequency domain:
25139 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),
25140 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
25146 bar_v=10:sono_v=bar_v*a_weighting(f)
25150 Custom gamma, now spectrum is linear to the amplitude.
25156 Custom tlength equation:
25158 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)))'
25162 Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
25164 fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
25168 Custom font using fontconfig:
25170 font='Courier New,Monospace,mono|bold'
25174 Custom frequency range with custom axis using image file:
25176 axisfile=myaxis.png:basefreq=40:endfreq=10000
25182 Convert input audio to video output representing the audio power spectrum.
25183 Audio amplitude is on Y-axis while frequency is on X-axis.
25185 The filter accepts the following options:
25189 Specify size of video. For the syntax of this option, check the
25190 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25191 Default is @code{1024x512}.
25195 This set how each frequency bin will be represented.
25197 It accepts the following values:
25203 Default is @code{bar}.
25206 Set amplitude scale.
25208 It accepts the following values:
25222 Default is @code{log}.
25225 Set frequency scale.
25227 It accepts the following values:
25236 Reverse logarithmic scale.
25238 Default is @code{lin}.
25241 Set window size. Allowed range is from 16 to 65536.
25243 Default is @code{2048}
25246 Set windowing function.
25248 It accepts the following values:
25271 Default is @code{hanning}.
25274 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
25275 which means optimal overlap for selected window function will be picked.
25278 Set time averaging. Setting this to 0 will display current maximal peaks.
25279 Default is @code{1}, which means time averaging is disabled.
25282 Specify list of colors separated by space or by '|' which will be used to
25283 draw channel frequencies. Unrecognized or missing colors will be replaced
25287 Set channel display mode.
25289 It accepts the following values:
25294 Default is @code{combined}.
25297 Set minimum amplitude used in @code{log} amplitude scaler.
25300 Set data display mode.
25302 It accepts the following values:
25308 Default is @code{magnitude}.
25311 @section showspatial
25313 Convert stereo input audio to a video output, representing the spatial relationship
25314 between two channels.
25316 The filter accepts the following options:
25320 Specify the video size for the output. For the syntax of this option, check the
25321 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25322 Default value is @code{512x512}.
25325 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
25328 Set window function.
25330 It accepts the following values:
25355 Default value is @code{hann}.
25358 Set ratio of overlap window. Default value is @code{0.5}.
25359 When value is @code{1} overlap is set to recommended size for specific
25360 window function currently used.
25363 @anchor{showspectrum}
25364 @section showspectrum
25366 Convert input audio to a video output, representing the audio frequency
25369 The filter accepts the following options:
25373 Specify the video size for the output. For the syntax of this option, check the
25374 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25375 Default value is @code{640x512}.
25378 Specify how the spectrum should slide along the window.
25380 It accepts the following values:
25383 the samples start again on the left when they reach the right
25385 the samples scroll from right to left
25387 frames are only produced when the samples reach the right
25389 the samples scroll from left to right
25392 Default value is @code{replace}.
25395 Specify display mode.
25397 It accepts the following values:
25400 all channels are displayed in the same row
25402 all channels are displayed in separate rows
25405 Default value is @samp{combined}.
25408 Specify display color mode.
25410 It accepts the following values:
25413 each channel is displayed in a separate color
25415 each channel is displayed using the same color scheme
25417 each channel is displayed using the rainbow color scheme
25419 each channel is displayed using the moreland color scheme
25421 each channel is displayed using the nebulae color scheme
25423 each channel is displayed using the fire color scheme
25425 each channel is displayed using the fiery color scheme
25427 each channel is displayed using the fruit color scheme
25429 each channel is displayed using the cool color scheme
25431 each channel is displayed using the magma color scheme
25433 each channel is displayed using the green color scheme
25435 each channel is displayed using the viridis color scheme
25437 each channel is displayed using the plasma color scheme
25439 each channel is displayed using the cividis color scheme
25441 each channel is displayed using the terrain color scheme
25444 Default value is @samp{channel}.
25447 Specify scale used for calculating intensity color values.
25449 It accepts the following values:
25454 square root, default
25465 Default value is @samp{sqrt}.
25468 Specify frequency scale.
25470 It accepts the following values:
25478 Default value is @samp{lin}.
25481 Set saturation modifier for displayed colors. Negative values provide
25482 alternative color scheme. @code{0} is no saturation at all.
25483 Saturation must be in [-10.0, 10.0] range.
25484 Default value is @code{1}.
25487 Set window function.
25489 It accepts the following values:
25514 Default value is @code{hann}.
25517 Set orientation of time vs frequency axis. Can be @code{vertical} or
25518 @code{horizontal}. Default is @code{vertical}.
25521 Set ratio of overlap window. Default value is @code{0}.
25522 When value is @code{1} overlap is set to recommended size for specific
25523 window function currently used.
25526 Set scale gain for calculating intensity color values.
25527 Default value is @code{1}.
25530 Set which data to display. Can be @code{magnitude}, default or @code{phase}.
25533 Set color rotation, must be in [-1.0, 1.0] range.
25534 Default value is @code{0}.
25537 Set start frequency from which to display spectrogram. Default is @code{0}.
25540 Set stop frequency to which to display spectrogram. Default is @code{0}.
25543 Set upper frame rate limit. Default is @code{auto}, unlimited.
25546 Draw time and frequency axes and legends. Default is disabled.
25549 The usage is very similar to the showwaves filter; see the examples in that
25552 @subsection Examples
25556 Large window with logarithmic color scaling:
25558 showspectrum=s=1280x480:scale=log
25562 Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
25564 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
25565 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
25569 @section showspectrumpic
25571 Convert input audio to a single video frame, representing the audio frequency
25574 The filter accepts the following options:
25578 Specify the video size for the output. For the syntax of this option, check the
25579 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25580 Default value is @code{4096x2048}.
25583 Specify display mode.
25585 It accepts the following values:
25588 all channels are displayed in the same row
25590 all channels are displayed in separate rows
25592 Default value is @samp{combined}.
25595 Specify display color mode.
25597 It accepts the following values:
25600 each channel is displayed in a separate color
25602 each channel is displayed using the same color scheme
25604 each channel is displayed using the rainbow color scheme
25606 each channel is displayed using the moreland color scheme
25608 each channel is displayed using the nebulae color scheme
25610 each channel is displayed using the fire color scheme
25612 each channel is displayed using the fiery color scheme
25614 each channel is displayed using the fruit color scheme
25616 each channel is displayed using the cool color scheme
25618 each channel is displayed using the magma color scheme
25620 each channel is displayed using the green color scheme
25622 each channel is displayed using the viridis color scheme
25624 each channel is displayed using the plasma color scheme
25626 each channel is displayed using the cividis color scheme
25628 each channel is displayed using the terrain color scheme
25630 Default value is @samp{intensity}.
25633 Specify scale used for calculating intensity color values.
25635 It accepts the following values:
25640 square root, default
25650 Default value is @samp{log}.
25653 Specify frequency scale.
25655 It accepts the following values:
25663 Default value is @samp{lin}.
25666 Set saturation modifier for displayed colors. Negative values provide
25667 alternative color scheme. @code{0} is no saturation at all.
25668 Saturation must be in [-10.0, 10.0] range.
25669 Default value is @code{1}.
25672 Set window function.
25674 It accepts the following values:
25698 Default value is @code{hann}.
25701 Set orientation of time vs frequency axis. Can be @code{vertical} or
25702 @code{horizontal}. Default is @code{vertical}.
25705 Set scale gain for calculating intensity color values.
25706 Default value is @code{1}.
25709 Draw time and frequency axes and legends. Default is enabled.
25712 Set color rotation, must be in [-1.0, 1.0] range.
25713 Default value is @code{0}.
25716 Set start frequency from which to display spectrogram. Default is @code{0}.
25719 Set stop frequency to which to display spectrogram. Default is @code{0}.
25722 @subsection Examples
25726 Extract an audio spectrogram of a whole audio track
25727 in a 1024x1024 picture using @command{ffmpeg}:
25729 ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
25733 @section showvolume
25735 Convert input audio volume to a video output.
25737 The filter accepts the following options:
25744 Set border width, allowed range is [0, 5]. Default is 1.
25747 Set channel width, allowed range is [80, 8192]. Default is 400.
25750 Set channel height, allowed range is [1, 900]. Default is 20.
25753 Set fade, allowed range is [0, 1]. Default is 0.95.
25756 Set volume color expression.
25758 The expression can use the following variables:
25762 Current max volume of channel in dB.
25768 Current channel number, starting from 0.
25772 If set, displays channel names. Default is enabled.
25775 If set, displays volume values. Default is enabled.
25778 Set orientation, can be horizontal: @code{h} or vertical: @code{v},
25779 default is @code{h}.
25782 Set step size, allowed range is [0, 5]. Default is 0, which means
25786 Set background opacity, allowed range is [0, 1]. Default is 0.
25789 Set metering mode, can be peak: @code{p} or rms: @code{r},
25790 default is @code{p}.
25793 Set display scale, can be linear: @code{lin} or log: @code{log},
25794 default is @code{lin}.
25798 If set to > 0., display a line for the max level
25799 in the previous seconds.
25800 default is disabled: @code{0.}
25803 The color of the max line. Use when @code{dm} option is set to > 0.
25804 default is: @code{orange}
25809 Convert input audio to a video output, representing the samples waves.
25811 The filter accepts the following options:
25815 Specify the video size for the output. For the syntax of this option, check the
25816 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25817 Default value is @code{600x240}.
25822 Available values are:
25825 Draw a point for each sample.
25828 Draw a vertical line for each sample.
25831 Draw a point for each sample and a line between them.
25834 Draw a centered vertical line for each sample.
25837 Default value is @code{point}.
25840 Set the number of samples which are printed on the same column. A
25841 larger value will decrease the frame rate. Must be a positive
25842 integer. This option can be set only if the value for @var{rate}
25843 is not explicitly specified.
25846 Set the (approximate) output frame rate. This is done by setting the
25847 option @var{n}. Default value is "25".
25849 @item split_channels
25850 Set if channels should be drawn separately or overlap. Default value is 0.
25853 Set colors separated by '|' which are going to be used for drawing of each channel.
25856 Set amplitude scale.
25858 Available values are:
25876 Set the draw mode. This is mostly useful to set for high @var{n}.
25878 Available values are:
25881 Scale pixel values for each drawn sample.
25884 Draw every sample directly.
25887 Default value is @code{scale}.
25890 @subsection Examples
25894 Output the input file audio and the corresponding video representation
25897 amovie=a.mp3,asplit[out0],showwaves[out1]
25901 Create a synthetic signal and show it with showwaves, forcing a
25902 frame rate of 30 frames per second:
25904 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
25908 @section showwavespic
25910 Convert input audio to a single video frame, representing the samples waves.
25912 The filter accepts the following options:
25916 Specify the video size for the output. For the syntax of this option, check the
25917 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25918 Default value is @code{600x240}.
25920 @item split_channels
25921 Set if channels should be drawn separately or overlap. Default value is 0.
25924 Set colors separated by '|' which are going to be used for drawing of each channel.
25927 Set amplitude scale.
25929 Available values are:
25949 Available values are:
25952 Scale pixel values for each drawn sample.
25955 Draw every sample directly.
25958 Default value is @code{scale}.
25961 Set the filter mode.
25963 Available values are:
25966 Use average samples values for each drawn sample.
25969 Use peak samples values for each drawn sample.
25972 Default value is @code{average}.
25975 @subsection Examples
25979 Extract a channel split representation of the wave form of a whole audio track
25980 in a 1024x800 picture using @command{ffmpeg}:
25982 ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
25986 @section sidedata, asidedata
25988 Delete frame side data, or select frames based on it.
25990 This filter accepts the following options:
25994 Set mode of operation of the filter.
25996 Can be one of the following:
26000 Select every frame with side data of @code{type}.
26003 Delete side data of @code{type}. If @code{type} is not set, delete all side
26009 Set side data type used with all modes. Must be set for @code{select} mode. For
26010 the list of frame side data types, refer to the @code{AVFrameSideDataType} enum
26011 in @file{libavutil/frame.h}. For example, to choose
26012 @code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}.
26016 @section spectrumsynth
26018 Synthesize audio from 2 input video spectrums, first input stream represents
26019 magnitude across time and second represents phase across time.
26020 The filter will transform from frequency domain as displayed in videos back
26021 to time domain as presented in audio output.
26023 This filter is primarily created for reversing processed @ref{showspectrum}
26024 filter outputs, but can synthesize sound from other spectrograms too.
26025 But in such case results are going to be poor if the phase data is not
26026 available, because in such cases phase data need to be recreated, usually
26027 it's just recreated from random noise.
26028 For best results use gray only output (@code{channel} color mode in
26029 @ref{showspectrum} filter) and @code{log} scale for magnitude video and
26030 @code{lin} scale for phase video. To produce phase, for 2nd video, use
26031 @code{data} option. Inputs videos should generally use @code{fullframe}
26032 slide mode as that saves resources needed for decoding video.
26034 The filter accepts the following options:
26038 Specify sample rate of output audio, the sample rate of audio from which
26039 spectrum was generated may differ.
26042 Set number of channels represented in input video spectrums.
26045 Set scale which was used when generating magnitude input spectrum.
26046 Can be @code{lin} or @code{log}. Default is @code{log}.
26049 Set slide which was used when generating inputs spectrums.
26050 Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
26051 Default is @code{fullframe}.
26054 Set window function used for resynthesis.
26057 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
26058 which means optimal overlap for selected window function will be picked.
26061 Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
26062 Default is @code{vertical}.
26065 @subsection Examples
26069 First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
26070 then resynthesize videos back to audio with spectrumsynth:
26072 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
26073 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
26074 ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
26078 @section split, asplit
26080 Split input into several identical outputs.
26082 @code{asplit} works with audio input, @code{split} with video.
26084 The filter accepts a single parameter which specifies the number of outputs. If
26085 unspecified, it defaults to 2.
26087 @subsection Examples
26091 Create two separate outputs from the same input:
26093 [in] split [out0][out1]
26097 To create 3 or more outputs, you need to specify the number of
26100 [in] asplit=3 [out0][out1][out2]
26104 Create two separate outputs from the same input, one cropped and
26107 [in] split [splitout1][splitout2];
26108 [splitout1] crop=100:100:0:0 [cropout];
26109 [splitout2] pad=200:200:100:100 [padout];
26113 Create 5 copies of the input audio with @command{ffmpeg}:
26115 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
26121 Receive commands sent through a libzmq client, and forward them to
26122 filters in the filtergraph.
26124 @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
26125 must be inserted between two video filters, @code{azmq} between two
26126 audio filters. Both are capable to send messages to any filter type.
26128 To enable these filters you need to install the libzmq library and
26129 headers and configure FFmpeg with @code{--enable-libzmq}.
26131 For more information about libzmq see:
26132 @url{http://www.zeromq.org/}
26134 The @code{zmq} and @code{azmq} filters work as a libzmq server, which
26135 receives messages sent through a network interface defined by the
26136 @option{bind_address} (or the abbreviation "@option{b}") option.
26137 Default value of this option is @file{tcp://localhost:5555}. You may
26138 want to alter this value to your needs, but do not forget to escape any
26139 ':' signs (see @ref{filtergraph escaping}).
26141 The received message must be in the form:
26143 @var{TARGET} @var{COMMAND} [@var{ARG}]
26146 @var{TARGET} specifies the target of the command, usually the name of
26147 the filter class or a specific filter instance name. The default
26148 filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>},
26149 but you can override this by using the @samp{filter_name@@id} syntax
26150 (see @ref{Filtergraph syntax}).
26152 @var{COMMAND} specifies the name of the command for the target filter.
26154 @var{ARG} is optional and specifies the optional argument list for the
26155 given @var{COMMAND}.
26157 Upon reception, the message is processed and the corresponding command
26158 is injected into the filtergraph. Depending on the result, the filter
26159 will send a reply to the client, adopting the format:
26161 @var{ERROR_CODE} @var{ERROR_REASON}
26165 @var{MESSAGE} is optional.
26167 @subsection Examples
26169 Look at @file{tools/zmqsend} for an example of a zmq client which can
26170 be used to send commands processed by these filters.
26172 Consider the following filtergraph generated by @command{ffplay}.
26173 In this example the last overlay filter has an instance name. All other
26174 filters will have default instance names.
26177 ffplay -dumpgraph 1 -f lavfi "
26178 color=s=100x100:c=red [l];
26179 color=s=100x100:c=blue [r];
26180 nullsrc=s=200x100, zmq [bg];
26181 [bg][l] overlay [bg+l];
26182 [bg+l][r] overlay@@my=x=100 "
26185 To change the color of the left side of the video, the following
26186 command can be used:
26188 echo Parsed_color_0 c yellow | tools/zmqsend
26191 To change the right side:
26193 echo Parsed_color_1 c pink | tools/zmqsend
26196 To change the position of the right side:
26198 echo overlay@@my x 150 | tools/zmqsend
26202 @c man end MULTIMEDIA FILTERS
26204 @chapter Multimedia Sources
26205 @c man begin MULTIMEDIA SOURCES
26207 Below is a description of the currently available multimedia sources.
26211 This is the same as @ref{movie} source, except it selects an audio
26217 Read audio and/or video stream(s) from a movie container.
26219 It accepts the following parameters:
26223 The name of the resource to read (not necessarily a file; it can also be a
26224 device or a stream accessed through some protocol).
26226 @item format_name, f
26227 Specifies the format assumed for the movie to read, and can be either
26228 the name of a container or an input device. If not specified, the
26229 format is guessed from @var{movie_name} or by probing.
26231 @item seek_point, sp
26232 Specifies the seek point in seconds. The frames will be output
26233 starting from this seek point. The parameter is evaluated with
26234 @code{av_strtod}, so the numerical value may be suffixed by an IS
26235 postfix. The default value is "0".
26238 Specifies the streams to read. Several streams can be specified,
26239 separated by "+". The source will then have as many outputs, in the
26240 same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers"
26241 section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify
26242 respectively the default (best suited) video and audio stream. Default
26243 is "dv", or "da" if the filter is called as "amovie".
26245 @item stream_index, si
26246 Specifies the index of the video stream to read. If the value is -1,
26247 the most suitable video stream will be automatically selected. The default
26248 value is "-1". Deprecated. If the filter is called "amovie", it will select
26249 audio instead of video.
26252 Specifies how many times to read the stream in sequence.
26253 If the value is 0, the stream will be looped infinitely.
26254 Default value is "1".
26256 Note that when the movie is looped the source timestamps are not
26257 changed, so it will generate non monotonically increasing timestamps.
26259 @item discontinuity
26260 Specifies the time difference between frames above which the point is
26261 considered a timestamp discontinuity which is removed by adjusting the later
26265 It allows overlaying a second video on top of the main input of
26266 a filtergraph, as shown in this graph:
26268 input -----------> deltapts0 --> overlay --> output
26271 movie --> scale--> deltapts1 -------+
26273 @subsection Examples
26277 Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
26278 on top of the input labelled "in":
26280 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
26281 [in] setpts=PTS-STARTPTS [main];
26282 [main][over] overlay=16:16 [out]
26286 Read from a video4linux2 device, and overlay it on top of the input
26289 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
26290 [in] setpts=PTS-STARTPTS [main];
26291 [main][over] overlay=16:16 [out]
26295 Read the first video stream and the audio stream with id 0x81 from
26296 dvd.vob; the video is connected to the pad named "video" and the audio is
26297 connected to the pad named "audio":
26299 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
26303 @subsection Commands
26305 Both movie and amovie support the following commands:
26308 Perform seek using "av_seek_frame".
26309 The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
26312 @var{stream_index}: If stream_index is -1, a default
26313 stream is selected, and @var{timestamp} is automatically converted
26314 from AV_TIME_BASE units to the stream specific time_base.
26316 @var{timestamp}: Timestamp in AVStream.time_base units
26317 or, if no stream is specified, in AV_TIME_BASE units.
26319 @var{flags}: Flags which select direction and seeking mode.
26323 Get movie duration in AV_TIME_BASE units.
26327 @c man end MULTIMEDIA SOURCES