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 This filter supports the all above options as @ref{commands}.
649 Delay audio filtering until a given wallclock timestamp. See the @ref{cue}
653 Remove impulsive noise from input audio.
655 Samples detected as impulsive noise are replaced by interpolated samples using
656 autoregressive modelling.
660 Set window size, in milliseconds. Allowed range is from @code{10} to
661 @code{100}. Default value is @code{55} milliseconds.
662 This sets size of window which will be processed at once.
665 Set window overlap, in percentage of window size. Allowed range is from
666 @code{50} to @code{95}. Default value is @code{75} percent.
667 Setting this to a very high value increases impulsive noise removal but makes
668 whole process much slower.
671 Set autoregression order, in percentage of window size. Allowed range is from
672 @code{0} to @code{25}. Default value is @code{2} percent. This option also
673 controls quality of interpolated samples using neighbour good samples.
676 Set threshold value. Allowed range is from @code{1} to @code{100}.
677 Default value is @code{2}.
678 This controls the strength of impulsive noise which is going to be removed.
679 The lower value, the more samples will be detected as impulsive noise.
682 Set burst fusion, in percentage of window size. Allowed range is @code{0} to
683 @code{10}. Default value is @code{2}.
684 If any two samples detected as noise are spaced less than this value then any
685 sample between those two samples will be also detected as noise.
690 It accepts the following values:
693 Select overlap-add method. Even not interpolated samples are slightly
694 changed with this method.
697 Select overlap-save method. Not interpolated samples remain unchanged.
700 Default value is @code{a}.
704 Remove clipped samples from input audio.
706 Samples detected as clipped are replaced by interpolated samples using
707 autoregressive modelling.
711 Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}.
712 Default value is @code{55} milliseconds.
713 This sets size of window which will be processed at once.
716 Set window overlap, in percentage of window size. Allowed range is from @code{50}
717 to @code{95}. Default value is @code{75} percent.
720 Set autoregression order, in percentage of window size. Allowed range is from
721 @code{0} to @code{25}. Default value is @code{8} percent. This option also controls
722 quality of interpolated samples using neighbour good samples.
725 Set threshold value. Allowed range is from @code{1} to @code{100}.
726 Default value is @code{10}. Higher values make clip detection less aggressive.
729 Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}.
730 Default value is @code{1000}. Higher values make clip detection less aggressive.
735 It accepts the following values:
738 Select overlap-add method. Even not interpolated samples are slightly changed
742 Select overlap-save method. Not interpolated samples remain unchanged.
745 Default value is @code{a}.
750 Delay one or more audio channels.
752 Samples in delayed channel are filled with silence.
754 The filter accepts the following option:
758 Set list of delays in milliseconds for each channel separated by '|'.
759 Unused delays will be silently ignored. If number of given delays is
760 smaller than number of channels all remaining channels will not be delayed.
761 If you want to delay exact number of samples, append 'S' to number.
762 If you want instead to delay in seconds, append 's' to number.
765 Use last set delay for all remaining channels. By default is disabled.
766 This option if enabled changes how option @code{delays} is interpreted.
773 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
774 the second channel (and any other channels that may be present) unchanged.
780 Delay second channel by 500 samples, the third channel by 700 samples and leave
781 the first channel (and any other channels that may be present) unchanged.
787 Delay all channels by same number of samples:
789 adelay=delays=64S:all=1
794 Remedy denormals in audio by adding extremely low-level noise.
796 This filter shall be placed before any filter that can produce denormals.
798 A description of the accepted parameters follows.
802 Set level of added noise in dB. Default is @code{-351}.
803 Allowed range is from -451 to -90.
806 Set type of added noise.
819 Default is @code{dc}.
824 This filter supports the all above options as @ref{commands}.
826 @section aderivative, aintegral
828 Compute derivative/integral of audio stream.
830 Applying both filters one after another produces original audio.
834 Apply echoing to the input audio.
836 Echoes are reflected sound and can occur naturally amongst mountains
837 (and sometimes large buildings) when talking or shouting; digital echo
838 effects emulate this behaviour and are often used to help fill out the
839 sound of a single instrument or vocal. The time difference between the
840 original signal and the reflection is the @code{delay}, and the
841 loudness of the reflected signal is the @code{decay}.
842 Multiple echoes can have different delays and decays.
844 A description of the accepted parameters follows.
848 Set input gain of reflected signal. Default is @code{0.6}.
851 Set output gain of reflected signal. Default is @code{0.3}.
854 Set list of time intervals in milliseconds between original signal and reflections
855 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
856 Default is @code{1000}.
859 Set list of loudness of reflected signals separated by '|'.
860 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
861 Default is @code{0.5}.
868 Make it sound as if there are twice as many instruments as are actually playing:
870 aecho=0.8:0.88:60:0.4
874 If delay is very short, then it sounds like a (metallic) robot playing music:
880 A longer delay will sound like an open air concert in the mountains:
882 aecho=0.8:0.9:1000:0.3
886 Same as above but with one more mountain:
888 aecho=0.8:0.9:1000|1800:0.3|0.25
893 Audio emphasis filter creates or restores material directly taken from LPs or
894 emphased CDs with different filter curves. E.g. to store music on vinyl the
895 signal has to be altered by a filter first to even out the disadvantages of
896 this recording medium.
897 Once the material is played back the inverse filter has to be applied to
898 restore the distortion of the frequency response.
900 The filter accepts the following options:
910 Set filter mode. For restoring material use @code{reproduction} mode, otherwise
911 use @code{production} mode. Default is @code{reproduction} mode.
914 Set filter type. Selects medium. Can be one of the following:
926 select Compact Disc (CD).
932 select 50µs (FM-KF).
934 select 75µs (FM-KF).
940 This filter supports the all above options as @ref{commands}.
944 Modify an audio signal according to the specified expressions.
946 This filter accepts one or more expressions (one for each channel),
947 which are evaluated and used to modify a corresponding audio signal.
949 It accepts the following parameters:
953 Set the '|'-separated expressions list for each separate channel. If
954 the number of input channels is greater than the number of
955 expressions, the last specified expression is used for the remaining
958 @item channel_layout, c
959 Set output channel layout. If not specified, the channel layout is
960 specified by the number of expressions. If set to @samp{same}, it will
961 use by default the same input channel layout.
964 Each expression in @var{exprs} can contain the following constants and functions:
968 channel number of the current expression
971 number of the evaluated sample, starting from 0
977 time of the evaluated sample expressed in seconds
980 @item nb_out_channels
981 input and output number of channels
984 the value of input channel with number @var{CH}
987 Note: this filter is slow. For faster processing you should use a
996 aeval=val(ch)/2:c=same
1000 Invert phase of the second channel:
1002 aeval=val(0)|-val(1)
1009 Apply fade-in/out effect to input audio.
1011 A description of the accepted parameters follows.
1015 Specify the effect type, can be either @code{in} for fade-in, or
1016 @code{out} for a fade-out effect. Default is @code{in}.
1018 @item start_sample, ss
1019 Specify the number of the start sample for starting to apply the fade
1020 effect. Default is 0.
1022 @item nb_samples, ns
1023 Specify the number of samples for which the fade effect has to last. At
1024 the end of the fade-in effect the output audio will have the same
1025 volume as the input audio, at the end of the fade-out transition
1026 the output audio will be silence. Default is 44100.
1028 @item start_time, st
1029 Specify the start time of the fade effect. Default is 0.
1030 The value must be specified as a time duration; see
1031 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1032 for the accepted syntax.
1033 If set this option is used instead of @var{start_sample}.
1036 Specify the duration of the fade effect. See
1037 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1038 for the accepted syntax.
1039 At the end of the fade-in effect the output audio will have the same
1040 volume as the input audio, at the end of the fade-out transition
1041 the output audio will be silence.
1042 By default the duration is determined by @var{nb_samples}.
1043 If set this option is used instead of @var{nb_samples}.
1046 Set curve for fade transition.
1048 It accepts the following values:
1051 select triangular, linear slope (default)
1053 select quarter of sine wave
1055 select half of sine wave
1057 select exponential sine wave
1061 select inverted parabola
1075 select inverted quarter of sine wave
1077 select inverted half of sine wave
1079 select double-exponential seat
1081 select double-exponential sigmoid
1083 select logistic sigmoid
1085 select sine cardinal function
1087 select inverted sine cardinal function
1093 @subsection Commands
1095 This filter supports the all above options as @ref{commands}.
1097 @subsection Examples
1101 Fade in first 15 seconds of audio:
1103 afade=t=in:ss=0:d=15
1107 Fade out last 25 seconds of a 900 seconds audio:
1109 afade=t=out:st=875:d=25
1114 Denoise audio samples with FFT.
1116 A description of the accepted parameters follows.
1120 Set the noise reduction in dB, allowed range is 0.01 to 97.
1121 Default value is 12 dB.
1124 Set the noise floor in dB, allowed range is -80 to -20.
1125 Default value is -50 dB.
1130 It accepts the following values:
1139 Select shellac noise.
1142 Select custom noise, defined in @code{bn} option.
1144 Default value is white noise.
1148 Set custom band noise for every one of 15 bands.
1149 Bands are separated by ' ' or '|'.
1152 Set the residual floor in dB, allowed range is -80 to -20.
1153 Default value is -38 dB.
1156 Enable noise tracking. By default is disabled.
1157 With this enabled, noise floor is automatically adjusted.
1160 Enable residual tracking. By default is disabled.
1163 Set the output mode.
1165 It accepts the following values:
1168 Pass input unchanged.
1171 Pass noise filtered out.
1176 Default value is @var{o}.
1180 @subsection Commands
1182 This filter supports the following commands:
1184 @item sample_noise, sn
1185 Start or stop measuring noise profile.
1186 Syntax for the command is : "start" or "stop" string.
1187 After measuring noise profile is stopped it will be
1188 automatically applied in filtering.
1190 @item noise_reduction, nr
1191 Change noise reduction. Argument is single float number.
1192 Syntax for the command is : "@var{noise_reduction}"
1194 @item noise_floor, nf
1195 Change noise floor. Argument is single float number.
1196 Syntax for the command is : "@var{noise_floor}"
1198 @item output_mode, om
1199 Change output mode operation.
1200 Syntax for the command is : "i", "o" or "n" string.
1204 Apply arbitrary expressions to samples in frequency domain.
1208 Set frequency domain real expression for each separate channel separated
1209 by '|'. Default is "re".
1210 If the number of input channels is greater than the number of
1211 expressions, the last specified expression is used for the remaining
1215 Set frequency domain imaginary expression for each separate channel
1216 separated by '|'. Default is "im".
1218 Each expression in @var{real} and @var{imag} can contain the following
1219 constants and functions:
1226 current frequency bin number
1229 number of available bins
1232 channel number of the current expression
1241 current real part of frequency bin of current channel
1244 current imaginary part of frequency bin of current channel
1247 Return the value of real part of frequency bin at location (@var{bin},@var{channel})
1250 Return the value of imaginary part of frequency bin at location (@var{bin},@var{channel})
1254 Set window size. Allowed range is from 16 to 131072.
1255 Default is @code{4096}
1258 Set window function. Default is @code{hann}.
1261 Set window overlap. If set to 1, the recommended overlap for selected
1262 window function will be picked. Default is @code{0.75}.
1265 @subsection Examples
1269 Leave almost only low frequencies in audio:
1271 afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"
1275 Apply robotize effect:
1277 afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75"
1281 Apply whisper effect:
1283 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"
1290 Apply an arbitrary Finite Impulse Response filter.
1292 This filter is designed for applying long FIR filters,
1293 up to 60 seconds long.
1295 It can be used as component for digital crossover filters,
1296 room equalization, cross talk cancellation, wavefield synthesis,
1297 auralization, ambiophonics, ambisonics and spatialization.
1299 This filter uses the streams higher than first one as FIR coefficients.
1300 If the non-first stream holds a single channel, it will be used
1301 for all input channels in the first stream, otherwise
1302 the number of channels in the non-first stream must be same as
1303 the number of channels in the first stream.
1305 It accepts the following parameters:
1309 Set dry gain. This sets input gain.
1312 Set wet gain. This sets final output gain.
1315 Set Impulse Response filter length. Default is 1, which means whole IR is processed.
1318 Enable applying gain measured from power of IR.
1320 Set which approach to use for auto gain measurement.
1324 Do not apply any gain.
1327 select peak gain, very conservative approach. This is default value.
1330 select DC gain, limited application.
1333 select gain to noise approach, this is most popular one.
1337 Set gain to be applied to IR coefficients before filtering.
1338 Allowed range is 0 to 1. This gain is applied after any gain applied with @var{gtype} option.
1341 Set format of IR stream. Can be @code{mono} or @code{input}.
1342 Default is @code{input}.
1345 Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds.
1346 Allowed range is 0.1 to 60 seconds.
1349 Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
1350 By default it is disabled.
1353 Set for which IR channel to display frequency response. By default is first channel
1354 displayed. This option is used only when @var{response} is enabled.
1357 Set video stream size. This option is used only when @var{response} is enabled.
1360 Set video stream frame rate. This option is used only when @var{response} is enabled.
1363 Set minimal partition size used for convolution. Default is @var{8192}.
1364 Allowed range is from @var{1} to @var{32768}.
1365 Lower values decreases latency at cost of higher CPU usage.
1368 Set maximal partition size used for convolution. Default is @var{8192}.
1369 Allowed range is from @var{8} to @var{32768}.
1370 Lower values may increase CPU usage.
1373 Set number of input impulse responses streams which will be switchable at runtime.
1374 Allowed range is from @var{1} to @var{32}. Default is @var{1}.
1377 Set IR stream which will be used for convolution, starting from @var{0}, should always be
1378 lower than supplied value by @code{nbirs} option. Default is @var{0}.
1379 This option can be changed at runtime via @ref{commands}.
1382 @subsection Examples
1386 Apply reverb to stream using mono IR file as second input, complete command using ffmpeg:
1388 ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
1395 Set output format constraints for the input audio. The framework will
1396 negotiate the most appropriate format to minimize conversions.
1398 It accepts the following parameters:
1401 @item sample_fmts, f
1402 A '|'-separated list of requested sample formats.
1404 @item sample_rates, r
1405 A '|'-separated list of requested sample rates.
1407 @item channel_layouts, cl
1408 A '|'-separated list of requested channel layouts.
1410 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1411 for the required syntax.
1414 If a parameter is omitted, all values are allowed.
1416 Force the output to either unsigned 8-bit or signed 16-bit stereo
1418 aformat=sample_fmts=u8|s16:channel_layouts=stereo
1422 Apply frequency shift to input audio samples.
1424 The filter accepts the following options:
1428 Specify frequency shift. Allowed range is -INT_MAX to INT_MAX.
1429 Default value is 0.0.
1432 Set output gain applied to final output. Allowed range is from 0.0 to 1.0.
1433 Default value is 1.0.
1436 @subsection Commands
1438 This filter supports the all above options as @ref{commands}.
1442 A gate is mainly used to reduce lower parts of a signal. This kind of signal
1443 processing reduces disturbing noise between useful signals.
1445 Gating is done by detecting the volume below a chosen level @var{threshold}
1446 and dividing it by the factor set with @var{ratio}. The bottom of the noise
1447 floor is set via @var{range}. Because an exact manipulation of the signal
1448 would cause distortion of the waveform the reduction can be levelled over
1449 time. This is done by setting @var{attack} and @var{release}.
1451 @var{attack} determines how long the signal has to fall below the threshold
1452 before any reduction will occur and @var{release} sets the time the signal
1453 has to rise above the threshold to reduce the reduction again.
1454 Shorter signals than the chosen attack time will be left untouched.
1458 Set input level before filtering.
1459 Default is 1. Allowed range is from 0.015625 to 64.
1462 Set the mode of operation. Can be @code{upward} or @code{downward}.
1463 Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
1464 will be amplified, expanding dynamic range in upward direction.
1465 Otherwise, in case of @code{downward} lower parts of signal will be reduced.
1468 Set the level of gain reduction when the signal is below the threshold.
1469 Default is 0.06125. Allowed range is from 0 to 1.
1470 Setting this to 0 disables reduction and then filter behaves like expander.
1473 If a signal rises above this level the gain reduction is released.
1474 Default is 0.125. Allowed range is from 0 to 1.
1477 Set a ratio by which the signal is reduced.
1478 Default is 2. Allowed range is from 1 to 9000.
1481 Amount of milliseconds the signal has to rise above the threshold before gain
1483 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
1486 Amount of milliseconds the signal has to fall below the threshold before the
1487 reduction is increased again. Default is 250 milliseconds.
1488 Allowed range is from 0.01 to 9000.
1491 Set amount of amplification of signal after processing.
1492 Default is 1. Allowed range is from 1 to 64.
1495 Curve the sharp knee around the threshold to enter gain reduction more softly.
1496 Default is 2.828427125. Allowed range is from 1 to 8.
1499 Choose if exact signal should be taken for detection or an RMS like one.
1500 Default is @code{rms}. Can be @code{peak} or @code{rms}.
1503 Choose if the average level between all channels or the louder channel affects
1505 Default is @code{average}. Can be @code{average} or @code{maximum}.
1508 @subsection Commands
1510 This filter supports the all above options as @ref{commands}.
1514 Apply an arbitrary Infinite Impulse Response filter.
1516 It accepts the following parameters:
1520 Set B/numerator/zeros/reflection coefficients.
1523 Set A/denominator/poles/ladder coefficients.
1535 Set coefficients format.
1539 lattice-ladder function
1541 analog transfer function
1543 digital transfer function
1545 Z-plane zeros/poles, cartesian (default)
1547 Z-plane zeros/poles, polar radians
1549 Z-plane zeros/poles, polar degrees
1555 Set type of processing.
1567 Set filtering precision.
1571 double-precision floating-point (default)
1573 single-precision floating-point
1581 Normalize filter coefficients, by default is enabled.
1582 Enabling it will normalize magnitude response at DC to 0dB.
1585 How much to use filtered signal in output. Default is 1.
1586 Range is between 0 and 1.
1589 Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
1590 By default it is disabled.
1593 Set for which IR channel to display frequency response. By default is first channel
1594 displayed. This option is used only when @var{response} is enabled.
1597 Set video stream size. This option is used only when @var{response} is enabled.
1600 Coefficients in @code{tf} and @code{sf} format are separated by spaces and are in ascending
1603 Coefficients in @code{zp} format are separated by spaces and order of coefficients
1604 doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i}
1607 Different coefficients and gains can be provided for every channel, in such case
1608 use '|' to separate coefficients or gains. Last provided coefficients will be
1609 used for all remaining channels.
1611 @subsection Examples
1615 Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate:
1617 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
1621 Same as above but in @code{zp} format:
1623 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
1627 Apply 3-rd order analog normalized Butterworth low-pass filter, using analog transfer function format:
1629 aiir=z=1.3057 0 0 0:p=1.3057 2.3892 2.1860 1:f=sf:r=d
1635 The limiter prevents an input signal from rising over a desired threshold.
1636 This limiter uses lookahead technology to prevent your signal from distorting.
1637 It means that there is a small delay after the signal is processed. Keep in mind
1638 that the delay it produces is the attack time you set.
1640 The filter accepts the following options:
1644 Set input gain. Default is 1.
1647 Set output gain. Default is 1.
1650 Don't let signals above this level pass the limiter. Default is 1.
1653 The limiter will reach its attenuation level in this amount of time in
1654 milliseconds. Default is 5 milliseconds.
1657 Come back from limiting to attenuation 1.0 in this amount of milliseconds.
1658 Default is 50 milliseconds.
1661 When gain reduction is always needed ASC takes care of releasing to an
1662 average reduction level rather than reaching a reduction of 0 in the release
1666 Select how much the release time is affected by ASC, 0 means nearly no changes
1667 in release time while 1 produces higher release times.
1670 Auto level output signal. Default is enabled.
1671 This normalizes audio back to 0dB if enabled.
1674 Depending on picked setting it is recommended to upsample input 2x or 4x times
1675 with @ref{aresample} before applying this filter.
1679 Apply a two-pole all-pass filter with central frequency (in Hz)
1680 @var{frequency}, and filter-width @var{width}.
1681 An all-pass filter changes the audio's frequency to phase relationship
1682 without changing its frequency to amplitude relationship.
1684 The filter accepts the following options:
1688 Set frequency in Hz.
1691 Set method to specify band-width of filter.
1706 Specify the band-width of a filter in width_type units.
1709 How much to use filtered signal in output. Default is 1.
1710 Range is between 0 and 1.
1713 Specify which channels to filter, by default all available are filtered.
1716 Normalize biquad coefficients, by default is disabled.
1717 Enabling it will normalize magnitude response at DC to 0dB.
1720 Set the filter order, can be 1 or 2. Default is 2.
1723 Set transform type of IIR filter.
1732 Set precison of filtering.
1735 Pick automatic sample format depending on surround filters.
1737 Always use signed 16-bit.
1739 Always use signed 32-bit.
1741 Always use float 32-bit.
1743 Always use float 64-bit.
1747 @subsection Commands
1749 This filter supports the following commands:
1752 Change allpass frequency.
1753 Syntax for the command is : "@var{frequency}"
1756 Change allpass width_type.
1757 Syntax for the command is : "@var{width_type}"
1760 Change allpass width.
1761 Syntax for the command is : "@var{width}"
1765 Syntax for the command is : "@var{mix}"
1772 The filter accepts the following options:
1776 Set the number of loops. Setting this value to -1 will result in infinite loops.
1780 Set maximal number of samples. Default is 0.
1783 Set first sample of loop. Default is 0.
1789 Merge two or more audio streams into a single multi-channel stream.
1791 The filter accepts the following options:
1796 Set the number of inputs. Default is 2.
1800 If the channel layouts of the inputs are disjoint, and therefore compatible,
1801 the channel layout of the output will be set accordingly and the channels
1802 will be reordered as necessary. If the channel layouts of the inputs are not
1803 disjoint, the output will have all the channels of the first input then all
1804 the channels of the second input, in that order, and the channel layout of
1805 the output will be the default value corresponding to the total number of
1808 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
1809 is FC+BL+BR, then the output will be in 5.1, with the channels in the
1810 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
1811 first input, b1 is the first channel of the second input).
1813 On the other hand, if both input are in stereo, the output channels will be
1814 in the default order: a1, a2, b1, b2, and the channel layout will be
1815 arbitrarily set to 4.0, which may or may not be the expected value.
1817 All inputs must have the same sample rate, and format.
1819 If inputs do not have the same duration, the output will stop with the
1822 @subsection Examples
1826 Merge two mono files into a stereo stream:
1828 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
1832 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
1834 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
1840 Mixes multiple audio inputs into a single output.
1842 Note that this filter only supports float samples (the @var{amerge}
1843 and @var{pan} audio filters support many formats). If the @var{amix}
1844 input has integer samples then @ref{aresample} will be automatically
1845 inserted to perform the conversion to float samples.
1849 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
1851 will mix 3 input audio streams to a single output with the same duration as the
1852 first input and a dropout transition time of 3 seconds.
1854 It accepts the following parameters:
1858 The number of inputs. If unspecified, it defaults to 2.
1861 How to determine the end-of-stream.
1865 The duration of the longest input. (default)
1868 The duration of the shortest input.
1871 The duration of the first input.
1875 @item dropout_transition
1876 The transition time, in seconds, for volume renormalization when an input
1877 stream ends. The default value is 2 seconds.
1880 Specify weight of each input audio stream as sequence.
1881 Each weight is separated by space. By default all inputs have same weight.
1884 @subsection Commands
1886 This filter supports the following commands:
1889 Syntax is same as option with same name.
1894 Multiply first audio stream with second audio stream and store result
1895 in output audio stream. Multiplication is done by multiplying each
1896 sample from first stream with sample at same position from second stream.
1898 With this element-wise multiplication one can create amplitude fades and
1899 amplitude modulations.
1901 @section anequalizer
1903 High-order parametric multiband equalizer for each channel.
1905 It accepts the following parameters:
1909 This option string is in format:
1910 "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
1911 Each equalizer band is separated by '|'.
1915 Set channel number to which equalization will be applied.
1916 If input doesn't have that channel the entry is ignored.
1919 Set central frequency for band.
1920 If input doesn't have that frequency the entry is ignored.
1923 Set band width in Hertz.
1926 Set band gain in dB.
1929 Set filter type for band, optional, can be:
1933 Butterworth, this is default.
1944 With this option activated frequency response of anequalizer is displayed
1948 Set video stream size. Only useful if curves option is activated.
1951 Set max gain that will be displayed. Only useful if curves option is activated.
1952 Setting this to a reasonable value makes it possible to display gain which is derived from
1953 neighbour bands which are too close to each other and thus produce higher gain
1954 when both are activated.
1957 Set frequency scale used to draw frequency response in video output.
1958 Can be linear or logarithmic. Default is logarithmic.
1961 Set color for each channel curve which is going to be displayed in video stream.
1962 This is list of color names separated by space or by '|'.
1963 Unrecognised or missing colors will be replaced by white color.
1966 @subsection Examples
1970 Lower gain by 10 of central frequency 200Hz and width 100 Hz
1971 for first 2 channels using Chebyshev type 1 filter:
1973 anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
1977 @subsection Commands
1979 This filter supports the following commands:
1982 Alter existing filter parameters.
1983 Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
1985 @var{fN} is existing filter number, starting from 0, if no such filter is available
1987 @var{freq} set new frequency parameter.
1988 @var{width} set new width parameter in Hertz.
1989 @var{gain} set new gain parameter in dB.
1991 Full filter invocation with asendcmd may look like this:
1992 asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
1997 Reduce broadband noise in audio samples using Non-Local Means algorithm.
1999 Each sample is adjusted by looking for other samples with similar contexts. This
2000 context similarity is defined by comparing their surrounding patches of size
2001 @option{p}. Patches are searched in an area of @option{r} around the sample.
2003 The filter accepts the following options:
2007 Set denoising strength. Allowed range is from 0.00001 to 10. Default value is 0.00001.
2010 Set patch radius duration. Allowed range is from 1 to 100 milliseconds.
2011 Default value is 2 milliseconds.
2014 Set research radius duration. Allowed range is from 2 to 300 milliseconds.
2015 Default value is 6 milliseconds.
2018 Set the output mode.
2020 It accepts the following values:
2023 Pass input unchanged.
2026 Pass noise filtered out.
2031 Default value is @var{o}.
2035 Set smooth factor. Default value is @var{11}. Allowed range is from @var{1} to @var{15}.
2038 @subsection Commands
2040 This filter supports the all above options as @ref{commands}.
2043 Apply Normalized Least-Mean-Squares algorithm to the first audio stream using the second audio stream.
2045 This adaptive filter is used to mimic a desired filter by finding the filter coefficients that
2046 relate to producing the least mean square of the error signal (difference between the desired,
2047 2nd input audio stream and the actual signal, the 1st input audio stream).
2049 A description of the accepted options follows.
2062 Set the filter leakage.
2065 It accepts the following values:
2074 Pass filtered samples.
2077 Pass difference between desired and filtered samples.
2079 Default value is @var{o}.
2083 @subsection Examples
2087 One of many usages of this filter is noise reduction, input audio is filtered
2088 with same samples that are delayed by fixed amount, one such example for stereo audio is:
2090 asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o
2094 @subsection Commands
2096 This filter supports the same commands as options, excluding option @code{order}.
2100 Pass the audio source unchanged to the output.
2104 Pad the end of an audio stream with silence.
2106 This can be used together with @command{ffmpeg} @option{-shortest} to
2107 extend audio streams to the same length as the video stream.
2109 A description of the accepted options follows.
2113 Set silence packet size. Default value is 4096.
2116 Set the number of samples of silence to add to the end. After the
2117 value is reached, the stream is terminated. This option is mutually
2118 exclusive with @option{whole_len}.
2121 Set the minimum total number of samples in the output audio stream. If
2122 the value is longer than the input audio length, silence is added to
2123 the end, until the value is reached. This option is mutually exclusive
2124 with @option{pad_len}.
2127 Specify the duration of samples of silence to add. See
2128 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
2129 for the accepted syntax. Used only if set to non-zero value.
2132 Specify the minimum total duration in the output audio stream. See
2133 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
2134 for the accepted syntax. Used only if set to non-zero value. If the value is longer than
2135 the input audio length, silence is added to the end, until the value is reached.
2136 This option is mutually exclusive with @option{pad_dur}
2139 If neither the @option{pad_len} nor the @option{whole_len} nor @option{pad_dur}
2140 nor @option{whole_dur} option is set, the filter will add silence to the end of
2141 the input stream indefinitely.
2143 @subsection Examples
2147 Add 1024 samples of silence to the end of the input:
2153 Make sure the audio output will contain at least 10000 samples, pad
2154 the input with silence if required:
2156 apad=whole_len=10000
2160 Use @command{ffmpeg} to pad the audio input with silence, so that the
2161 video stream will always result the shortest and will be converted
2162 until the end in the output file when using the @option{shortest}
2165 ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
2170 Add a phasing effect to the input audio.
2172 A phaser filter creates series of peaks and troughs in the frequency spectrum.
2173 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
2175 A description of the accepted parameters follows.
2179 Set input gain. Default is 0.4.
2182 Set output gain. Default is 0.74
2185 Set delay in milliseconds. Default is 3.0.
2188 Set decay. Default is 0.4.
2191 Set modulation speed in Hz. Default is 0.5.
2194 Set modulation type. Default is triangular.
2196 It accepts the following values:
2203 @section aphaseshift
2204 Apply phase shift to input audio samples.
2206 The filter accepts the following options:
2210 Specify phase shift. Allowed range is from -1.0 to 1.0.
2211 Default value is 0.0.
2214 Set output gain applied to final output. Allowed range is from 0.0 to 1.0.
2215 Default value is 1.0.
2218 @subsection Commands
2220 This filter supports the all above options as @ref{commands}.
2224 Audio pulsator is something between an autopanner and a tremolo.
2225 But it can produce funny stereo effects as well. Pulsator changes the volume
2226 of the left and right channel based on a LFO (low frequency oscillator) with
2227 different waveforms and shifted phases.
2228 This filter have the ability to define an offset between left and right
2229 channel. An offset of 0 means that both LFO shapes match each other.
2230 The left and right channel are altered equally - a conventional tremolo.
2231 An offset of 50% means that the shape of the right channel is exactly shifted
2232 in phase (or moved backwards about half of the frequency) - pulsator acts as
2233 an autopanner. At 1 both curves match again. Every setting in between moves the
2234 phase shift gapless between all stages and produces some "bypassing" sounds with
2235 sine and triangle waveforms. The more you set the offset near 1 (starting from
2236 the 0.5) the faster the signal passes from the left to the right speaker.
2238 The filter accepts the following options:
2242 Set input gain. By default it is 1. Range is [0.015625 - 64].
2245 Set output gain. By default it is 1. Range is [0.015625 - 64].
2248 Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
2249 sawup or sawdown. Default is sine.
2252 Set modulation. Define how much of original signal is affected by the LFO.
2255 Set left channel offset. Default is 0. Allowed range is [0 - 1].
2258 Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
2261 Set pulse width. Default is 1. Allowed range is [0 - 2].
2264 Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
2267 Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
2271 Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
2275 Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
2276 if timing is set to hz.
2282 Resample the input audio to the specified parameters, using the
2283 libswresample library. If none are specified then the filter will
2284 automatically convert between its input and output.
2286 This filter is also able to stretch/squeeze the audio data to make it match
2287 the timestamps or to inject silence / cut out audio to make it match the
2288 timestamps, do a combination of both or do neither.
2290 The filter accepts the syntax
2291 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
2292 expresses a sample rate and @var{resampler_options} is a list of
2293 @var{key}=@var{value} pairs, separated by ":". See the
2294 @ref{Resampler Options,,"Resampler Options" section in the
2295 ffmpeg-resampler(1) manual,ffmpeg-resampler}
2296 for the complete list of supported options.
2298 @subsection Examples
2302 Resample the input audio to 44100Hz:
2308 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
2309 samples per second compensation:
2311 aresample=async=1000
2317 Reverse an audio clip.
2319 Warning: This filter requires memory to buffer the entire clip, so trimming
2322 @subsection Examples
2326 Take the first 5 seconds of a clip, and reverse it.
2328 atrim=end=5,areverse
2334 Reduce noise from speech using Recurrent Neural Networks.
2336 This filter accepts the following options:
2340 Set train model file to load. This option is always required.
2343 Set how much to mix filtered samples into final output.
2344 Allowed range is from -1 to 1. Default value is 1.
2345 Negative values are special, they set how much to keep filtered noise
2346 in the final filter output. Set this option to -1 to hear actual
2347 noise removed from input signal.
2350 @section asetnsamples
2352 Set the number of samples per each output audio frame.
2354 The last output packet may contain a different number of samples, as
2355 the filter will flush all the remaining samples when the input audio
2358 The filter accepts the following options:
2362 @item nb_out_samples, n
2363 Set the number of frames per each output audio frame. The number is
2364 intended as the number of samples @emph{per each channel}.
2365 Default value is 1024.
2368 If set to 1, the filter will pad the last audio frame with zeroes, so
2369 that the last frame will contain the same number of samples as the
2370 previous ones. Default value is 1.
2373 For example, to set the number of per-frame samples to 1234 and
2374 disable padding for the last frame, use:
2376 asetnsamples=n=1234:p=0
2381 Set the sample rate without altering the PCM data.
2382 This will result in a change of speed and pitch.
2384 The filter accepts the following options:
2387 @item sample_rate, r
2388 Set the output sample rate. Default is 44100 Hz.
2393 Show a line containing various information for each input audio frame.
2394 The input audio is not modified.
2396 The shown line contains a sequence of key/value pairs of the form
2397 @var{key}:@var{value}.
2399 The following values are shown in the output:
2403 The (sequential) number of the input frame, starting from 0.
2406 The presentation timestamp of the input frame, in time base units; the time base
2407 depends on the filter input pad, and is usually 1/@var{sample_rate}.
2410 The presentation timestamp of the input frame in seconds.
2413 position of the frame in the input stream, -1 if this information in
2414 unavailable and/or meaningless (for example in case of synthetic audio)
2423 The sample rate for the audio frame.
2426 The number of samples (per channel) in the frame.
2429 The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
2430 audio, the data is treated as if all the planes were concatenated.
2432 @item plane_checksums
2433 A list of Adler-32 checksums for each data plane.
2437 Apply audio soft clipping.
2439 Soft clipping is a type of distortion effect where the amplitude of a signal is saturated
2440 along a smooth curve, rather than the abrupt shape of hard-clipping.
2442 This filter accepts the following options:
2446 Set type of soft-clipping.
2448 It accepts the following values:
2462 Set threshold from where to start clipping. Default value is 0dB or 1.
2465 Set gain applied to output. Default value is 0dB or 1.
2468 Set additional parameter which controls sigmoid function.
2471 Set oversampling factor.
2474 @subsection Commands
2476 This filter supports the all above options as @ref{commands}.
2479 Automatic Speech Recognition
2481 This filter uses PocketSphinx for speech recognition. To enable
2482 compilation of this filter, you need to configure FFmpeg with
2483 @code{--enable-pocketsphinx}.
2485 It accepts the following options:
2489 Set sampling rate of input audio. Defaults is @code{16000}.
2490 This need to match speech models, otherwise one will get poor results.
2493 Set dictionary containing acoustic model files.
2496 Set pronunciation dictionary.
2499 Set language model file.
2502 Set language model set.
2505 Set which language model to use.
2508 Set output for log messages.
2511 The filter exports recognized speech as the frame metadata @code{lavfi.asr.text}.
2516 Display time domain statistical information about the audio channels.
2517 Statistics are calculated and displayed for each audio channel and,
2518 where applicable, an overall figure is also given.
2520 It accepts the following option:
2523 Short window length in seconds, used for peak and trough RMS measurement.
2524 Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}.
2528 Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
2529 where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
2532 Available keys for each channel are:
2578 For example full key look like this @code{lavfi.astats.1.DC_offset} or
2579 this @code{lavfi.astats.Overall.Peak_count}.
2581 For description what each key means read below.
2584 Set number of frame after which stats are going to be recalculated.
2585 Default is disabled.
2587 @item measure_perchannel
2588 Select the entries which need to be measured per channel. The metadata keys can
2589 be used as flags, default is @option{all} which measures everything.
2590 @option{none} disables all per channel measurement.
2592 @item measure_overall
2593 Select the entries which need to be measured overall. The metadata keys can
2594 be used as flags, default is @option{all} which measures everything.
2595 @option{none} disables all overall measurement.
2599 A description of each shown parameter follows:
2603 Mean amplitude displacement from zero.
2606 Minimal sample level.
2609 Maximal sample level.
2611 @item Min difference
2612 Minimal difference between two consecutive samples.
2614 @item Max difference
2615 Maximal difference between two consecutive samples.
2617 @item Mean difference
2618 Mean difference between two consecutive samples.
2619 The average of each difference between two consecutive samples.
2621 @item RMS difference
2622 Root Mean Square difference between two consecutive samples.
2626 Standard peak and RMS level measured in dBFS.
2630 Peak and trough values for RMS level measured over a short window.
2633 Standard ratio of peak to RMS level (note: not in dB).
2636 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
2637 (i.e. either @var{Min level} or @var{Max level}).
2640 Number of occasions (not the number of samples) that the signal attained either
2641 @var{Min level} or @var{Max level}.
2643 @item Noise floor dB
2644 Minimum local peak measured in dBFS over a short window.
2646 @item Noise floor count
2647 Number of occasions (not the number of samples) that the signal attained
2651 Overall bit depth of audio. Number of bits used for each sample.
2654 Measured dynamic range of audio in dB.
2656 @item Zero crossings
2657 Number of points where the waveform crosses the zero level axis.
2659 @item Zero crossings rate
2660 Rate of Zero crossings and number of audio samples.
2664 Boost subwoofer frequencies.
2666 The filter accepts the following options:
2670 Set dry gain, how much of original signal is kept. Allowed range is from 0 to 1.
2671 Default value is 0.7.
2674 Set wet gain, how much of filtered signal is kept. Allowed range is from 0 to 1.
2675 Default value is 0.7.
2678 Set delay line decay gain value. Allowed range is from 0 to 1.
2679 Default value is 0.7.
2682 Set delay line feedback gain value. Allowed range is from 0 to 1.
2683 Default value is 0.9.
2686 Set cutoff frequency in Hertz. Allowed range is 50 to 900.
2687 Default value is 100.
2690 Set slope amount for cutoff frequency. Allowed range is 0.0001 to 1.
2691 Default value is 0.5.
2694 Set delay. Allowed range is from 1 to 100.
2695 Default value is 20.
2698 @subsection Commands
2700 This filter supports the all above options as @ref{commands}.
2703 Cut subwoofer frequencies.
2705 This filter allows to set custom, steeper
2706 roll off than highpass filter, and thus is able to more attenuate
2707 frequency content in stop-band.
2709 The filter accepts the following options:
2713 Set cutoff frequency in Hertz. Allowed range is 2 to 200.
2714 Default value is 20.
2717 Set filter order. Available values are from 3 to 20.
2718 Default value is 10.
2721 Set input gain level. Allowed range is from 0 to 1. Default value is 1.
2724 @subsection Commands
2726 This filter supports the all above options as @ref{commands}.
2729 Cut super frequencies.
2731 The filter accepts the following options:
2735 Set cutoff frequency in Hertz. Allowed range is 20000 to 192000.
2736 Default value is 20000.
2739 Set filter order. Available values are from 3 to 20.
2740 Default value is 10.
2743 Set input gain level. Allowed range is from 0 to 1. Default value is 1.
2746 @subsection Commands
2748 This filter supports the all above options as @ref{commands}.
2751 Apply high order Butterworth band-pass filter.
2753 The filter accepts the following options:
2757 Set center frequency in Hertz. Allowed range is 2 to 999999.
2758 Default value is 1000.
2761 Set filter order. Available values are from 4 to 20.
2765 Set Q-factor. Allowed range is from 0.01 to 100. Default value is 1.
2768 Set input gain level. Allowed range is from 0 to 2. Default value is 1.
2771 @subsection Commands
2773 This filter supports the all above options as @ref{commands}.
2776 Apply high order Butterworth band-stop filter.
2778 The filter accepts the following options:
2782 Set center frequency in Hertz. Allowed range is 2 to 999999.
2783 Default value is 1000.
2786 Set filter order. Available values are from 4 to 20.
2790 Set Q-factor. Allowed range is from 0.01 to 100. Default value is 1.
2793 Set input gain level. Allowed range is from 0 to 2. Default value is 1.
2796 @subsection Commands
2798 This filter supports the all above options as @ref{commands}.
2804 The filter accepts exactly one parameter, the audio tempo. If not
2805 specified then the filter will assume nominal 1.0 tempo. Tempo must
2806 be in the [0.5, 100.0] range.
2808 Note that tempo greater than 2 will skip some samples rather than
2809 blend them in. If for any reason this is a concern it is always
2810 possible to daisy-chain several instances of atempo to achieve the
2811 desired product tempo.
2813 @subsection Examples
2817 Slow down audio to 80% tempo:
2823 To speed up audio to 300% tempo:
2829 To speed up audio to 300% tempo by daisy-chaining two atempo instances:
2831 atempo=sqrt(3),atempo=sqrt(3)
2835 @subsection Commands
2837 This filter supports the following commands:
2840 Change filter tempo scale factor.
2841 Syntax for the command is : "@var{tempo}"
2846 Trim the input so that the output contains one continuous subpart of the input.
2848 It accepts the following parameters:
2851 Timestamp (in seconds) of the start of the section to keep. I.e. the audio
2852 sample with the timestamp @var{start} will be the first sample in the output.
2855 Specify time of the first audio sample that will be dropped, i.e. the
2856 audio sample immediately preceding the one with the timestamp @var{end} will be
2857 the last sample in the output.
2860 Same as @var{start}, except this option sets the start timestamp in samples
2864 Same as @var{end}, except this option sets the end timestamp in samples instead
2868 The maximum duration of the output in seconds.
2871 The number of the first sample that should be output.
2874 The number of the first sample that should be dropped.
2877 @option{start}, @option{end}, and @option{duration} are expressed as time
2878 duration specifications; see
2879 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
2881 Note that the first two sets of the start/end options and the @option{duration}
2882 option look at the frame timestamp, while the _sample options simply count the
2883 samples that pass through the filter. So start/end_pts and start/end_sample will
2884 give different results when the timestamps are wrong, inexact or do not start at
2885 zero. Also note that this filter does not modify the timestamps. If you wish
2886 to have the output timestamps start at zero, insert the asetpts filter after the
2889 If multiple start or end options are set, this filter tries to be greedy and
2890 keep all samples that match at least one of the specified constraints. To keep
2891 only the part that matches all the constraints at once, chain multiple atrim
2894 The defaults are such that all the input is kept. So it is possible to set e.g.
2895 just the end values to keep everything before the specified time.
2900 Drop everything except the second minute of input:
2902 ffmpeg -i INPUT -af atrim=60:120
2906 Keep only the first 1000 samples:
2908 ffmpeg -i INPUT -af atrim=end_sample=1000
2913 @section axcorrelate
2914 Calculate normalized cross-correlation between two input audio streams.
2916 Resulted samples are always between -1 and 1 inclusive.
2917 If result is 1 it means two input samples are highly correlated in that selected segment.
2918 Result 0 means they are not correlated at all.
2919 If result is -1 it means two input samples are out of phase, which means they cancel each
2922 The filter accepts the following options:
2926 Set size of segment over which cross-correlation is calculated.
2927 Default is 256. Allowed range is from 2 to 131072.
2930 Set algorithm for cross-correlation. Can be @code{slow} or @code{fast}.
2931 Default is @code{slow}. Fast algorithm assumes mean values over any given segment
2932 are always zero and thus need much less calculations to make.
2933 This is generally not true, but is valid for typical audio streams.
2936 @subsection Examples
2940 Calculate correlation between channels in stereo audio stream:
2942 ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav
2948 Apply a two-pole Butterworth band-pass filter with central
2949 frequency @var{frequency}, and (3dB-point) band-width width.
2950 The @var{csg} option selects a constant skirt gain (peak gain = Q)
2951 instead of the default: constant 0dB peak gain.
2952 The filter roll off at 6dB per octave (20dB per decade).
2954 The filter accepts the following options:
2958 Set the filter's central frequency. Default is @code{3000}.
2961 Constant skirt gain if set to 1. Defaults to 0.
2964 Set method to specify band-width of filter.
2979 Specify the band-width of a filter in width_type units.
2982 How much to use filtered signal in output. Default is 1.
2983 Range is between 0 and 1.
2986 Specify which channels to filter, by default all available are filtered.
2989 Normalize biquad coefficients, by default is disabled.
2990 Enabling it will normalize magnitude response at DC to 0dB.
2993 Set transform type of IIR filter.
3002 Set precison of filtering.
3005 Pick automatic sample format depending on surround filters.
3007 Always use signed 16-bit.
3009 Always use signed 32-bit.
3011 Always use float 32-bit.
3013 Always use float 64-bit.
3017 @subsection Commands
3019 This filter supports the following commands:
3022 Change bandpass frequency.
3023 Syntax for the command is : "@var{frequency}"
3026 Change bandpass width_type.
3027 Syntax for the command is : "@var{width_type}"
3030 Change bandpass width.
3031 Syntax for the command is : "@var{width}"
3034 Change bandpass mix.
3035 Syntax for the command is : "@var{mix}"
3040 Apply a two-pole Butterworth band-reject filter with central
3041 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
3042 The filter roll off at 6dB per octave (20dB per decade).
3044 The filter accepts the following options:
3048 Set the filter's central frequency. Default is @code{3000}.
3051 Set method to specify band-width of filter.
3066 Specify the band-width of a filter in width_type units.
3069 How much to use filtered signal in output. Default is 1.
3070 Range is between 0 and 1.
3073 Specify which channels to filter, by default all available are filtered.
3076 Normalize biquad coefficients, by default is disabled.
3077 Enabling it will normalize magnitude response at DC to 0dB.
3080 Set transform type of IIR filter.
3089 Set precison of filtering.
3092 Pick automatic sample format depending on surround filters.
3094 Always use signed 16-bit.
3096 Always use signed 32-bit.
3098 Always use float 32-bit.
3100 Always use float 64-bit.
3104 @subsection Commands
3106 This filter supports the following commands:
3109 Change bandreject frequency.
3110 Syntax for the command is : "@var{frequency}"
3113 Change bandreject width_type.
3114 Syntax for the command is : "@var{width_type}"
3117 Change bandreject width.
3118 Syntax for the command is : "@var{width}"
3121 Change bandreject mix.
3122 Syntax for the command is : "@var{mix}"
3125 @section bass, lowshelf
3127 Boost or cut the bass (lower) frequencies of the audio using a two-pole
3128 shelving filter with a response similar to that of a standard
3129 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
3131 The filter accepts the following options:
3135 Give the gain at 0 Hz. Its useful range is about -20
3136 (for a large cut) to +20 (for a large boost).
3137 Beware of clipping when using a positive gain.
3140 Set the filter's central frequency and so can be used
3141 to extend or reduce the frequency range to be boosted or cut.
3142 The default value is @code{100} Hz.
3145 Set method to specify band-width of filter.
3160 Determine how steep is the filter's shelf transition.
3163 Set number of poles. Default is 2.
3166 How much to use filtered signal in output. Default is 1.
3167 Range is between 0 and 1.
3170 Specify which channels to filter, by default all available are filtered.
3173 Normalize biquad coefficients, by default is disabled.
3174 Enabling it will normalize magnitude response at DC to 0dB.
3177 Set transform type of IIR filter.
3186 Set precison of filtering.
3189 Pick automatic sample format depending on surround filters.
3191 Always use signed 16-bit.
3193 Always use signed 32-bit.
3195 Always use float 32-bit.
3197 Always use float 64-bit.
3201 @subsection Commands
3203 This filter supports the following commands:
3206 Change bass frequency.
3207 Syntax for the command is : "@var{frequency}"
3210 Change bass width_type.
3211 Syntax for the command is : "@var{width_type}"
3215 Syntax for the command is : "@var{width}"
3219 Syntax for the command is : "@var{gain}"
3223 Syntax for the command is : "@var{mix}"
3228 Apply a biquad IIR filter with the given coefficients.
3229 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
3230 are the numerator and denominator coefficients respectively.
3231 and @var{channels}, @var{c} specify which channels to filter, by default all
3232 available are filtered.
3234 @subsection Commands
3236 This filter supports the following commands:
3244 Change biquad parameter.
3245 Syntax for the command is : "@var{value}"
3248 How much to use filtered signal in output. Default is 1.
3249 Range is between 0 and 1.
3252 Specify which channels to filter, by default all available are filtered.
3255 Normalize biquad coefficients, by default is disabled.
3256 Enabling it will normalize magnitude response at DC to 0dB.
3259 Set transform type of IIR filter.
3268 Set precison of filtering.
3271 Pick automatic sample format depending on surround filters.
3273 Always use signed 16-bit.
3275 Always use signed 32-bit.
3277 Always use float 32-bit.
3279 Always use float 64-bit.
3284 Bauer stereo to binaural transformation, which improves headphone listening of
3285 stereo audio records.
3287 To enable compilation of this filter you need to configure FFmpeg with
3288 @code{--enable-libbs2b}.
3290 It accepts the following parameters:
3294 Pre-defined crossfeed level.
3298 Default level (fcut=700, feed=50).
3301 Chu Moy circuit (fcut=700, feed=60).
3304 Jan Meier circuit (fcut=650, feed=95).
3309 Cut frequency (in Hz).
3318 Remap input channels to new locations.
3320 It accepts the following parameters:
3323 Map channels from input to output. The argument is a '|'-separated list of
3324 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
3325 @var{in_channel} form. @var{in_channel} can be either the name of the input
3326 channel (e.g. FL for front left) or its index in the input channel layout.
3327 @var{out_channel} is the name of the output channel or its index in the output
3328 channel layout. If @var{out_channel} is not given then it is implicitly an
3329 index, starting with zero and increasing by one for each mapping.
3331 @item channel_layout
3332 The channel layout of the output stream.
3335 If no mapping is present, the filter will implicitly map input channels to
3336 output channels, preserving indices.
3338 @subsection Examples
3342 For example, assuming a 5.1+downmix input MOV file,
3344 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
3346 will create an output WAV file tagged as stereo from the downmix channels of
3350 To fix a 5.1 WAV improperly encoded in AAC's native channel order
3352 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
3356 @section channelsplit
3358 Split each channel from an input audio stream into a separate output stream.
3360 It accepts the following parameters:
3362 @item channel_layout
3363 The channel layout of the input stream. The default is "stereo".
3365 A channel layout describing the channels to be extracted as separate output streams
3366 or "all" to extract each input channel as a separate stream. The default is "all".
3368 Choosing channels not present in channel layout in the input will result in an error.
3371 @subsection Examples
3375 For example, assuming a stereo input MP3 file,
3377 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
3379 will create an output Matroska file with two audio streams, one containing only
3380 the left channel and the other the right channel.
3383 Split a 5.1 WAV file into per-channel files:
3385 ffmpeg -i in.wav -filter_complex
3386 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
3387 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
3388 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
3393 Extract only LFE from a 5.1 WAV file:
3395 ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
3396 -map '[LFE]' lfe.wav
3401 Add a chorus effect to the audio.
3403 Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
3405 Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
3406 constant, with chorus, it is varied using using sinusoidal or triangular modulation.
3407 The modulation depth defines the range the modulated delay is played before or after
3408 the delay. Hence the delayed sound will sound slower or faster, that is the delayed
3409 sound tuned around the original one, like in a chorus where some vocals are slightly
3412 It accepts the following parameters:
3415 Set input gain. Default is 0.4.
3418 Set output gain. Default is 0.4.
3421 Set delays. A typical delay is around 40ms to 60ms.
3433 @subsection Examples
3439 chorus=0.7:0.9:55:0.4:0.25:2
3445 chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
3449 Fuller sounding chorus with three delays:
3451 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
3456 Compress or expand the audio's dynamic range.
3458 It accepts the following parameters:
3464 A list of times in seconds for each channel over which the instantaneous level
3465 of the input signal is averaged to determine its volume. @var{attacks} refers to
3466 increase of volume and @var{decays} refers to decrease of volume. For most
3467 situations, the attack time (response to the audio getting louder) should be
3468 shorter than the decay time, because the human ear is more sensitive to sudden
3469 loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
3470 a typical value for decay is 0.8 seconds.
3471 If specified number of attacks & decays is lower than number of channels, the last
3472 set attack/decay will be used for all remaining channels.
3475 A list of points for the transfer function, specified in dB relative to the
3476 maximum possible signal amplitude. Each key points list must be defined using
3477 the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
3478 @code{x0/y0 x1/y1 x2/y2 ....}
3480 The input values must be in strictly increasing order but the transfer function
3481 does not have to be monotonically rising. The point @code{0/0} is assumed but
3482 may be overridden (by @code{0/out-dBn}). Typical values for the transfer
3483 function are @code{-70/-70|-60/-20|1/0}.
3486 Set the curve radius in dB for all joints. It defaults to 0.01.
3489 Set the additional gain in dB to be applied at all points on the transfer
3490 function. This allows for easy adjustment of the overall gain.
3494 Set an initial volume, in dB, to be assumed for each channel when filtering
3495 starts. This permits the user to supply a nominal level initially, so that, for
3496 example, a very large gain is not applied to initial signal levels before the
3497 companding has begun to operate. A typical value for audio which is initially
3498 quiet is -90 dB. It defaults to 0.
3501 Set a delay, in seconds. The input audio is analyzed immediately, but audio is
3502 delayed before being fed to the volume adjuster. Specifying a delay
3503 approximately equal to the attack/decay times allows the filter to effectively
3504 operate in predictive rather than reactive mode. It defaults to 0.
3508 @subsection Examples
3512 Make music with both quiet and loud passages suitable for listening to in a
3515 compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
3518 Another example for audio with whisper and explosion parts:
3520 compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
3524 A noise gate for when the noise is at a lower level than the signal:
3526 compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
3530 Here is another noise gate, this time for when the noise is at a higher level
3531 than the signal (making it, in some ways, similar to squelch):
3533 compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
3537 2:1 compression starting at -6dB:
3539 compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
3543 2:1 compression starting at -9dB:
3545 compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
3549 2:1 compression starting at -12dB:
3551 compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
3555 2:1 compression starting at -18dB:
3557 compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
3561 3:1 compression starting at -15dB:
3563 compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
3569 compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
3575 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
3579 Hard limiter at -6dB:
3581 compand=attacks=0:points=-80/-80|-6/-6|20/-6
3585 Hard limiter at -12dB:
3587 compand=attacks=0:points=-80/-80|-12/-12|20/-12
3591 Hard noise gate at -35 dB:
3593 compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
3599 compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
3603 @section compensationdelay
3605 Compensation Delay Line is a metric based delay to compensate differing
3606 positions of microphones or speakers.
3608 For example, you have recorded guitar with two microphones placed in
3609 different locations. Because the front of sound wave has fixed speed in
3610 normal conditions, the phasing of microphones can vary and depends on
3611 their location and interposition. The best sound mix can be achieved when
3612 these microphones are in phase (synchronized). Note that a distance of
3613 ~30 cm between microphones makes one microphone capture the signal in
3614 antiphase to the other microphone. That makes the final mix sound moody.
3615 This filter helps to solve phasing problems by adding different delays
3616 to each microphone track and make them synchronized.
3618 The best result can be reached when you take one track as base and
3619 synchronize other tracks one by one with it.
3620 Remember that synchronization/delay tolerance depends on sample rate, too.
3621 Higher sample rates will give more tolerance.
3623 The filter accepts the following parameters:
3627 Set millimeters distance. This is compensation distance for fine tuning.
3631 Set cm distance. This is compensation distance for tightening distance setup.
3635 Set meters distance. This is compensation distance for hard distance setup.
3639 Set dry amount. Amount of unprocessed (dry) signal.
3643 Set wet amount. Amount of processed (wet) signal.
3647 Set temperature in degrees Celsius. This is the temperature of the environment.
3652 Apply headphone crossfeed filter.
3654 Crossfeed is the process of blending the left and right channels of stereo
3656 It is mainly used to reduce extreme stereo separation of low frequencies.
3658 The intent is to produce more speaker like sound to the listener.
3660 The filter accepts the following options:
3664 Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1.
3665 This sets gain of low shelf filter for side part of stereo image.
3666 Default is -6dB. Max allowed is -30db when strength is set to 1.
3669 Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1.
3670 This sets cut off frequency of low shelf filter. Default is cut off near
3671 1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz.
3674 Set curve slope of low shelf filter. Default is 0.5.
3675 Allowed range is from 0.01 to 1.
3678 Set input gain. Default is 0.9.
3681 Set output gain. Default is 1.
3684 @subsection Commands
3686 This filter supports the all above options as @ref{commands}.
3688 @section crystalizer
3689 Simple algorithm for audio noise sharpening.
3691 This filter linearly increases differences betweeen each audio sample.
3693 The filter accepts the following options:
3697 Sets the intensity of effect (default: 2.0). Must be in range between -10.0 to 0
3698 (unchanged sound) to 10.0 (maximum effect).
3699 To inverse filtering use negative value.
3702 Enable clipping. By default is enabled.
3705 @subsection Commands
3707 This filter supports the all above options as @ref{commands}.
3710 Apply a DC shift to the audio.
3712 This can be useful to remove a DC offset (caused perhaps by a hardware problem
3713 in the recording chain) from the audio. The effect of a DC offset is reduced
3714 headroom and hence volume. The @ref{astats} filter can be used to determine if
3715 a signal has a DC offset.
3719 Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
3723 Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
3724 used to prevent clipping.
3729 Apply de-essing to the audio samples.
3733 Set intensity for triggering de-essing. Allowed range is from 0 to 1.
3737 Set amount of ducking on treble part of sound. Allowed range is from 0 to 1.
3741 How much of original frequency content to keep when de-essing. Allowed range is from 0 to 1.
3745 Set the output mode.
3747 It accepts the following values:
3750 Pass input unchanged.
3753 Pass ess filtered out.
3758 Default value is @var{o}.
3764 Measure audio dynamic range.
3766 DR values of 14 and higher is found in very dynamic material. DR of 8 to 13
3767 is found in transition material. And anything less that 8 have very poor dynamics
3768 and is very compressed.
3770 The filter accepts the following options:
3774 Set window length in seconds used to split audio into segments of equal length.
3775 Default is 3 seconds.
3779 Dynamic Audio Normalizer.
3781 This filter applies a certain amount of gain to the input audio in order
3782 to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
3783 contrast to more "simple" normalization algorithms, the Dynamic Audio
3784 Normalizer *dynamically* re-adjusts the gain factor to the input audio.
3785 This allows for applying extra gain to the "quiet" sections of the audio
3786 while avoiding distortions or clipping the "loud" sections. In other words:
3787 The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
3788 sections, in the sense that the volume of each section is brought to the
3789 same target level. Note, however, that the Dynamic Audio Normalizer achieves
3790 this goal *without* applying "dynamic range compressing". It will retain 100%
3791 of the dynamic range *within* each section of the audio file.
3795 Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
3796 Default is 500 milliseconds.
3797 The Dynamic Audio Normalizer processes the input audio in small chunks,
3798 referred to as frames. This is required, because a peak magnitude has no
3799 meaning for just a single sample value. Instead, we need to determine the
3800 peak magnitude for a contiguous sequence of sample values. While a "standard"
3801 normalizer would simply use the peak magnitude of the complete file, the
3802 Dynamic Audio Normalizer determines the peak magnitude individually for each
3803 frame. The length of a frame is specified in milliseconds. By default, the
3804 Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
3805 been found to give good results with most files.
3806 Note that the exact frame length, in number of samples, will be determined
3807 automatically, based on the sampling rate of the individual input audio file.
3810 Set the Gaussian filter window size. In range from 3 to 301, must be odd
3811 number. Default is 31.
3812 Probably the most important parameter of the Dynamic Audio Normalizer is the
3813 @code{window size} of the Gaussian smoothing filter. The filter's window size
3814 is specified in frames, centered around the current frame. For the sake of
3815 simplicity, this must be an odd number. Consequently, the default value of 31
3816 takes into account the current frame, as well as the 15 preceding frames and
3817 the 15 subsequent frames. Using a larger window results in a stronger
3818 smoothing effect and thus in less gain variation, i.e. slower gain
3819 adaptation. Conversely, using a smaller window results in a weaker smoothing
3820 effect and thus in more gain variation, i.e. faster gain adaptation.
3821 In other words, the more you increase this value, the more the Dynamic Audio
3822 Normalizer will behave like a "traditional" normalization filter. On the
3823 contrary, the more you decrease this value, the more the Dynamic Audio
3824 Normalizer will behave like a dynamic range compressor.
3827 Set the target peak value. This specifies the highest permissible magnitude
3828 level for the normalized audio input. This filter will try to approach the
3829 target peak magnitude as closely as possible, but at the same time it also
3830 makes sure that the normalized signal will never exceed the peak magnitude.
3831 A frame's maximum local gain factor is imposed directly by the target peak
3832 magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
3833 It is not recommended to go above this value.
3836 Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
3837 The Dynamic Audio Normalizer determines the maximum possible (local) gain
3838 factor for each input frame, i.e. the maximum gain factor that does not
3839 result in clipping or distortion. The maximum gain factor is determined by
3840 the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
3841 additionally bounds the frame's maximum gain factor by a predetermined
3842 (global) maximum gain factor. This is done in order to avoid excessive gain
3843 factors in "silent" or almost silent frames. By default, the maximum gain
3844 factor is 10.0, For most inputs the default value should be sufficient and
3845 it usually is not recommended to increase this value. Though, for input
3846 with an extremely low overall volume level, it may be necessary to allow even
3847 higher gain factors. Note, however, that the Dynamic Audio Normalizer does
3848 not simply apply a "hard" threshold (i.e. cut off values above the threshold).
3849 Instead, a "sigmoid" threshold function will be applied. This way, the
3850 gain factors will smoothly approach the threshold value, but never exceed that
3854 Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
3855 By default, the Dynamic Audio Normalizer performs "peak" normalization.
3856 This means that the maximum local gain factor for each frame is defined
3857 (only) by the frame's highest magnitude sample. This way, the samples can
3858 be amplified as much as possible without exceeding the maximum signal
3859 level, i.e. without clipping. Optionally, however, the Dynamic Audio
3860 Normalizer can also take into account the frame's root mean square,
3861 abbreviated RMS. In electrical engineering, the RMS is commonly used to
3862 determine the power of a time-varying signal. It is therefore considered
3863 that the RMS is a better approximation of the "perceived loudness" than
3864 just looking at the signal's peak magnitude. Consequently, by adjusting all
3865 frames to a constant RMS value, a uniform "perceived loudness" can be
3866 established. If a target RMS value has been specified, a frame's local gain
3867 factor is defined as the factor that would result in exactly that RMS value.
3868 Note, however, that the maximum local gain factor is still restricted by the
3869 frame's highest magnitude sample, in order to prevent clipping.
3872 Enable channels coupling. By default is enabled.
3873 By default, the Dynamic Audio Normalizer will amplify all channels by the same
3874 amount. This means the same gain factor will be applied to all channels, i.e.
3875 the maximum possible gain factor is determined by the "loudest" channel.
3876 However, in some recordings, it may happen that the volume of the different
3877 channels is uneven, e.g. one channel may be "quieter" than the other one(s).
3878 In this case, this option can be used to disable the channel coupling. This way,
3879 the gain factor will be determined independently for each channel, depending
3880 only on the individual channel's highest magnitude sample. This allows for
3881 harmonizing the volume of the different channels.
3884 Enable DC bias correction. By default is disabled.
3885 An audio signal (in the time domain) is a sequence of sample values.
3886 In the Dynamic Audio Normalizer these sample values are represented in the
3887 -1.0 to 1.0 range, regardless of the original input format. Normally, the
3888 audio signal, or "waveform", should be centered around the zero point.
3889 That means if we calculate the mean value of all samples in a file, or in a
3890 single frame, then the result should be 0.0 or at least very close to that
3891 value. If, however, there is a significant deviation of the mean value from
3892 0.0, in either positive or negative direction, this is referred to as a
3893 DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
3894 Audio Normalizer provides optional DC bias correction.
3895 With DC bias correction enabled, the Dynamic Audio Normalizer will determine
3896 the mean value, or "DC correction" offset, of each input frame and subtract
3897 that value from all of the frame's sample values which ensures those samples
3898 are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
3899 boundaries, the DC correction offset values will be interpolated smoothly
3900 between neighbouring frames.
3902 @item altboundary, b
3903 Enable alternative boundary mode. By default is disabled.
3904 The Dynamic Audio Normalizer takes into account a certain neighbourhood
3905 around each frame. This includes the preceding frames as well as the
3906 subsequent frames. However, for the "boundary" frames, located at the very
3907 beginning and at the very end of the audio file, not all neighbouring
3908 frames are available. In particular, for the first few frames in the audio
3909 file, the preceding frames are not known. And, similarly, for the last few
3910 frames in the audio file, the subsequent frames are not known. Thus, the
3911 question arises which gain factors should be assumed for the missing frames
3912 in the "boundary" region. The Dynamic Audio Normalizer implements two modes
3913 to deal with this situation. The default boundary mode assumes a gain factor
3914 of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
3915 "fade out" at the beginning and at the end of the input, respectively.
3918 Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
3919 By default, the Dynamic Audio Normalizer does not apply "traditional"
3920 compression. This means that signal peaks will not be pruned and thus the
3921 full dynamic range will be retained within each local neighbourhood. However,
3922 in some cases it may be desirable to combine the Dynamic Audio Normalizer's
3923 normalization algorithm with a more "traditional" compression.
3924 For this purpose, the Dynamic Audio Normalizer provides an optional compression
3925 (thresholding) function. If (and only if) the compression feature is enabled,
3926 all input frames will be processed by a soft knee thresholding function prior
3927 to the actual normalization process. Put simply, the thresholding function is
3928 going to prune all samples whose magnitude exceeds a certain threshold value.
3929 However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
3930 value. Instead, the threshold value will be adjusted for each individual
3932 In general, smaller parameters result in stronger compression, and vice versa.
3933 Values below 3.0 are not recommended, because audible distortion may appear.
3936 Set the target threshold value. This specifies the lowest permissible
3937 magnitude level for the audio input which will be normalized.
3938 If input frame volume is above this value frame will be normalized.
3939 Otherwise frame may not be normalized at all. The default value is set
3940 to 0, which means all input frames will be normalized.
3941 This option is mostly useful if digital noise is not wanted to be amplified.
3944 @subsection Commands
3946 This filter supports the all above options as @ref{commands}.
3950 Make audio easier to listen to on headphones.
3952 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
3953 so that when listened to on headphones the stereo image is moved from
3954 inside your head (standard for headphones) to outside and in front of
3955 the listener (standard for speakers).
3961 Apply a two-pole peaking equalisation (EQ) filter. With this
3962 filter, the signal-level at and around a selected frequency can
3963 be increased or decreased, whilst (unlike bandpass and bandreject
3964 filters) that at all other frequencies is unchanged.
3966 In order to produce complex equalisation curves, this filter can
3967 be given several times, each with a different central frequency.
3969 The filter accepts the following options:
3973 Set the filter's central frequency in Hz.
3976 Set method to specify band-width of filter.
3991 Specify the band-width of a filter in width_type units.
3994 Set the required gain or attenuation in dB.
3995 Beware of clipping when using a positive gain.
3998 How much to use filtered signal in output. Default is 1.
3999 Range is between 0 and 1.
4002 Specify which channels to filter, by default all available are filtered.
4005 Normalize biquad coefficients, by default is disabled.
4006 Enabling it will normalize magnitude response at DC to 0dB.
4009 Set transform type of IIR filter.
4018 Set precison of filtering.
4021 Pick automatic sample format depending on surround filters.
4023 Always use signed 16-bit.
4025 Always use signed 32-bit.
4027 Always use float 32-bit.
4029 Always use float 64-bit.
4033 @subsection Examples
4036 Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
4038 equalizer=f=1000:t=h:width=200:g=-10
4042 Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
4044 equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
4048 @subsection Commands
4050 This filter supports the following commands:
4053 Change equalizer frequency.
4054 Syntax for the command is : "@var{frequency}"
4057 Change equalizer width_type.
4058 Syntax for the command is : "@var{width_type}"
4061 Change equalizer width.
4062 Syntax for the command is : "@var{width}"
4065 Change equalizer gain.
4066 Syntax for the command is : "@var{gain}"
4069 Change equalizer mix.
4070 Syntax for the command is : "@var{mix}"
4073 @section extrastereo
4075 Linearly increases the difference between left and right channels which
4076 adds some sort of "live" effect to playback.
4078 The filter accepts the following options:
4082 Sets the difference coefficient (default: 2.5). 0.0 means mono sound
4083 (average of both channels), with 1.0 sound will be unchanged, with
4084 -1.0 left and right channels will be swapped.
4087 Enable clipping. By default is enabled.
4090 @subsection Commands
4092 This filter supports the all above options as @ref{commands}.
4094 @section firequalizer
4095 Apply FIR Equalization using arbitrary frequency response.
4097 The filter accepts the following option:
4101 Set gain curve equation (in dB). The expression can contain variables:
4104 the evaluated frequency
4108 channel number, set to 0 when multichannels evaluation is disabled
4110 channel id, see libavutil/channel_layout.h, set to the first channel id when
4111 multichannels evaluation is disabled
4115 channel_layout, see libavutil/channel_layout.h
4120 @item gain_interpolate(f)
4121 interpolate gain on frequency f based on gain_entry
4122 @item cubic_interpolate(f)
4123 same as gain_interpolate, but smoother
4125 This option is also available as command. Default is @code{gain_interpolate(f)}.
4128 Set gain entry for gain_interpolate function. The expression can
4132 store gain entry at frequency f with value g
4134 This option is also available as command.
4137 Set filter delay in seconds. Higher value means more accurate.
4138 Default is @code{0.01}.
4141 Set filter accuracy in Hz. Lower value means more accurate.
4142 Default is @code{5}.
4145 Set window function. Acceptable values are:
4148 rectangular window, useful when gain curve is already smooth
4150 hann window (default)
4156 3-terms continuous 1st derivative nuttall window
4158 minimum 3-terms discontinuous nuttall window
4160 4-terms continuous 1st derivative nuttall window
4162 minimum 4-terms discontinuous nuttall (blackman-nuttall) window
4164 blackman-harris window
4170 If enabled, use fixed number of audio samples. This improves speed when
4171 filtering with large delay. Default is disabled.
4174 Enable multichannels evaluation on gain. Default is disabled.
4177 Enable zero phase mode by subtracting timestamp to compensate delay.
4178 Default is disabled.
4181 Set scale used by gain. Acceptable values are:
4184 linear frequency, linear gain
4186 linear frequency, logarithmic (in dB) gain (default)
4188 logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain
4190 logarithmic frequency, logarithmic gain
4194 Set file for dumping, suitable for gnuplot.
4197 Set scale for dumpfile. Acceptable values are same with scale option.
4201 Enable 2-channel convolution using complex FFT. This improves speed significantly.
4202 Default is disabled.
4205 Enable minimum phase impulse response. Default is disabled.
4208 @subsection Examples
4213 firequalizer=gain='if(lt(f,1000), 0, -INF)'
4216 lowpass at 1000 Hz with gain_entry:
4218 firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
4221 custom equalization:
4223 firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
4226 higher delay with zero phase to compensate delay:
4228 firequalizer=delay=0.1:fixed=on:zero_phase=on
4231 lowpass on left channel, highpass on right channel:
4233 firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
4234 :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
4239 Apply a flanging effect to the audio.
4241 The filter accepts the following options:
4245 Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
4248 Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2.
4251 Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
4255 Set percentage of delayed signal mixed with original. Range from 0 to 100.
4256 Default value is 71.
4259 Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
4262 Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
4263 Default value is @var{sinusoidal}.
4266 Set swept wave percentage-shift for multi channel. Range from 0 to 100.
4267 Default value is 25.
4270 Set delay-line interpolation, @var{linear} or @var{quadratic}.
4271 Default is @var{linear}.
4275 Apply Haas effect to audio.
4277 Note that this makes most sense to apply on mono signals.
4278 With this filter applied to mono signals it give some directionality and
4279 stretches its stereo image.
4281 The filter accepts the following options:
4285 Set input level. By default is @var{1}, or 0dB
4288 Set output level. By default is @var{1}, or 0dB.
4291 Set gain applied to side part of signal. By default is @var{1}.
4294 Set kind of middle source. Can be one of the following:
4304 Pick middle part signal of stereo image.
4307 Pick side part signal of stereo image.
4311 Change middle phase. By default is disabled.
4314 Set left channel delay. By default is @var{2.05} milliseconds.
4317 Set left channel balance. By default is @var{-1}.
4320 Set left channel gain. By default is @var{1}.
4323 Change left phase. By default is disabled.
4326 Set right channel delay. By defaults is @var{2.12} milliseconds.
4329 Set right channel balance. By default is @var{1}.
4332 Set right channel gain. By default is @var{1}.
4335 Change right phase. By default is enabled.
4340 Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
4341 embedded HDCD codes is expanded into a 20-bit PCM stream.
4343 The filter supports the Peak Extend and Low-level Gain Adjustment features
4344 of HDCD, and detects the Transient Filter flag.
4347 ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
4350 When using the filter with wav, note the default encoding for wav is 16-bit,
4351 so the resulting 20-bit stream will be truncated back to 16-bit. Use something
4352 like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
4354 ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
4355 ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
4358 The filter accepts the following options:
4361 @item disable_autoconvert
4362 Disable any automatic format conversion or resampling in the filter graph.
4364 @item process_stereo
4365 Process the stereo channels together. If target_gain does not match between
4366 channels, consider it invalid and use the last valid target_gain.
4369 Set the code detect timer period in ms.
4372 Always extend peaks above -3dBFS even if PE isn't signaled.
4375 Replace audio with a solid tone and adjust the amplitude to signal some
4376 specific aspect of the decoding process. The output file can be loaded in
4377 an audio editor alongside the original to aid analysis.
4379 @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
4386 Gain adjustment level at each sample
4388 Samples where peak extend occurs
4390 Samples where the code detect timer is active
4392 Samples where the target gain does not match between channels
4398 Apply head-related transfer functions (HRTFs) to create virtual
4399 loudspeakers around the user for binaural listening via headphones.
4400 The HRIRs are provided via additional streams, for each channel
4401 one stereo input stream is needed.
4403 The filter accepts the following options:
4407 Set mapping of input streams for convolution.
4408 The argument is a '|'-separated list of channel names in order as they
4409 are given as additional stream inputs for filter.
4410 This also specify number of input streams. Number of input streams
4411 must be not less than number of channels in first stream plus one.
4414 Set gain applied to audio. Value is in dB. Default is 0.
4417 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
4418 processing audio in time domain which is slow.
4419 @var{freq} is processing audio in frequency domain which is fast.
4420 Default is @var{freq}.
4423 Set custom gain for LFE channels. Value is in dB. Default is 0.
4426 Set size of frame in number of samples which will be processed at once.
4427 Default value is @var{1024}. Allowed range is from 1024 to 96000.
4430 Set format of hrir stream.
4431 Default value is @var{stereo}. Alternative value is @var{multich}.
4432 If value is set to @var{stereo}, number of additional streams should
4433 be greater or equal to number of input channels in first input stream.
4434 Also each additional stream should have stereo number of channels.
4435 If value is set to @var{multich}, number of additional streams should
4436 be exactly one. Also number of input channels of additional stream
4437 should be equal or greater than twice number of channels of first input
4441 @subsection Examples
4445 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
4446 each amovie filter use stereo file with IR coefficients as input.
4447 The files give coefficients for each position of virtual loudspeaker:
4450 -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"
4455 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
4456 but now in @var{multich} @var{hrir} format.
4458 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"
4465 Apply a high-pass filter with 3dB point frequency.
4466 The filter can be either single-pole, or double-pole (the default).
4467 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
4469 The filter accepts the following options:
4473 Set frequency in Hz. Default is 3000.
4476 Set number of poles. Default is 2.
4479 Set method to specify band-width of filter.
4494 Specify the band-width of a filter in width_type units.
4495 Applies only to double-pole filter.
4496 The default is 0.707q and gives a Butterworth response.
4499 How much to use filtered signal in output. Default is 1.
4500 Range is between 0 and 1.
4503 Specify which channels to filter, by default all available are filtered.
4506 Normalize biquad coefficients, by default is disabled.
4507 Enabling it will normalize magnitude response at DC to 0dB.
4510 Set transform type of IIR filter.
4519 Set precison of filtering.
4522 Pick automatic sample format depending on surround filters.
4524 Always use signed 16-bit.
4526 Always use signed 32-bit.
4528 Always use float 32-bit.
4530 Always use float 64-bit.
4534 @subsection Commands
4536 This filter supports the following commands:
4539 Change highpass frequency.
4540 Syntax for the command is : "@var{frequency}"
4543 Change highpass width_type.
4544 Syntax for the command is : "@var{width_type}"
4547 Change highpass width.
4548 Syntax for the command is : "@var{width}"
4551 Change highpass mix.
4552 Syntax for the command is : "@var{mix}"
4557 Join multiple input streams into one multi-channel stream.
4559 It accepts the following parameters:
4563 The number of input streams. It defaults to 2.
4565 @item channel_layout
4566 The desired output channel layout. It defaults to stereo.
4569 Map channels from inputs to output. The argument is a '|'-separated list of
4570 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
4571 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
4572 can be either the name of the input channel (e.g. FL for front left) or its
4573 index in the specified input stream. @var{out_channel} is the name of the output
4577 The filter will attempt to guess the mappings when they are not specified
4578 explicitly. It does so by first trying to find an unused matching input channel
4579 and if that fails it picks the first unused input channel.
4581 Join 3 inputs (with properly set channel layouts):
4583 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
4586 Build a 5.1 output from 6 single-channel streams:
4588 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
4589 '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'
4595 Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
4597 To enable compilation of this filter you need to configure FFmpeg with
4598 @code{--enable-ladspa}.
4602 Specifies the name of LADSPA plugin library to load. If the environment
4603 variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
4604 each one of the directories specified by the colon separated list in
4605 @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
4606 this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
4607 @file{/usr/lib/ladspa/}.
4610 Specifies the plugin within the library. Some libraries contain only
4611 one plugin, but others contain many of them. If this is not set filter
4612 will list all available plugins within the specified library.
4615 Set the '|' separated list of controls which are zero or more floating point
4616 values that determine the behavior of the loaded plugin (for example delay,
4618 Controls need to be defined using the following syntax:
4619 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
4620 @var{valuei} is the value set on the @var{i}-th control.
4621 Alternatively they can be also defined using the following syntax:
4622 @var{value0}|@var{value1}|@var{value2}|..., where
4623 @var{valuei} is the value set on the @var{i}-th control.
4624 If @option{controls} is set to @code{help}, all available controls and
4625 their valid ranges are printed.
4627 @item sample_rate, s
4628 Specify the sample rate, default to 44100. Only used if plugin have
4632 Set the number of samples per channel per each output frame, default
4633 is 1024. Only used if plugin have zero inputs.
4636 Set the minimum duration of the sourced audio. See
4637 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4638 for the accepted syntax.
4639 Note that the resulting duration may be greater than the specified duration,
4640 as the generated audio is always cut at the end of a complete frame.
4641 If not specified, or the expressed duration is negative, the audio is
4642 supposed to be generated forever.
4643 Only used if plugin have zero inputs.
4646 Enable latency compensation, by default is disabled.
4647 Only used if plugin have inputs.
4650 @subsection Examples
4654 List all available plugins within amp (LADSPA example plugin) library:
4660 List all available controls and their valid ranges for @code{vcf_notch}
4661 plugin from @code{VCF} library:
4663 ladspa=f=vcf:p=vcf_notch:c=help
4667 Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
4670 ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
4674 Add reverberation to the audio using TAP-plugins
4675 (Tom's Audio Processing plugins):
4677 ladspa=file=tap_reverb:tap_reverb
4681 Generate white noise, with 0.2 amplitude:
4683 ladspa=file=cmt:noise_source_white:c=c0=.2
4687 Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
4688 @code{C* Audio Plugin Suite} (CAPS) library:
4690 ladspa=file=caps:Click:c=c1=20'
4694 Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
4696 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
4700 Increase volume by 20dB using fast lookahead limiter from Steve Harris
4701 @code{SWH Plugins} collection:
4703 ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
4707 Attenuate low frequencies using Multiband EQ from Steve Harris
4708 @code{SWH Plugins} collection:
4710 ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
4714 Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite}
4717 ladspa=caps:Narrower
4721 Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library:
4723 ladspa=caps:White:.2
4727 Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library:
4729 ladspa=caps:Fractal:c=c1=1
4733 Dynamic volume normalization using @code{VLevel} plugin:
4735 ladspa=vlevel-ladspa:vlevel_mono
4739 @subsection Commands
4741 This filter supports the following commands:
4744 Modify the @var{N}-th control value.
4746 If the specified value is not valid, it is ignored and prior one is kept.
4751 EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
4752 Support for both single pass (livestreams, files) and double pass (files) modes.
4753 This algorithm can target IL, LRA, and maximum true peak. In dynamic mode, to accurately
4754 detect true peaks, the audio stream will be upsampled to 192 kHz.
4755 Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate.
4757 The filter accepts the following options:
4761 Set integrated loudness target.
4762 Range is -70.0 - -5.0. Default value is -24.0.
4765 Set loudness range target.
4766 Range is 1.0 - 20.0. Default value is 7.0.
4769 Set maximum true peak.
4770 Range is -9.0 - +0.0. Default value is -2.0.
4772 @item measured_I, measured_i
4773 Measured IL of input file.
4774 Range is -99.0 - +0.0.
4776 @item measured_LRA, measured_lra
4777 Measured LRA of input file.
4778 Range is 0.0 - 99.0.
4780 @item measured_TP, measured_tp
4781 Measured true peak of input file.
4782 Range is -99.0 - +99.0.
4784 @item measured_thresh
4785 Measured threshold of input file.
4786 Range is -99.0 - +0.0.
4789 Set offset gain. Gain is applied before the true-peak limiter.
4790 Range is -99.0 - +99.0. Default is +0.0.
4793 Normalize by linearly scaling the source audio.
4794 @code{measured_I}, @code{measured_LRA}, @code{measured_TP},
4795 and @code{measured_thresh} must all be specified. Target LRA shouldn't
4796 be lower than source LRA and the change in integrated loudness shouldn't
4797 result in a true peak which exceeds the target TP. If any of these
4798 conditions aren't met, normalization mode will revert to @var{dynamic}.
4799 Options are @code{true} or @code{false}. Default is @code{true}.
4802 Treat mono input files as "dual-mono". If a mono file is intended for playback
4803 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
4804 If set to @code{true}, this option will compensate for this effect.
4805 Multi-channel input files are not affected by this option.
4806 Options are true or false. Default is false.
4809 Set print format for stats. Options are summary, json, or none.
4810 Default value is none.
4815 Apply a low-pass filter with 3dB point frequency.
4816 The filter can be either single-pole or double-pole (the default).
4817 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
4819 The filter accepts the following options:
4823 Set frequency in Hz. Default is 500.
4826 Set number of poles. Default is 2.
4829 Set method to specify band-width of filter.
4844 Specify the band-width of a filter in width_type units.
4845 Applies only to double-pole filter.
4846 The default is 0.707q and gives a Butterworth response.
4849 How much to use filtered signal in output. Default is 1.
4850 Range is between 0 and 1.
4853 Specify which channels to filter, by default all available are filtered.
4856 Normalize biquad coefficients, by default is disabled.
4857 Enabling it will normalize magnitude response at DC to 0dB.
4860 Set transform type of IIR filter.
4869 Set precison of filtering.
4872 Pick automatic sample format depending on surround filters.
4874 Always use signed 16-bit.
4876 Always use signed 32-bit.
4878 Always use float 32-bit.
4880 Always use float 64-bit.
4884 @subsection Examples
4887 Lowpass only LFE channel, it LFE is not present it does nothing:
4893 @subsection Commands
4895 This filter supports the following commands:
4898 Change lowpass frequency.
4899 Syntax for the command is : "@var{frequency}"
4902 Change lowpass width_type.
4903 Syntax for the command is : "@var{width_type}"
4906 Change lowpass width.
4907 Syntax for the command is : "@var{width}"
4911 Syntax for the command is : "@var{mix}"
4916 Load a LV2 (LADSPA Version 2) plugin.
4918 To enable compilation of this filter you need to configure FFmpeg with
4919 @code{--enable-lv2}.
4923 Specifies the plugin URI. You may need to escape ':'.
4926 Set the '|' separated list of controls which are zero or more floating point
4927 values that determine the behavior of the loaded plugin (for example delay,
4929 If @option{controls} is set to @code{help}, all available controls and
4930 their valid ranges are printed.
4932 @item sample_rate, s
4933 Specify the sample rate, default to 44100. Only used if plugin have
4937 Set the number of samples per channel per each output frame, default
4938 is 1024. Only used if plugin have zero inputs.
4941 Set the minimum duration of the sourced audio. See
4942 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4943 for the accepted syntax.
4944 Note that the resulting duration may be greater than the specified duration,
4945 as the generated audio is always cut at the end of a complete frame.
4946 If not specified, or the expressed duration is negative, the audio is
4947 supposed to be generated forever.
4948 Only used if plugin have zero inputs.
4951 @subsection Examples
4955 Apply bass enhancer plugin from Calf:
4957 lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
4961 Apply vinyl plugin from Calf:
4963 lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
4967 Apply bit crusher plugin from ArtyFX:
4969 lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
4974 Multiband Compress or expand the audio's dynamic range.
4976 The input audio is divided into bands using 4th order Linkwitz-Riley IIRs.
4977 This is akin to the crossover of a loudspeaker, and results in flat frequency
4978 response when absent compander action.
4980 It accepts the following parameters:
4984 This option syntax is:
4985 attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ...
4986 For explanation of each item refer to compand filter documentation.
4992 Mix channels with specific gain levels. The filter accepts the output
4993 channel layout followed by a set of channels definitions.
4995 This filter is also designed to efficiently remap the channels of an audio
4998 The filter accepts parameters of the form:
4999 "@var{l}|@var{outdef}|@var{outdef}|..."
5003 output channel layout or number of channels
5006 output channel specification, of the form:
5007 "@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]"
5010 output channel to define, either a channel name (FL, FR, etc.) or a channel
5011 number (c0, c1, etc.)
5014 multiplicative coefficient for the channel, 1 leaving the volume unchanged
5017 input channel to use, see out_name for details; it is not possible to mix
5018 named and numbered input channels
5021 If the `=' in a channel specification is replaced by `<', then the gains for
5022 that specification will be renormalized so that the total is 1, thus
5023 avoiding clipping noise.
5025 @subsection Mixing examples
5027 For example, if you want to down-mix from stereo to mono, but with a bigger
5028 factor for the left channel:
5030 pan=1c|c0=0.9*c0+0.1*c1
5033 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
5034 7-channels surround:
5036 pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
5039 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
5040 that should be preferred (see "-ac" option) unless you have very specific
5043 @subsection Remapping examples
5045 The channel remapping will be effective if, and only if:
5048 @item gain coefficients are zeroes or ones,
5049 @item only one input per channel output,
5052 If all these conditions are satisfied, the filter will notify the user ("Pure
5053 channel mapping detected"), and use an optimized and lossless method to do the
5056 For example, if you have a 5.1 source and want a stereo audio stream by
5057 dropping the extra channels:
5059 pan="stereo| c0=FL | c1=FR"
5062 Given the same source, you can also switch front left and front right channels
5063 and keep the input channel layout:
5065 pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
5068 If the input is a stereo audio stream, you can mute the front left channel (and
5069 still keep the stereo channel layout) with:
5074 Still with a stereo audio stream input, you can copy the right channel in both
5075 front left and right:
5077 pan="stereo| c0=FR | c1=FR"
5082 ReplayGain scanner filter. This filter takes an audio stream as an input and
5083 outputs it unchanged.
5084 At end of filtering it displays @code{track_gain} and @code{track_peak}.
5088 Convert the audio sample format, sample rate and channel layout. It is
5089 not meant to be used directly.
5092 Apply time-stretching and pitch-shifting with librubberband.
5094 To enable compilation of this filter, you need to configure FFmpeg with
5095 @code{--enable-librubberband}.
5097 The filter accepts the following options:
5101 Set tempo scale factor.
5104 Set pitch scale factor.
5107 Set transients detector.
5108 Possible values are:
5117 Possible values are:
5126 Possible values are:
5133 Set processing window size.
5134 Possible values are:
5143 Possible values are:
5150 Enable formant preservation when shift pitching.
5151 Possible values are:
5159 Possible values are:
5168 Possible values are:
5175 @subsection Commands
5177 This filter supports the following commands:
5180 Change filter tempo scale factor.
5181 Syntax for the command is : "@var{tempo}"
5184 Change filter pitch scale factor.
5185 Syntax for the command is : "@var{pitch}"
5188 @section sidechaincompress
5190 This filter acts like normal compressor but has the ability to compress
5191 detected signal using second input signal.
5192 It needs two input streams and returns one output stream.
5193 First input stream will be processed depending on second stream signal.
5194 The filtered signal then can be filtered with other filters in later stages of
5195 processing. See @ref{pan} and @ref{amerge} filter.
5197 The filter accepts the following options:
5201 Set input gain. Default is 1. Range is between 0.015625 and 64.
5204 Set mode of compressor operation. Can be @code{upward} or @code{downward}.
5205 Default is @code{downward}.
5208 If a signal of second stream raises above this level it will affect the gain
5209 reduction of first stream.
5210 By default is 0.125. Range is between 0.00097563 and 1.
5213 Set a ratio about which the signal is reduced. 1:2 means that if the level
5214 raised 4dB above the threshold, it will be only 2dB above after the reduction.
5215 Default is 2. Range is between 1 and 20.
5218 Amount of milliseconds the signal has to rise above the threshold before gain
5219 reduction starts. Default is 20. Range is between 0.01 and 2000.
5222 Amount of milliseconds the signal has to fall below the threshold before
5223 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
5226 Set the amount by how much signal will be amplified after processing.
5227 Default is 1. Range is from 1 to 64.
5230 Curve the sharp knee around the threshold to enter gain reduction more softly.
5231 Default is 2.82843. Range is between 1 and 8.
5234 Choose if the @code{average} level between all channels of side-chain stream
5235 or the louder(@code{maximum}) channel of side-chain stream affects the
5236 reduction. Default is @code{average}.
5239 Should the exact signal be taken in case of @code{peak} or an RMS one in case
5240 of @code{rms}. Default is @code{rms} which is mainly smoother.
5243 Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
5246 How much to use compressed signal in output. Default is 1.
5247 Range is between 0 and 1.
5250 @subsection Commands
5252 This filter supports the all above options as @ref{commands}.
5254 @subsection Examples
5258 Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
5259 depending on the signal of 2nd input and later compressed signal to be
5260 merged with 2nd input:
5262 ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
5266 @section sidechaingate
5268 A sidechain gate acts like a normal (wideband) gate but has the ability to
5269 filter the detected signal before sending it to the gain reduction stage.
5270 Normally a gate uses the full range signal to detect a level above the
5272 For example: If you cut all lower frequencies from your sidechain signal
5273 the gate will decrease the volume of your track only if not enough highs
5274 appear. With this technique you are able to reduce the resonation of a
5275 natural drum or remove "rumbling" of muted strokes from a heavily distorted
5277 It needs two input streams and returns one output stream.
5278 First input stream will be processed depending on second stream signal.
5280 The filter accepts the following options:
5284 Set input level before filtering.
5285 Default is 1. Allowed range is from 0.015625 to 64.
5288 Set the mode of operation. Can be @code{upward} or @code{downward}.
5289 Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
5290 will be amplified, expanding dynamic range in upward direction.
5291 Otherwise, in case of @code{downward} lower parts of signal will be reduced.
5294 Set the level of gain reduction when the signal is below the threshold.
5295 Default is 0.06125. Allowed range is from 0 to 1.
5296 Setting this to 0 disables reduction and then filter behaves like expander.
5299 If a signal rises above this level the gain reduction is released.
5300 Default is 0.125. Allowed range is from 0 to 1.
5303 Set a ratio about which the signal is reduced.
5304 Default is 2. Allowed range is from 1 to 9000.
5307 Amount of milliseconds the signal has to rise above the threshold before gain
5309 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
5312 Amount of milliseconds the signal has to fall below the threshold before the
5313 reduction is increased again. Default is 250 milliseconds.
5314 Allowed range is from 0.01 to 9000.
5317 Set amount of amplification of signal after processing.
5318 Default is 1. Allowed range is from 1 to 64.
5321 Curve the sharp knee around the threshold to enter gain reduction more softly.
5322 Default is 2.828427125. Allowed range is from 1 to 8.
5325 Choose if exact signal should be taken for detection or an RMS like one.
5326 Default is rms. Can be peak or rms.
5329 Choose if the average level between all channels or the louder channel affects
5331 Default is average. Can be average or maximum.
5334 Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
5337 @subsection Commands
5339 This filter supports the all above options as @ref{commands}.
5341 @section silencedetect
5343 Detect silence in an audio stream.
5345 This filter logs a message when it detects that the input audio volume is less
5346 or equal to a noise tolerance value for a duration greater or equal to the
5347 minimum detected noise duration.
5349 The printed times and duration are expressed in seconds. The
5350 @code{lavfi.silence_start} or @code{lavfi.silence_start.X} metadata key
5351 is set on the first frame whose timestamp equals or exceeds the detection
5352 duration and it contains the timestamp of the first frame of the silence.
5354 The @code{lavfi.silence_duration} or @code{lavfi.silence_duration.X}
5355 and @code{lavfi.silence_end} or @code{lavfi.silence_end.X} metadata
5356 keys are set on the first frame after the silence. If @option{mono} is
5357 enabled, and each channel is evaluated separately, the @code{.X}
5358 suffixed keys are used, and @code{X} corresponds to the channel number.
5360 The filter accepts the following options:
5364 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
5365 specified value) or amplitude ratio. Default is -60dB, or 0.001.
5368 Set silence duration until notification (default is 2 seconds). See
5369 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5370 for the accepted syntax.
5373 Process each channel separately, instead of combined. By default is disabled.
5376 @subsection Examples
5380 Detect 5 seconds of silence with -50dB noise tolerance:
5382 silencedetect=n=-50dB:d=5
5386 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
5387 tolerance in @file{silence.mp3}:
5389 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
5393 @section silenceremove
5395 Remove silence from the beginning, middle or end of the audio.
5397 The filter accepts the following options:
5401 This value is used to indicate if audio should be trimmed at beginning of
5402 the audio. A value of zero indicates no silence should be trimmed from the
5403 beginning. When specifying a non-zero value, it trims audio up until it
5404 finds non-silence. Normally, when trimming silence from beginning of audio
5405 the @var{start_periods} will be @code{1} but it can be increased to higher
5406 values to trim all audio up to specific count of non-silence periods.
5407 Default value is @code{0}.
5409 @item start_duration
5410 Specify the amount of time that non-silence must be detected before it stops
5411 trimming audio. By increasing the duration, bursts of noises can be treated
5412 as silence and trimmed off. Default value is @code{0}.
5414 @item start_threshold
5415 This indicates what sample value should be treated as silence. For digital
5416 audio, a value of @code{0} may be fine but for audio recorded from analog,
5417 you may wish to increase the value to account for background noise.
5418 Can be specified in dB (in case "dB" is appended to the specified value)
5419 or amplitude ratio. Default value is @code{0}.
5422 Specify max duration of silence at beginning that will be kept after
5423 trimming. Default is 0, which is equal to trimming all samples detected
5427 Specify mode of detection of silence end in start of multi-channel audio.
5428 Can be @var{any} or @var{all}. Default is @var{any}.
5429 With @var{any}, any sample that is detected as non-silence will cause
5430 stopped trimming of silence.
5431 With @var{all}, only if all channels are detected as non-silence will cause
5432 stopped trimming of silence.
5435 Set the count for trimming silence from the end of audio.
5436 To remove silence from the middle of a file, specify a @var{stop_periods}
5437 that is negative. This value is then treated as a positive value and is
5438 used to indicate the effect should restart processing as specified by
5439 @var{start_periods}, making it suitable for removing periods of silence
5440 in the middle of the audio.
5441 Default value is @code{0}.
5444 Specify a duration of silence that must exist before audio is not copied any
5445 more. By specifying a higher duration, silence that is wanted can be left in
5447 Default value is @code{0}.
5449 @item stop_threshold
5450 This is the same as @option{start_threshold} but for trimming silence from
5452 Can be specified in dB (in case "dB" is appended to the specified value)
5453 or amplitude ratio. Default value is @code{0}.
5456 Specify max duration of silence at end that will be kept after
5457 trimming. Default is 0, which is equal to trimming all samples detected
5461 Specify mode of detection of silence start in end of multi-channel audio.
5462 Can be @var{any} or @var{all}. Default is @var{any}.
5463 With @var{any}, any sample that is detected as non-silence will cause
5464 stopped trimming of silence.
5465 With @var{all}, only if all channels are detected as non-silence will cause
5466 stopped trimming of silence.
5469 Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
5470 and works better with digital silence which is exactly 0.
5471 Default value is @code{rms}.
5474 Set duration in number of seconds used to calculate size of window in number
5475 of samples for detecting silence.
5476 Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
5479 @subsection Examples
5483 The following example shows how this filter can be used to start a recording
5484 that does not contain the delay at the start which usually occurs between
5485 pressing the record button and the start of the performance:
5487 silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
5491 Trim all silence encountered from beginning to end where there is more than 1
5492 second of silence in audio:
5494 silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
5498 Trim all digital silence samples, using peak detection, from beginning to end
5499 where there is more than 0 samples of digital silence in audio and digital
5500 silence is detected in all channels at same positions in stream:
5502 silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0
5508 SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
5509 loudspeakers around the user for binaural listening via headphones (audio
5510 formats up to 9 channels supported).
5511 The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
5512 SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
5513 Austrian Academy of Sciences.
5515 To enable compilation of this filter you need to configure FFmpeg with
5516 @code{--enable-libmysofa}.
5518 The filter accepts the following options:
5522 Set the SOFA file used for rendering.
5525 Set gain applied to audio. Value is in dB. Default is 0.
5528 Set rotation of virtual loudspeakers in deg. Default is 0.
5531 Set elevation of virtual speakers in deg. Default is 0.
5534 Set distance in meters between loudspeakers and the listener with near-field
5535 HRTFs. Default is 1.
5538 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
5539 processing audio in time domain which is slow.
5540 @var{freq} is processing audio in frequency domain which is fast.
5541 Default is @var{freq}.
5544 Set custom positions of virtual loudspeakers. Syntax for this option is:
5545 <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
5546 Each virtual loudspeaker is described with short channel name following with
5547 azimuth and elevation in degrees.
5548 Each virtual loudspeaker description is separated by '|'.
5549 For example to override front left and front right channel positions use:
5550 'speakers=FL 45 15|FR 345 15'.
5551 Descriptions with unrecognised channel names are ignored.
5554 Set custom gain for LFE channels. Value is in dB. Default is 0.
5557 Set custom frame size in number of samples. Default is 1024.
5558 Allowed range is from 1024 to 96000. Only used if option @samp{type}
5559 is set to @var{freq}.
5562 Should all IRs be normalized upon importing SOFA file.
5563 By default is enabled.
5566 Should nearest IRs be interpolated with neighbor IRs if exact position
5567 does not match. By default is disabled.
5570 Minphase all IRs upon loading of SOFA file. By default is disabled.
5573 Set neighbor search angle step. Only used if option @var{interpolate} is enabled.
5576 Set neighbor search radius step. Only used if option @var{interpolate} is enabled.
5579 @subsection Examples
5583 Using ClubFritz6 sofa file:
5585 sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
5589 Using ClubFritz12 sofa file and bigger radius with small rotation:
5591 sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
5595 Similar as above but with custom speaker positions for front left, front right, back left and back right
5596 and also with custom gain:
5598 "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
5605 This filter expands or compresses each half-cycle of audio samples
5606 (local set of samples all above or all below zero and between two nearest zero crossings) depending
5607 on threshold value, so audio reaches target peak value under conditions controlled by below options.
5609 The filter accepts the following options:
5613 Set the expansion target peak value. This specifies the highest allowed absolute amplitude
5614 level for the normalized audio input. Default value is 0.95. Allowed range is from 0.0 to 1.0.
5617 Set the maximum expansion factor. Allowed range is from 1.0 to 50.0. Default value is 2.0.
5618 This option controls maximum local half-cycle of samples expansion. The maximum expansion
5619 would be such that local peak value reaches target peak value but never to surpass it and that
5620 ratio between new and previous peak value does not surpass this option value.
5622 @item compression, c
5623 Set the maximum compression factor. Allowed range is from 1.0 to 50.0. Default value is 2.0.
5624 This option controls maximum local half-cycle of samples compression. This option is used
5625 only if @option{threshold} option is set to value greater than 0.0, then in such cases
5626 when local peak is lower or same as value set by @option{threshold} all samples belonging to
5627 that peak's half-cycle will be compressed by current compression factor.
5630 Set the threshold value. Default value is 0.0. Allowed range is from 0.0 to 1.0.
5631 This option specifies which half-cycles of samples will be compressed and which will be expanded.
5632 Any half-cycle samples with their local peak value below or same as this option value will be
5633 compressed by current compression factor, otherwise, if greater than threshold value they will be
5634 expanded with expansion factor so that it could reach peak target value but never surpass it.
5637 Set the expansion raising amount per each half-cycle of samples. Default value is 0.001.
5638 Allowed range is from 0.0 to 1.0. This controls how fast expansion factor is raised per
5639 each new half-cycle until it reaches @option{expansion} value.
5640 Setting this options too high may lead to distortions.
5643 Set the compression raising amount per each half-cycle of samples. Default value is 0.001.
5644 Allowed range is from 0.0 to 1.0. This controls how fast compression factor is raised per
5645 each new half-cycle until it reaches @option{compression} value.
5648 Specify which channels to filter, by default all available channels are filtered.
5651 Enable inverted filtering, by default is disabled. This inverts interpretation of @option{threshold}
5652 option. When enabled any half-cycle of samples with their local peak value below or same as
5653 @option{threshold} option will be expanded otherwise it will be compressed.
5656 Link channels when calculating gain applied to each filtered channel sample, by default is disabled.
5657 When disabled each filtered channel gain calculation is independent, otherwise when this option
5658 is enabled the minimum of all possible gains for each filtered channel is used.
5661 @subsection Commands
5663 This filter supports the all above options as @ref{commands}.
5665 @section stereotools
5667 This filter has some handy utilities to manage stereo signals, for converting
5668 M/S stereo recordings to L/R signal while having control over the parameters
5669 or spreading the stereo image of master track.
5671 The filter accepts the following options:
5675 Set input level before filtering for both channels. Defaults is 1.
5676 Allowed range is from 0.015625 to 64.
5679 Set output level after filtering for both channels. Defaults is 1.
5680 Allowed range is from 0.015625 to 64.
5683 Set input balance between both channels. Default is 0.
5684 Allowed range is from -1 to 1.
5687 Set output balance between both channels. Default is 0.
5688 Allowed range is from -1 to 1.
5691 Enable softclipping. Results in analog distortion instead of harsh digital 0dB
5692 clipping. Disabled by default.
5695 Mute the left channel. Disabled by default.
5698 Mute the right channel. Disabled by default.
5701 Change the phase of the left channel. Disabled by default.
5704 Change the phase of the right channel. Disabled by default.
5707 Set stereo mode. Available values are:
5711 Left/Right to Left/Right, this is default.
5714 Left/Right to Mid/Side.
5717 Mid/Side to Left/Right.
5720 Left/Right to Left/Left.
5723 Left/Right to Right/Right.
5726 Left/Right to Left + Right.
5729 Left/Right to Right/Left.
5732 Mid/Side to Left/Left.
5735 Mid/Side to Right/Right.
5738 Mid/Side to Right/Left.
5741 Left/Right to Left - Right.
5745 Set level of side signal. Default is 1.
5746 Allowed range is from 0.015625 to 64.
5749 Set balance of side signal. Default is 0.
5750 Allowed range is from -1 to 1.
5753 Set level of the middle signal. Default is 1.
5754 Allowed range is from 0.015625 to 64.
5757 Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
5760 Set stereo base between mono and inversed channels. Default is 0.
5761 Allowed range is from -1 to 1.
5764 Set delay in milliseconds how much to delay left from right channel and
5765 vice versa. Default is 0. Allowed range is from -20 to 20.
5768 Set S/C level. Default is 1. Allowed range is from 1 to 100.
5771 Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
5773 @item bmode_in, bmode_out
5774 Set balance mode for balance_in/balance_out option.
5776 Can be one of the following:
5780 Classic balance mode. Attenuate one channel at time.
5781 Gain is raised up to 1.
5784 Similar as classic mode above but gain is raised up to 2.
5787 Equal power distribution, from -6dB to +6dB range.
5791 @subsection Commands
5793 This filter supports the all above options as @ref{commands}.
5795 @subsection Examples
5799 Apply karaoke like effect:
5801 stereotools=mlev=0.015625
5805 Convert M/S signal to L/R:
5807 "stereotools=mode=ms>lr"
5811 @section stereowiden
5813 This filter enhance the stereo effect by suppressing signal common to both
5814 channels and by delaying the signal of left into right and vice versa,
5815 thereby widening the stereo effect.
5817 The filter accepts the following options:
5821 Time in milliseconds of the delay of left signal into right and vice versa.
5822 Default is 20 milliseconds.
5825 Amount of gain in delayed signal into right and vice versa. Gives a delay
5826 effect of left signal in right output and vice versa which gives widening
5827 effect. Default is 0.3.
5830 Cross feed of left into right with inverted phase. This helps in suppressing
5831 the mono. If the value is 1 it will cancel all the signal common to both
5832 channels. Default is 0.3.
5835 Set level of input signal of original channel. Default is 0.8.
5838 @subsection Commands
5840 This filter supports the all above options except @code{delay} as @ref{commands}.
5842 @section superequalizer
5843 Apply 18 band equalizer.
5845 The filter accepts the following options:
5852 Set 131Hz band gain.
5854 Set 185Hz band gain.
5856 Set 262Hz band gain.
5858 Set 370Hz band gain.
5860 Set 523Hz band gain.
5862 Set 740Hz band gain.
5864 Set 1047Hz band gain.
5866 Set 1480Hz band gain.
5868 Set 2093Hz band gain.
5870 Set 2960Hz band gain.
5872 Set 4186Hz band gain.
5874 Set 5920Hz band gain.
5876 Set 8372Hz band gain.
5878 Set 11840Hz band gain.
5880 Set 16744Hz band gain.
5882 Set 20000Hz band gain.
5886 Apply audio surround upmix filter.
5888 This filter allows to produce multichannel output from audio stream.
5890 The filter accepts the following options:
5894 Set output channel layout. By default, this is @var{5.1}.
5896 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5897 for the required syntax.
5900 Set input channel layout. By default, this is @var{stereo}.
5902 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5903 for the required syntax.
5906 Set input volume level. By default, this is @var{1}.
5909 Set output volume level. By default, this is @var{1}.
5912 Enable LFE channel output if output channel layout has it. By default, this is enabled.
5915 Set LFE low cut off frequency. By default, this is @var{128} Hz.
5918 Set LFE high cut off frequency. By default, this is @var{256} Hz.
5921 Set LFE mode, can be @var{add} or @var{sub}. Default is @var{add}.
5922 In @var{add} mode, LFE channel is created from input audio and added to output.
5923 In @var{sub} mode, LFE channel is created from input audio and added to output but
5924 also all non-LFE output channels are subtracted with output LFE channel.
5927 Set angle of stereo surround transform, Allowed range is from @var{0} to @var{360}.
5928 Default is @var{90}.
5931 Set front center input volume. By default, this is @var{1}.
5934 Set front center output volume. By default, this is @var{1}.
5937 Set front left input volume. By default, this is @var{1}.
5940 Set front left output volume. By default, this is @var{1}.
5943 Set front right input volume. By default, this is @var{1}.
5946 Set front right output volume. By default, this is @var{1}.
5949 Set side left input volume. By default, this is @var{1}.
5952 Set side left output volume. By default, this is @var{1}.
5955 Set side right input volume. By default, this is @var{1}.
5958 Set side right output volume. By default, this is @var{1}.
5961 Set back left input volume. By default, this is @var{1}.
5964 Set back left output volume. By default, this is @var{1}.
5967 Set back right input volume. By default, this is @var{1}.
5970 Set back right output volume. By default, this is @var{1}.
5973 Set back center input volume. By default, this is @var{1}.
5976 Set back center output volume. By default, this is @var{1}.
5979 Set LFE input volume. By default, this is @var{1}.
5982 Set LFE output volume. By default, this is @var{1}.
5985 Set spread usage of stereo image across X axis for all channels.
5988 Set spread usage of stereo image across Y axis for all channels.
5990 @item fcx, flx, frx, blx, brx, slx, srx, bcx
5991 Set spread usage of stereo image across X axis for each channel.
5993 @item fcy, fly, fry, bly, bry, sly, sry, bcy
5994 Set spread usage of stereo image across Y axis for each channel.
5997 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
6000 Set window function.
6002 It accepts the following values:
6025 Default is @code{hann}.
6028 Set window overlap. If set to 1, the recommended overlap for selected
6029 window function will be picked. Default is @code{0.5}.
6032 @section treble, highshelf
6034 Boost or cut treble (upper) frequencies of the audio using a two-pole
6035 shelving filter with a response similar to that of a standard
6036 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
6038 The filter accepts the following options:
6042 Give the gain at whichever is the lower of ~22 kHz and the
6043 Nyquist frequency. Its useful range is about -20 (for a large cut)
6044 to +20 (for a large boost). Beware of clipping when using a positive gain.
6047 Set the filter's central frequency and so can be used
6048 to extend or reduce the frequency range to be boosted or cut.
6049 The default value is @code{3000} Hz.
6052 Set method to specify band-width of filter.
6067 Determine how steep is the filter's shelf transition.
6070 Set number of poles. Default is 2.
6073 How much to use filtered signal in output. Default is 1.
6074 Range is between 0 and 1.
6077 Specify which channels to filter, by default all available are filtered.
6080 Normalize biquad coefficients, by default is disabled.
6081 Enabling it will normalize magnitude response at DC to 0dB.
6084 Set transform type of IIR filter.
6093 Set precison of filtering.
6096 Pick automatic sample format depending on surround filters.
6098 Always use signed 16-bit.
6100 Always use signed 32-bit.
6102 Always use float 32-bit.
6104 Always use float 64-bit.
6108 @subsection Commands
6110 This filter supports the following commands:
6113 Change treble frequency.
6114 Syntax for the command is : "@var{frequency}"
6117 Change treble width_type.
6118 Syntax for the command is : "@var{width_type}"
6121 Change treble width.
6122 Syntax for the command is : "@var{width}"
6126 Syntax for the command is : "@var{gain}"
6130 Syntax for the command is : "@var{mix}"
6135 Sinusoidal amplitude modulation.
6137 The filter accepts the following options:
6141 Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
6142 (20 Hz or lower) will result in a tremolo effect.
6143 This filter may also be used as a ring modulator by specifying
6144 a modulation frequency higher than 20 Hz.
6145 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
6148 Depth of modulation as a percentage. Range is 0.0 - 1.0.
6149 Default value is 0.5.
6154 Sinusoidal phase modulation.
6156 The filter accepts the following options:
6160 Modulation frequency in Hertz.
6161 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
6164 Depth of modulation as a percentage. Range is 0.0 - 1.0.
6165 Default value is 0.5.
6170 Adjust the input audio volume.
6172 It accepts the following parameters:
6176 Set audio volume expression.
6178 Output values are clipped to the maximum value.
6180 The output audio volume is given by the relation:
6182 @var{output_volume} = @var{volume} * @var{input_volume}
6185 The default value for @var{volume} is "1.0".
6188 This parameter represents the mathematical precision.
6190 It determines which input sample formats will be allowed, which affects the
6191 precision of the volume scaling.
6195 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
6197 32-bit floating-point; this limits input sample format to FLT. (default)
6199 64-bit floating-point; this limits input sample format to DBL.
6203 Choose the behaviour on encountering ReplayGain side data in input frames.
6207 Remove ReplayGain side data, ignoring its contents (the default).
6210 Ignore ReplayGain side data, but leave it in the frame.
6213 Prefer the track gain, if present.
6216 Prefer the album gain, if present.
6219 @item replaygain_preamp
6220 Pre-amplification gain in dB to apply to the selected replaygain gain.
6222 Default value for @var{replaygain_preamp} is 0.0.
6224 @item replaygain_noclip
6225 Prevent clipping by limiting the gain applied.
6227 Default value for @var{replaygain_noclip} is 1.
6230 Set when the volume expression is evaluated.
6232 It accepts the following values:
6235 only evaluate expression once during the filter initialization, or
6236 when the @samp{volume} command is sent
6239 evaluate expression for each incoming frame
6242 Default value is @samp{once}.
6245 The volume expression can contain the following parameters.
6249 frame number (starting at zero)
6252 @item nb_consumed_samples
6253 number of samples consumed by the filter
6255 number of samples in the current frame
6257 original frame position in the file
6263 PTS at start of stream
6265 time at start of stream
6271 last set volume value
6274 Note that when @option{eval} is set to @samp{once} only the
6275 @var{sample_rate} and @var{tb} variables are available, all other
6276 variables will evaluate to NAN.
6278 @subsection Commands
6280 This filter supports the following commands:
6283 Modify the volume expression.
6284 The command accepts the same syntax of the corresponding option.
6286 If the specified expression is not valid, it is kept at its current
6290 @subsection Examples
6294 Halve the input audio volume:
6298 volume=volume=-6.0206dB
6301 In all the above example the named key for @option{volume} can be
6302 omitted, for example like in:
6308 Increase input audio power by 6 decibels using fixed-point precision:
6310 volume=volume=6dB:precision=fixed
6314 Fade volume after time 10 with an annihilation period of 5 seconds:
6316 volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
6320 @section volumedetect
6322 Detect the volume of the input video.
6324 The filter has no parameters. The input is not modified. Statistics about
6325 the volume will be printed in the log when the input stream end is reached.
6327 In particular it will show the mean volume (root mean square), maximum
6328 volume (on a per-sample basis), and the beginning of a histogram of the
6329 registered volume values (from the maximum value to a cumulated 1/1000 of
6332 All volumes are in decibels relative to the maximum PCM value.
6334 @subsection Examples
6336 Here is an excerpt of the output:
6338 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
6339 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
6340 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
6341 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
6342 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
6343 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
6344 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
6345 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
6346 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
6352 The mean square energy is approximately -27 dB, or 10^-2.7.
6354 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
6356 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
6359 In other words, raising the volume by +4 dB does not cause any clipping,
6360 raising it by +5 dB causes clipping for 6 samples, etc.
6362 @c man end AUDIO FILTERS
6364 @chapter Audio Sources
6365 @c man begin AUDIO SOURCES
6367 Below is a description of the currently available audio sources.
6371 Buffer audio frames, and make them available to the filter chain.
6373 This source is mainly intended for a programmatic use, in particular
6374 through the interface defined in @file{libavfilter/buffersrc.h}.
6376 It accepts the following parameters:
6380 The timebase which will be used for timestamps of submitted frames. It must be
6381 either a floating-point number or in @var{numerator}/@var{denominator} form.
6384 The sample rate of the incoming audio buffers.
6387 The sample format of the incoming audio buffers.
6388 Either a sample format name or its corresponding integer representation from
6389 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
6391 @item channel_layout
6392 The channel layout of the incoming audio buffers.
6393 Either a channel layout name from channel_layout_map in
6394 @file{libavutil/channel_layout.c} or its corresponding integer representation
6395 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
6398 The number of channels of the incoming audio buffers.
6399 If both @var{channels} and @var{channel_layout} are specified, then they
6404 @subsection Examples
6407 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
6410 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
6411 Since the sample format with name "s16p" corresponds to the number
6412 6 and the "stereo" channel layout corresponds to the value 0x3, this is
6415 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
6420 Generate an audio signal specified by an expression.
6422 This source accepts in input one or more expressions (one for each
6423 channel), which are evaluated and used to generate a corresponding
6426 This source accepts the following options:
6430 Set the '|'-separated expressions list for each separate channel. In case the
6431 @option{channel_layout} option is not specified, the selected channel layout
6432 depends on the number of provided expressions. Otherwise the last
6433 specified expression is applied to the remaining output channels.
6435 @item channel_layout, c
6436 Set the channel layout. The number of channels in the specified layout
6437 must be equal to the number of specified expressions.
6440 Set the minimum duration of the sourced audio. See
6441 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
6442 for the accepted syntax.
6443 Note that the resulting duration may be greater than the specified
6444 duration, as the generated audio is always cut at the end of a
6447 If not specified, or the expressed duration is negative, the audio is
6448 supposed to be generated forever.
6451 Set the number of samples per channel per each output frame,
6454 @item sample_rate, s
6455 Specify the sample rate, default to 44100.
6458 Each expression in @var{exprs} can contain the following constants:
6462 number of the evaluated sample, starting from 0
6465 time of the evaluated sample expressed in seconds, starting from 0
6472 @subsection Examples
6482 Generate a sin signal with frequency of 440 Hz, set sample rate to
6485 aevalsrc="sin(440*2*PI*t):s=8000"
6489 Generate a two channels signal, specify the channel layout (Front
6490 Center + Back Center) explicitly:
6492 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
6496 Generate white noise:
6498 aevalsrc="-2+random(0)"
6502 Generate an amplitude modulated signal:
6504 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
6508 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
6510 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
6517 Generate a FIR coefficients using frequency sampling method.
6519 The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
6521 The filter accepts the following options:
6525 Set number of filter coefficents in output audio stream.
6526 Default value is 1025.
6529 Set frequency points from where magnitude and phase are set.
6530 This must be in non decreasing order, and first element must be 0, while last element
6531 must be 1. Elements are separated by white spaces.
6534 Set magnitude value for every frequency point set by @option{frequency}.
6535 Number of values must be same as number of frequency points.
6536 Values are separated by white spaces.
6539 Set phase value for every frequency point set by @option{frequency}.
6540 Number of values must be same as number of frequency points.
6541 Values are separated by white spaces.
6543 @item sample_rate, r
6544 Set sample rate, default is 44100.
6547 Set number of samples per each frame. Default is 1024.
6550 Set window function. Default is blackman.
6555 The null audio source, return unprocessed audio frames. It is mainly useful
6556 as a template and to be employed in analysis / debugging tools, or as
6557 the source for filters which ignore the input data (for example the sox
6560 This source accepts the following options:
6564 @item channel_layout, cl
6566 Specifies the channel layout, and can be either an integer or a string
6567 representing a channel layout. The default value of @var{channel_layout}
6570 Check the channel_layout_map definition in
6571 @file{libavutil/channel_layout.c} for the mapping between strings and
6572 channel layout values.
6574 @item sample_rate, r
6575 Specifies the sample rate, and defaults to 44100.
6578 Set the number of samples per requested frames.
6581 Set the duration of the sourced audio. See
6582 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
6583 for the accepted syntax.
6585 If not specified, or the expressed duration is negative, the audio is
6586 supposed to be generated forever.
6589 @subsection Examples
6593 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
6595 anullsrc=r=48000:cl=4
6599 Do the same operation with a more obvious syntax:
6601 anullsrc=r=48000:cl=mono
6605 All the parameters need to be explicitly defined.
6609 Synthesize a voice utterance using the libflite library.
6611 To enable compilation of this filter you need to configure FFmpeg with
6612 @code{--enable-libflite}.
6614 Note that versions of the flite library prior to 2.0 are not thread-safe.
6616 The filter accepts the following options:
6621 If set to 1, list the names of the available voices and exit
6622 immediately. Default value is 0.
6625 Set the maximum number of samples per frame. Default value is 512.
6628 Set the filename containing the text to speak.
6631 Set the text to speak.
6634 Set the voice to use for the speech synthesis. Default value is
6635 @code{kal}. See also the @var{list_voices} option.
6638 @subsection Examples
6642 Read from file @file{speech.txt}, and synthesize the text using the
6643 standard flite voice:
6645 flite=textfile=speech.txt
6649 Read the specified text selecting the @code{slt} voice:
6651 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
6655 Input text to ffmpeg:
6657 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
6661 Make @file{ffplay} speak the specified text, using @code{flite} and
6662 the @code{lavfi} device:
6664 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
6668 For more information about libflite, check:
6669 @url{http://www.festvox.org/flite/}
6673 Generate a noise audio signal.
6675 The filter accepts the following options:
6678 @item sample_rate, r
6679 Specify the sample rate. Default value is 48000 Hz.
6682 Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value
6686 Specify the duration of the generated audio stream. Not specifying this option
6687 results in noise with an infinite length.
6689 @item color, colour, c
6690 Specify the color of noise. Available noise colors are white, pink, brown,
6691 blue, violet and velvet. Default color is white.
6694 Specify a value used to seed the PRNG.
6697 Set the number of samples per each output frame, default is 1024.
6700 @subsection Examples
6705 Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5:
6707 anoisesrc=d=60:c=pink:r=44100:a=0.5
6713 Generate odd-tap Hilbert transform FIR coefficients.
6715 The resulting stream can be used with @ref{afir} filter for phase-shifting
6716 the signal by 90 degrees.
6718 This is used in many matrix coding schemes and for analytic signal generation.
6719 The process is often written as a multiplication by i (or j), the imaginary unit.
6721 The filter accepts the following options:
6725 @item sample_rate, s
6726 Set sample rate, default is 44100.
6729 Set length of FIR filter, default is 22051.
6732 Set number of samples per each frame.
6735 Set window function to be used when generating FIR coefficients.
6740 Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients.
6742 The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
6744 The filter accepts the following options:
6747 @item sample_rate, r
6748 Set sample rate, default is 44100.
6751 Set number of samples per each frame. Default is 1024.
6754 Set high-pass frequency. Default is 0.
6757 Set low-pass frequency. Default is 0.
6758 If high-pass frequency is lower than low-pass frequency and low-pass frequency
6759 is higher than 0 then filter will create band-pass filter coefficients,
6760 otherwise band-reject filter coefficients.
6763 Set filter phase response. Default is 50. Allowed range is from 0 to 100.
6766 Set Kaiser window beta.
6769 Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB.
6772 Enable rounding, by default is disabled.
6775 Set number of taps for high-pass filter.
6778 Set number of taps for low-pass filter.
6783 Generate an audio signal made of a sine wave with amplitude 1/8.
6785 The audio signal is bit-exact.
6787 The filter accepts the following options:
6792 Set the carrier frequency. Default is 440 Hz.
6794 @item beep_factor, b
6795 Enable a periodic beep every second with frequency @var{beep_factor} times
6796 the carrier frequency. Default is 0, meaning the beep is disabled.
6798 @item sample_rate, r
6799 Specify the sample rate, default is 44100.
6802 Specify the duration of the generated audio stream.
6804 @item samples_per_frame
6805 Set the number of samples per output frame.
6807 The expression can contain the following constants:
6811 The (sequential) number of the output audio frame, starting from 0.
6814 The PTS (Presentation TimeStamp) of the output audio frame,
6815 expressed in @var{TB} units.
6818 The PTS of the output audio frame, expressed in seconds.
6821 The timebase of the output audio frames.
6824 Default is @code{1024}.
6827 @subsection Examples
6832 Generate a simple 440 Hz sine wave:
6838 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
6842 sine=frequency=220:beep_factor=4:duration=5
6846 Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC
6849 sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
6853 @c man end AUDIO SOURCES
6855 @chapter Audio Sinks
6856 @c man begin AUDIO SINKS
6858 Below is a description of the currently available audio sinks.
6860 @section abuffersink
6862 Buffer audio frames, and make them available to the end of filter chain.
6864 This sink is mainly intended for programmatic use, in particular
6865 through the interface defined in @file{libavfilter/buffersink.h}
6866 or the options system.
6868 It accepts a pointer to an AVABufferSinkContext structure, which
6869 defines the incoming buffers' formats, to be passed as the opaque
6870 parameter to @code{avfilter_init_filter} for initialization.
6873 Null audio sink; do absolutely nothing with the input audio. It is
6874 mainly useful as a template and for use in analysis / debugging
6877 @c man end AUDIO SINKS
6879 @chapter Video Filters
6880 @c man begin VIDEO FILTERS
6882 When you configure your FFmpeg build, you can disable any of the
6883 existing filters using @code{--disable-filters}.
6884 The configure output will show the video filters included in your
6887 Below is a description of the currently available video filters.
6891 Mark a region of interest in a video frame.
6893 The frame data is passed through unchanged, but metadata is attached
6894 to the frame indicating regions of interest which can affect the
6895 behaviour of later encoding. Multiple regions can be marked by
6896 applying the filter multiple times.
6900 Region distance in pixels from the left edge of the frame.
6902 Region distance in pixels from the top edge of the frame.
6904 Region width in pixels.
6906 Region height in pixels.
6908 The parameters @var{x}, @var{y}, @var{w} and @var{h} are expressions,
6909 and may contain the following variables:
6912 Width of the input frame.
6914 Height of the input frame.
6918 Quantisation offset to apply within the region.
6920 This must be a real value in the range -1 to +1. A value of zero
6921 indicates no quality change. A negative value asks for better quality
6922 (less quantisation), while a positive value asks for worse quality
6923 (greater quantisation).
6925 The range is calibrated so that the extreme values indicate the
6926 largest possible offset - if the rest of the frame is encoded with the
6927 worst possible quality, an offset of -1 indicates that this region
6928 should be encoded with the best possible quality anyway. Intermediate
6929 values are then interpolated in some codec-dependent way.
6931 For example, in 10-bit H.264 the quantisation parameter varies between
6932 -12 and 51. A typical qoffset value of -1/10 therefore indicates that
6933 this region should be encoded with a QP around one-tenth of the full
6934 range better than the rest of the frame. So, if most of the frame
6935 were to be encoded with a QP of around 30, this region would get a QP
6936 of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3).
6937 An extreme value of -1 would indicate that this region should be
6938 encoded with the best possible quality regardless of the treatment of
6939 the rest of the frame - that is, should be encoded at a QP of -12.
6941 If set to true, remove any existing regions of interest marked on the
6942 frame before adding the new one.
6945 @subsection Examples
6949 Mark the centre quarter of the frame as interesting.
6951 addroi=iw/4:ih/4:iw/2:ih/2:-1/10
6954 Mark the 100-pixel-wide region on the left edge of the frame as very
6955 uninteresting (to be encoded at much lower quality than the rest of
6958 addroi=0:0:100:ih:+1/5
6962 @section alphaextract
6964 Extract the alpha component from the input as a grayscale video. This
6965 is especially useful with the @var{alphamerge} filter.
6969 Add or replace the alpha component of the primary input with the
6970 grayscale value of a second input. This is intended for use with
6971 @var{alphaextract} to allow the transmission or storage of frame
6972 sequences that have alpha in a format that doesn't support an alpha
6975 For example, to reconstruct full frames from a normal YUV-encoded video
6976 and a separate video created with @var{alphaextract}, you might use:
6978 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
6983 Amplify differences between current pixel and pixels of adjacent frames in
6984 same pixel location.
6986 This filter accepts the following options:
6990 Set frame radius. Default is 2. Allowed range is from 1 to 63.
6991 For example radius of 3 will instruct filter to calculate average of 7 frames.
6994 Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535.
6997 Set threshold for difference amplification. Any difference greater or equal to
6998 this value will not alter source pixel. Default is 10.
6999 Allowed range is from 0 to 65535.
7002 Set tolerance for difference amplification. Any difference lower to
7003 this value will not alter source pixel. Default is 0.
7004 Allowed range is from 0 to 65535.
7007 Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
7008 This option controls maximum possible value that will decrease source pixel value.
7011 Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
7012 This option controls maximum possible value that will increase source pixel value.
7015 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
7018 @subsection Commands
7020 This filter supports the following @ref{commands} that corresponds to option of same name:
7032 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
7033 and libavformat to work. On the other hand, it is limited to ASS (Advanced
7034 Substation Alpha) subtitles files.
7036 This filter accepts the following option in addition to the common options from
7037 the @ref{subtitles} filter:
7041 Set the shaping engine
7043 Available values are:
7046 The default libass shaping engine, which is the best available.
7048 Fast, font-agnostic shaper that can do only substitutions
7050 Slower shaper using OpenType for substitutions and positioning
7053 The default is @code{auto}.
7057 Apply an Adaptive Temporal Averaging Denoiser to the video input.
7059 The filter accepts the following options:
7063 Set threshold A for 1st plane. Default is 0.02.
7064 Valid range is 0 to 0.3.
7067 Set threshold B for 1st plane. Default is 0.04.
7068 Valid range is 0 to 5.
7071 Set threshold A for 2nd plane. Default is 0.02.
7072 Valid range is 0 to 0.3.
7075 Set threshold B for 2nd plane. Default is 0.04.
7076 Valid range is 0 to 5.
7079 Set threshold A for 3rd plane. Default is 0.02.
7080 Valid range is 0 to 0.3.
7083 Set threshold B for 3rd plane. Default is 0.04.
7084 Valid range is 0 to 5.
7086 Threshold A is designed to react on abrupt changes in the input signal and
7087 threshold B is designed to react on continuous changes in the input signal.
7090 Set number of frames filter will use for averaging. Default is 9. Must be odd
7091 number in range [5, 129].
7094 Set what planes of frame filter will use for averaging. Default is all.
7097 Set what variant of algorithm filter will use for averaging. Default is @code{p} parallel.
7098 Alternatively can be set to @code{s} serial.
7100 Parallel can be faster then serial, while other way around is never true.
7101 Parallel will abort early on first change being greater then thresholds, while serial
7102 will continue processing other side of frames if they are equal or below thresholds.
7107 Set sigma for 1st plane, 2nd plane or 3rd plane. Default is 32767.
7108 Valid range is from 0 to 32767.
7109 This options controls weight for each pixel in radius defined by size.
7110 Default value means every pixel have same weight.
7111 Setting this option to 0 effectively disables filtering.
7114 @subsection Commands
7115 This filter supports same @ref{commands} as options except option @code{s}.
7116 The command accepts the same syntax of the corresponding option.
7120 Apply average blur filter.
7122 The filter accepts the following options:
7126 Set horizontal radius size.
7129 Set which planes to filter. By default all planes are filtered.
7132 Set vertical radius size, if zero it will be same as @code{sizeX}.
7133 Default is @code{0}.
7136 @subsection Commands
7137 This filter supports same commands as options.
7138 The command accepts the same syntax of the corresponding option.
7140 If the specified expression is not valid, it is kept at its current
7145 Compute the bounding box for the non-black pixels in the input frame
7148 This filter computes the bounding box containing all the pixels with a
7149 luminance value greater than the minimum allowed value.
7150 The parameters describing the bounding box are printed on the filter
7153 The filter accepts the following option:
7157 Set the minimal luminance value. Default is @code{16}.
7160 @subsection Commands
7162 This filter supports the all above options as @ref{commands}.
7165 Apply bilateral filter, spatial smoothing while preserving edges.
7167 The filter accepts the following options:
7170 Set sigma of gaussian function to calculate spatial weight.
7171 Allowed range is 0 to 512. Default is 0.1.
7174 Set sigma of gaussian function to calculate range weight.
7175 Allowed range is 0 to 1. Default is 0.1.
7178 Set planes to filter. Default is first only.
7181 @subsection Commands
7183 This filter supports the all above options as @ref{commands}.
7185 @section bitplanenoise
7187 Show and measure bit plane noise.
7189 The filter accepts the following options:
7193 Set which plane to analyze. Default is @code{1}.
7196 Filter out noisy pixels from @code{bitplane} set above.
7197 Default is disabled.
7200 @section blackdetect
7202 Detect video intervals that are (almost) completely black. Can be
7203 useful to detect chapter transitions, commercials, or invalid
7206 The filter outputs its detection analysis to both the log as well as
7207 frame metadata. If a black segment of at least the specified minimum
7208 duration is found, a line with the start and end timestamps as well
7209 as duration is printed to the log with level @code{info}. In addition,
7210 a log line with level @code{debug} is printed per frame showing the
7211 black amount detected for that frame.
7213 The filter also attaches metadata to the first frame of a black
7214 segment with key @code{lavfi.black_start} and to the first frame
7215 after the black segment ends with key @code{lavfi.black_end}. The
7216 value is the frame's timestamp. This metadata is added regardless
7217 of the minimum duration specified.
7219 The filter accepts the following options:
7222 @item black_min_duration, d
7223 Set the minimum detected black duration expressed in seconds. It must
7224 be a non-negative floating point number.
7226 Default value is 2.0.
7228 @item picture_black_ratio_th, pic_th
7229 Set the threshold for considering a picture "black".
7230 Express the minimum value for the ratio:
7232 @var{nb_black_pixels} / @var{nb_pixels}
7235 for which a picture is considered black.
7236 Default value is 0.98.
7238 @item pixel_black_th, pix_th
7239 Set the threshold for considering a pixel "black".
7241 The threshold expresses the maximum pixel luminance value for which a
7242 pixel is considered "black". The provided value is scaled according to
7243 the following equation:
7245 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
7248 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
7249 the input video format, the range is [0-255] for YUV full-range
7250 formats and [16-235] for YUV non full-range formats.
7252 Default value is 0.10.
7255 The following example sets the maximum pixel threshold to the minimum
7256 value, and detects only black intervals of 2 or more seconds:
7258 blackdetect=d=2:pix_th=0.00
7263 Detect frames that are (almost) completely black. Can be useful to
7264 detect chapter transitions or commercials. Output lines consist of
7265 the frame number of the detected frame, the percentage of blackness,
7266 the position in the file if known or -1 and the timestamp in seconds.
7268 In order to display the output lines, you need to set the loglevel at
7269 least to the AV_LOG_INFO value.
7271 This filter exports frame metadata @code{lavfi.blackframe.pblack}.
7272 The value represents the percentage of pixels in the picture that
7273 are below the threshold value.
7275 It accepts the following parameters:
7280 The percentage of the pixels that have to be below the threshold; it defaults to
7283 @item threshold, thresh
7284 The threshold below which a pixel value is considered black; it defaults to
7292 Blend two video frames into each other.
7294 The @code{blend} filter takes two input streams and outputs one
7295 stream, the first input is the "top" layer and second input is
7296 "bottom" layer. By default, the output terminates when the longest input terminates.
7298 The @code{tblend} (time blend) filter takes two consecutive frames
7299 from one single stream, and outputs the result obtained by blending
7300 the new frame on top of the old frame.
7302 A description of the accepted options follows.
7310 Set blend mode for specific pixel component or all pixel components in case
7311 of @var{all_mode}. Default value is @code{normal}.
7313 Available values for component modes are:
7355 Set blend opacity for specific pixel component or all pixel components in case
7356 of @var{all_opacity}. Only used in combination with pixel component blend modes.
7363 Set blend expression for specific pixel component or all pixel components in case
7364 of @var{all_expr}. Note that related mode options will be ignored if those are set.
7366 The expressions can use the following variables:
7370 The sequential number of the filtered frame, starting from @code{0}.
7374 the coordinates of the current sample
7378 the width and height of currently filtered plane
7382 Width and height scale for the plane being filtered. It is the
7383 ratio between the dimensions of the current plane to the luma plane,
7384 e.g. for a @code{yuv420p} frame, the values are @code{1,1} for
7385 the luma plane and @code{0.5,0.5} for the chroma planes.
7388 Time of the current frame, expressed in seconds.
7391 Value of pixel component at current location for first video frame (top layer).
7394 Value of pixel component at current location for second video frame (bottom layer).
7398 The @code{blend} filter also supports the @ref{framesync} options.
7400 @subsection Examples
7404 Apply transition from bottom layer to top layer in first 10 seconds:
7406 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
7410 Apply linear horizontal transition from top layer to bottom layer:
7412 blend=all_expr='A*(X/W)+B*(1-X/W)'
7416 Apply 1x1 checkerboard effect:
7418 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
7422 Apply uncover left effect:
7424 blend=all_expr='if(gte(N*SW+X,W),A,B)'
7428 Apply uncover down effect:
7430 blend=all_expr='if(gte(Y-N*SH,0),A,B)'
7434 Apply uncover up-left effect:
7436 blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
7440 Split diagonally video and shows top and bottom layer on each side:
7442 blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
7446 Display differences between the current and the previous frame:
7448 tblend=all_mode=grainextract
7454 Denoise frames using Block-Matching 3D algorithm.
7456 The filter accepts the following options.
7460 Set denoising strength. Default value is 1.
7461 Allowed range is from 0 to 999.9.
7462 The denoising algorithm is very sensitive to sigma, so adjust it
7463 according to the source.
7466 Set local patch size. This sets dimensions in 2D.
7469 Set sliding step for processing blocks. Default value is 4.
7470 Allowed range is from 1 to 64.
7471 Smaller values allows processing more reference blocks and is slower.
7474 Set maximal number of similar blocks for 3rd dimension. Default value is 1.
7475 When set to 1, no block matching is done. Larger values allows more blocks
7477 Allowed range is from 1 to 256.
7480 Set radius for search block matching. Default is 9.
7481 Allowed range is from 1 to INT32_MAX.
7484 Set step between two search locations for block matching. Default is 1.
7485 Allowed range is from 1 to 64. Smaller is slower.
7488 Set threshold of mean square error for block matching. Valid range is 0 to
7492 Set thresholding parameter for hard thresholding in 3D transformed domain.
7493 Larger values results in stronger hard-thresholding filtering in frequency
7497 Set filtering estimation mode. Can be @code{basic} or @code{final}.
7498 Default is @code{basic}.
7501 If enabled, filter will use 2nd stream for block matching.
7502 Default is disabled for @code{basic} value of @var{estim} option,
7503 and always enabled if value of @var{estim} is @code{final}.
7506 Set planes to filter. Default is all available except alpha.
7509 @subsection Examples
7513 Basic filtering with bm3d:
7515 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
7519 Same as above, but filtering only luma:
7521 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
7525 Same as above, but with both estimation modes:
7527 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
7531 Same as above, but prefilter with @ref{nlmeans} filter instead:
7533 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
7539 Apply a boxblur algorithm to the input video.
7541 It accepts the following parameters:
7545 @item luma_radius, lr
7546 @item luma_power, lp
7547 @item chroma_radius, cr
7548 @item chroma_power, cp
7549 @item alpha_radius, ar
7550 @item alpha_power, ap
7554 A description of the accepted options follows.
7557 @item luma_radius, lr
7558 @item chroma_radius, cr
7559 @item alpha_radius, ar
7560 Set an expression for the box radius in pixels used for blurring the
7561 corresponding input plane.
7563 The radius value must be a non-negative number, and must not be
7564 greater than the value of the expression @code{min(w,h)/2} for the
7565 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
7568 Default value for @option{luma_radius} is "2". If not specified,
7569 @option{chroma_radius} and @option{alpha_radius} default to the
7570 corresponding value set for @option{luma_radius}.
7572 The expressions can contain the following constants:
7576 The input width and height in pixels.
7580 The input chroma image width and height in pixels.
7584 The horizontal and vertical chroma subsample values. For example, for the
7585 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
7588 @item luma_power, lp
7589 @item chroma_power, cp
7590 @item alpha_power, ap
7591 Specify how many times the boxblur filter is applied to the
7592 corresponding plane.
7594 Default value for @option{luma_power} is 2. If not specified,
7595 @option{chroma_power} and @option{alpha_power} default to the
7596 corresponding value set for @option{luma_power}.
7598 A value of 0 will disable the effect.
7601 @subsection Examples
7605 Apply a boxblur filter with the luma, chroma, and alpha radii
7608 boxblur=luma_radius=2:luma_power=1
7613 Set the luma radius to 2, and alpha and chroma radius to 0:
7615 boxblur=2:1:cr=0:ar=0
7619 Set the luma and chroma radii to a fraction of the video dimension:
7621 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
7627 Deinterlace the input video ("bwdif" stands for "Bob Weaver
7628 Deinterlacing Filter").
7630 Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
7631 interpolation algorithms.
7632 It accepts the following parameters:
7636 The interlacing mode to adopt. It accepts one of the following values:
7640 Output one frame for each frame.
7642 Output one frame for each field.
7645 The default value is @code{send_field}.
7648 The picture field parity assumed for the input interlaced video. It accepts one
7649 of the following values:
7653 Assume the top field is first.
7655 Assume the bottom field is first.
7657 Enable automatic detection of field parity.
7660 The default value is @code{auto}.
7661 If the interlacing is unknown or the decoder does not export this information,
7662 top field first will be assumed.
7665 Specify which frames to deinterlace. Accepts one of the following
7670 Deinterlace all frames.
7672 Only deinterlace frames marked as interlaced.
7675 The default value is @code{all}.
7680 Apply Contrast Adaptive Sharpen filter to video stream.
7682 The filter accepts the following options:
7686 Set the sharpening strength. Default value is 0.
7689 Set planes to filter. Default value is to filter all
7690 planes except alpha plane.
7693 @subsection Commands
7694 This filter supports same @ref{commands} as options.
7697 Remove all color information for all colors except for certain one.
7699 The filter accepts the following options:
7703 The color which will not be replaced with neutral chroma.
7706 Similarity percentage with the above color.
7707 0.01 matches only the exact key color, while 1.0 matches everything.
7711 0.0 makes pixels either fully gray, or not gray at all.
7712 Higher values result in more preserved color.
7715 Signals that the color passed is already in YUV instead of RGB.
7717 Literal colors like "green" or "red" don't make sense with this enabled anymore.
7718 This can be used to pass exact YUV values as hexadecimal numbers.
7721 @subsection Commands
7722 This filter supports same @ref{commands} as options.
7723 The command accepts the same syntax of the corresponding option.
7725 If the specified expression is not valid, it is kept at its current
7729 YUV colorspace color/chroma keying.
7731 The filter accepts the following options:
7735 The color which will be replaced with transparency.
7738 Similarity percentage with the key color.
7740 0.01 matches only the exact key color, while 1.0 matches everything.
7745 0.0 makes pixels either fully transparent, or not transparent at all.
7747 Higher values result in semi-transparent pixels, with a higher transparency
7748 the more similar the pixels color is to the key color.
7751 Signals that the color passed is already in YUV instead of RGB.
7753 Literal colors like "green" or "red" don't make sense with this enabled anymore.
7754 This can be used to pass exact YUV values as hexadecimal numbers.
7757 @subsection Commands
7758 This filter supports same @ref{commands} as options.
7759 The command accepts the same syntax of the corresponding option.
7761 If the specified expression is not valid, it is kept at its current
7764 @subsection Examples
7768 Make every green pixel in the input image transparent:
7770 ffmpeg -i input.png -vf chromakey=green out.png
7774 Overlay a greenscreen-video on top of a static black background.
7776 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
7781 Reduce chrominance noise.
7783 The filter accepts the following options:
7787 Set threshold for averaging chrominance values.
7788 Sum of absolute difference of Y, U and V pixel components of current
7789 pixel and neighbour pixels lower than this threshold will be used in
7790 averaging. Luma component is left unchanged and is copied to output.
7791 Default value is 30. Allowed range is from 1 to 200.
7794 Set horizontal radius of rectangle used for averaging.
7795 Allowed range is from 1 to 100. Default value is 5.
7798 Set vertical radius of rectangle used for averaging.
7799 Allowed range is from 1 to 100. Default value is 5.
7802 Set horizontal step when averaging. Default value is 1.
7803 Allowed range is from 1 to 50.
7804 Mostly useful to speed-up filtering.
7807 Set vertical step when averaging. Default value is 1.
7808 Allowed range is from 1 to 50.
7809 Mostly useful to speed-up filtering.
7812 Set Y threshold for averaging chrominance values.
7813 Set finer control for max allowed difference between Y components
7814 of current pixel and neigbour pixels.
7815 Default value is 200. Allowed range is from 1 to 200.
7818 Set U threshold for averaging chrominance values.
7819 Set finer control for max allowed difference between U components
7820 of current pixel and neigbour pixels.
7821 Default value is 200. Allowed range is from 1 to 200.
7824 Set V threshold for averaging chrominance values.
7825 Set finer control for max allowed difference between V components
7826 of current pixel and neigbour pixels.
7827 Default value is 200. Allowed range is from 1 to 200.
7830 @subsection Commands
7831 This filter supports same @ref{commands} as options.
7832 The command accepts the same syntax of the corresponding option.
7834 @section chromashift
7835 Shift chroma pixels horizontally and/or vertically.
7837 The filter accepts the following options:
7840 Set amount to shift chroma-blue horizontally.
7842 Set amount to shift chroma-blue vertically.
7844 Set amount to shift chroma-red horizontally.
7846 Set amount to shift chroma-red vertically.
7848 Set edge mode, can be @var{smear}, default, or @var{warp}.
7851 @subsection Commands
7853 This filter supports the all above options as @ref{commands}.
7857 Display CIE color diagram with pixels overlaid onto it.
7859 The filter accepts the following options:
7874 @item uhdtv, rec2020
7888 Set what gamuts to draw.
7890 See @code{system} option for available values.
7893 Set ciescope size, by default set to 512.
7896 Set intensity used to map input pixel values to CIE diagram.
7899 Set contrast used to draw tongue colors that are out of active color system gamut.
7902 Correct gamma displayed on scope, by default enabled.
7905 Show white point on CIE diagram, by default disabled.
7908 Set input gamma. Used only with XYZ input color space.
7913 Visualize information exported by some codecs.
7915 Some codecs can export information through frames using side-data or other
7916 means. For example, some MPEG based codecs export motion vectors through the
7917 @var{export_mvs} flag in the codec @option{flags2} option.
7919 The filter accepts the following option:
7923 Set motion vectors to visualize.
7925 Available flags for @var{mv} are:
7929 forward predicted MVs of P-frames
7931 forward predicted MVs of B-frames
7933 backward predicted MVs of B-frames
7937 Display quantization parameters using the chroma planes.
7940 Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
7942 Available flags for @var{mv_type} are:
7946 forward predicted MVs
7948 backward predicted MVs
7951 @item frame_type, ft
7952 Set frame type to visualize motion vectors of.
7954 Available flags for @var{frame_type} are:
7958 intra-coded frames (I-frames)
7960 predicted frames (P-frames)
7962 bi-directionally predicted frames (B-frames)
7966 @subsection Examples
7970 Visualize forward predicted MVs of all frames using @command{ffplay}:
7972 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
7976 Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
7978 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
7982 @section colorbalance
7983 Modify intensity of primary colors (red, green and blue) of input frames.
7985 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
7986 regions for the red-cyan, green-magenta or blue-yellow balance.
7988 A positive adjustment value shifts the balance towards the primary color, a negative
7989 value towards the complementary color.
7991 The filter accepts the following options:
7997 Adjust red, green and blue shadows (darkest pixels).
8002 Adjust red, green and blue midtones (medium pixels).
8007 Adjust red, green and blue highlights (brightest pixels).
8009 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
8012 Preserve lightness when changing color balance. Default is disabled.
8015 @subsection Examples
8019 Add red color cast to shadows:
8025 @subsection Commands
8027 This filter supports the all above options as @ref{commands}.
8029 @section colorcontrast
8031 Adjust color contrast between RGB components.
8033 The filter accepts the following options:
8037 Set the red-cyan contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0.
8040 Set the green-magenta contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0.
8043 Set the blue-yellow contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0.
8048 Set the weight of each @code{rc}, @code{gm}, @code{by} option value. Default value is 0.0.
8049 Allowed range is from 0.0 to 1.0. If all weights are 0.0 filtering is disabled.
8052 Set the amount of preserving lightness. Default value is 0.0. Allowed range is from 0.0 to 1.0.
8055 @subsection Commands
8057 This filter supports the all above options as @ref{commands}.
8059 @section colorcorrect
8061 Adjust color white balance selectively for blacks and whites.
8062 This filter operates in YUV colorspace.
8064 The filter accepts the following options:
8068 Set the red shadow spot. Allowed range is from -1.0 to 1.0.
8072 Set the blue shadow spot. Allowed range is from -1.0 to 1.0.
8076 Set the red highlight spot. Allowed range is from -1.0 to 1.0.
8080 Set the red highlight spot. Allowed range is from -1.0 to 1.0.
8084 Set the amount of saturation. Allowed range is from -3.0 to 3.0.
8088 @subsection Commands
8090 This filter supports the all above options as @ref{commands}.
8092 @section colorchannelmixer
8094 Adjust video input frames by re-mixing color channels.
8096 This filter modifies a color channel by adding the values associated to
8097 the other channels of the same pixels. For example if the value to
8098 modify is red, the output value will be:
8100 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
8103 The filter accepts the following options:
8110 Adjust contribution of input red, green, blue and alpha channels for output red channel.
8111 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
8117 Adjust contribution of input red, green, blue and alpha channels for output green channel.
8118 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
8124 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
8125 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
8131 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
8132 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
8134 Allowed ranges for options are @code{[-2.0, 2.0]}.
8137 Preserve lightness when changing colors. Allowed range is from @code{[0.0, 1.0]}.
8138 Default is @code{0.0}, thus disabled.
8141 @subsection Examples
8145 Convert source to grayscale:
8147 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
8150 Simulate sepia tones:
8152 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
8156 @subsection Commands
8158 This filter supports the all above options as @ref{commands}.
8161 RGB colorspace color keying.
8163 The filter accepts the following options:
8167 The color which will be replaced with transparency.
8170 Similarity percentage with the key color.
8172 0.01 matches only the exact key color, while 1.0 matches everything.
8177 0.0 makes pixels either fully transparent, or not transparent at all.
8179 Higher values result in semi-transparent pixels, with a higher transparency
8180 the more similar the pixels color is to the key color.
8183 @subsection Examples
8187 Make every green pixel in the input image transparent:
8189 ffmpeg -i input.png -vf colorkey=green out.png
8193 Overlay a greenscreen-video on top of a static background image.
8195 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
8199 @subsection Commands
8200 This filter supports same @ref{commands} as options.
8201 The command accepts the same syntax of the corresponding option.
8203 If the specified expression is not valid, it is kept at its current
8207 Remove all color information for all RGB colors except for certain one.
8209 The filter accepts the following options:
8213 The color which will not be replaced with neutral gray.
8216 Similarity percentage with the above color.
8217 0.01 matches only the exact key color, while 1.0 matches everything.
8220 Blend percentage. 0.0 makes pixels fully gray.
8221 Higher values result in more preserved color.
8224 @subsection Commands
8225 This filter supports same @ref{commands} as options.
8226 The command accepts the same syntax of the corresponding option.
8228 If the specified expression is not valid, it is kept at its current
8231 @section colorlevels
8233 Adjust video input frames using levels.
8235 The filter accepts the following options:
8242 Adjust red, green, blue and alpha input black point.
8243 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
8249 Adjust red, green, blue and alpha input white point.
8250 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
8252 Input levels are used to lighten highlights (bright tones), darken shadows
8253 (dark tones), change the balance of bright and dark tones.
8259 Adjust red, green, blue and alpha output black point.
8260 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
8266 Adjust red, green, blue and alpha output white point.
8267 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
8269 Output levels allows manual selection of a constrained output level range.
8272 @subsection Examples
8276 Make video output darker:
8278 colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
8284 colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
8288 Make video output lighter:
8290 colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
8294 Increase brightness:
8296 colorlevels=romin=0.5:gomin=0.5:bomin=0.5
8300 @subsection Commands
8302 This filter supports the all above options as @ref{commands}.
8304 @section colormatrix
8306 Convert color matrix.
8308 The filter accepts the following options:
8313 Specify the source and destination color matrix. Both values must be
8316 The accepted values are:
8344 For example to convert from BT.601 to SMPTE-240M, use the command:
8346 colormatrix=bt601:smpte240m
8351 Convert colorspace, transfer characteristics or color primaries.
8352 Input video needs to have an even size.
8354 The filter accepts the following options:
8359 Specify all color properties at once.
8361 The accepted values are:
8391 Specify output colorspace.
8393 The accepted values are:
8402 BT.470BG or BT.601-6 625
8405 SMPTE-170M or BT.601-6 525
8414 BT.2020 with non-constant luminance
8420 Specify output transfer characteristics.
8422 The accepted values are:
8434 Constant gamma of 2.2
8437 Constant gamma of 2.8
8440 SMPTE-170M, BT.601-6 625 or BT.601-6 525
8458 BT.2020 for 10-bits content
8461 BT.2020 for 12-bits content
8467 Specify output color primaries.
8469 The accepted values are:
8478 BT.470BG or BT.601-6 625
8481 SMPTE-170M or BT.601-6 525
8505 Specify output color range.
8507 The accepted values are:
8510 TV (restricted) range
8513 MPEG (restricted) range
8524 Specify output color format.
8526 The accepted values are:
8529 YUV 4:2:0 planar 8-bits
8532 YUV 4:2:0 planar 10-bits
8535 YUV 4:2:0 planar 12-bits
8538 YUV 4:2:2 planar 8-bits
8541 YUV 4:2:2 planar 10-bits
8544 YUV 4:2:2 planar 12-bits
8547 YUV 4:4:4 planar 8-bits
8550 YUV 4:4:4 planar 10-bits
8553 YUV 4:4:4 planar 12-bits
8558 Do a fast conversion, which skips gamma/primary correction. This will take
8559 significantly less CPU, but will be mathematically incorrect. To get output
8560 compatible with that produced by the colormatrix filter, use fast=1.
8563 Specify dithering mode.
8565 The accepted values are:
8571 Floyd-Steinberg dithering
8575 Whitepoint adaptation mode.
8577 The accepted values are:
8580 Bradford whitepoint adaptation
8583 von Kries whitepoint adaptation
8586 identity whitepoint adaptation (i.e. no whitepoint adaptation)
8590 Override all input properties at once. Same accepted values as @ref{all}.
8593 Override input colorspace. Same accepted values as @ref{space}.
8596 Override input color primaries. Same accepted values as @ref{primaries}.
8599 Override input transfer characteristics. Same accepted values as @ref{trc}.
8602 Override input color range. Same accepted values as @ref{range}.
8606 The filter converts the transfer characteristics, color space and color
8607 primaries to the specified user values. The output value, if not specified,
8608 is set to a default value based on the "all" property. If that property is
8609 also not specified, the filter will log an error. The output color range and
8610 format default to the same value as the input color range and format. The
8611 input transfer characteristics, color space, color primaries and color range
8612 should be set on the input data. If any of these are missing, the filter will
8613 log an error and no conversion will take place.
8615 For example to convert the input to SMPTE-240M, use the command:
8617 colorspace=smpte240m
8620 @section colortemperature
8621 Adjust color temperature in video to simulate variations in ambient color temperature.
8623 The filter accepts the following options:
8627 Set the temperature in Kelvin. Allowed range is from 1000 to 40000.
8628 Default value is 6500 K.
8631 Set mixing with filtered output. Allowed range is from 0 to 1.
8635 Set the amount of preserving lightness. Allowed range is from 0 to 1.
8639 @subsection Commands
8640 This filter supports same @ref{commands} as options.
8642 @section convolution
8644 Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
8646 The filter accepts the following options:
8653 Set matrix for each plane.
8654 Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode,
8655 and from 1 to 49 odd number of signed integers in @var{row} mode.
8661 Set multiplier for calculated value for each plane.
8662 If unset or 0, it will be sum of all matrix elements.
8668 Set bias for each plane. This value is added to the result of the multiplication.
8669 Useful for making the overall image brighter or darker. Default is 0.0.
8675 Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}.
8676 Default is @var{square}.
8679 @subsection Commands
8681 This filter supports the all above options as @ref{commands}.
8683 @subsection Examples
8689 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"
8695 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"
8701 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"
8707 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"
8711 Apply laplacian edge detector which includes diagonals:
8713 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"
8719 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"
8725 Apply 2D convolution of video stream in frequency domain using second stream
8728 The filter accepts the following options:
8732 Set which planes to process.
8735 Set which impulse video frames will be processed, can be @var{first}
8736 or @var{all}. Default is @var{all}.
8739 The @code{convolve} filter also supports the @ref{framesync} options.
8743 Copy the input video source unchanged to the output. This is mainly useful for
8748 Video filtering on GPU using Apple's CoreImage API on OSX.
8750 Hardware acceleration is based on an OpenGL context. Usually, this means it is
8751 processed by video hardware. However, software-based OpenGL implementations
8752 exist which means there is no guarantee for hardware processing. It depends on
8755 There are many filters and image generators provided by Apple that come with a
8756 large variety of options. The filter has to be referenced by its name along
8759 The coreimage filter accepts the following options:
8762 List all available filters and generators along with all their respective
8763 options as well as possible minimum and maximum values along with the default
8770 Specify all filters by their respective name and options.
8771 Use @var{list_filters} to determine all valid filter names and options.
8772 Numerical options are specified by a float value and are automatically clamped
8773 to their respective value range. Vector and color options have to be specified
8774 by a list of space separated float values. Character escaping has to be done.
8775 A special option name @code{default} is available to use default options for a
8778 It is required to specify either @code{default} or at least one of the filter options.
8779 All omitted options are used with their default values.
8780 The syntax of the filter string is as follows:
8782 filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
8786 Specify a rectangle where the output of the filter chain is copied into the
8787 input image. It is given by a list of space separated float values:
8789 output_rect=x\ y\ width\ height
8791 If not given, the output rectangle equals the dimensions of the input image.
8792 The output rectangle is automatically cropped at the borders of the input
8793 image. Negative values are valid for each component.
8795 output_rect=25\ 25\ 100\ 100
8799 Several filters can be chained for successive processing without GPU-HOST
8800 transfers allowing for fast processing of complex filter chains.
8801 Currently, only filters with zero (generators) or exactly one (filters) input
8802 image and one output image are supported. Also, transition filters are not yet
8805 Some filters generate output images with additional padding depending on the
8806 respective filter kernel. The padding is automatically removed to ensure the
8807 filter output has the same size as the input image.
8809 For image generators, the size of the output image is determined by the
8810 previous output image of the filter chain or the input image of the whole
8811 filterchain, respectively. The generators do not use the pixel information of
8812 this image to generate their output. However, the generated output is
8813 blended onto this image, resulting in partial or complete coverage of the
8816 The @ref{coreimagesrc} video source can be used for generating input images
8817 which are directly fed into the filter chain. By using it, providing input
8818 images by another video source or an input video is not required.
8820 @subsection Examples
8825 List all filters available:
8827 coreimage=list_filters=true
8831 Use the CIBoxBlur filter with default options to blur an image:
8833 coreimage=filter=CIBoxBlur@@default
8837 Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
8838 its center at 100x100 and a radius of 50 pixels:
8840 coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
8844 Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
8845 given as complete and escaped command-line for Apple's standard bash shell:
8847 ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
8853 Cover a rectangular object
8855 It accepts the following options:
8859 Filepath of the optional cover image, needs to be in yuv420.
8864 It accepts the following values:
8867 cover it by the supplied image
8869 cover it by interpolating the surrounding pixels
8872 Default value is @var{blur}.
8875 @subsection Examples
8879 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
8881 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
8887 Crop the input video to given dimensions.
8889 It accepts the following parameters:
8893 The width of the output video. It defaults to @code{iw}.
8894 This expression is evaluated only once during the filter
8895 configuration, or when the @samp{w} or @samp{out_w} command is sent.
8898 The height of the output video. It defaults to @code{ih}.
8899 This expression is evaluated only once during the filter
8900 configuration, or when the @samp{h} or @samp{out_h} command is sent.
8903 The horizontal position, in the input video, of the left edge of the output
8904 video. It defaults to @code{(in_w-out_w)/2}.
8905 This expression is evaluated per-frame.
8908 The vertical position, in the input video, of the top edge of the output video.
8909 It defaults to @code{(in_h-out_h)/2}.
8910 This expression is evaluated per-frame.
8913 If set to 1 will force the output display aspect ratio
8914 to be the same of the input, by changing the output sample aspect
8915 ratio. It defaults to 0.
8918 Enable exact cropping. If enabled, subsampled videos will be cropped at exact
8919 width/height/x/y as specified and will not be rounded to nearest smaller value.
8923 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
8924 expressions containing the following constants:
8929 The computed values for @var{x} and @var{y}. They are evaluated for
8934 The input width and height.
8938 These are the same as @var{in_w} and @var{in_h}.
8942 The output (cropped) width and height.
8946 These are the same as @var{out_w} and @var{out_h}.
8949 same as @var{iw} / @var{ih}
8952 input sample aspect ratio
8955 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
8959 horizontal and vertical chroma subsample values. For example for the
8960 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8963 The number of the input frame, starting from 0.
8966 the position in the file of the input frame, NAN if unknown
8969 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
8973 The expression for @var{out_w} may depend on the value of @var{out_h},
8974 and the expression for @var{out_h} may depend on @var{out_w}, but they
8975 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
8976 evaluated after @var{out_w} and @var{out_h}.
8978 The @var{x} and @var{y} parameters specify the expressions for the
8979 position of the top-left corner of the output (non-cropped) area. They
8980 are evaluated for each frame. If the evaluated value is not valid, it
8981 is approximated to the nearest valid value.
8983 The expression for @var{x} may depend on @var{y}, and the expression
8984 for @var{y} may depend on @var{x}.
8986 @subsection Examples
8990 Crop area with size 100x100 at position (12,34).
8995 Using named options, the example above becomes:
8997 crop=w=100:h=100:x=12:y=34
9001 Crop the central input area with size 100x100:
9007 Crop the central input area with size 2/3 of the input video:
9009 crop=2/3*in_w:2/3*in_h
9013 Crop the input video central square:
9020 Delimit the rectangle with the top-left corner placed at position
9021 100:100 and the right-bottom corner corresponding to the right-bottom
9022 corner of the input image.
9024 crop=in_w-100:in_h-100:100:100
9028 Crop 10 pixels from the left and right borders, and 20 pixels from
9029 the top and bottom borders
9031 crop=in_w-2*10:in_h-2*20
9035 Keep only the bottom right quarter of the input image:
9037 crop=in_w/2:in_h/2:in_w/2:in_h/2
9041 Crop height for getting Greek harmony:
9043 crop=in_w:1/PHI*in_w
9047 Apply trembling effect:
9049 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)
9053 Apply erratic camera effect depending on timestamp:
9055 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)"
9059 Set x depending on the value of y:
9061 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
9065 @subsection Commands
9067 This filter supports the following commands:
9073 Set width/height of the output video and the horizontal/vertical position
9075 The command accepts the same syntax of the corresponding option.
9077 If the specified expression is not valid, it is kept at its current
9083 Auto-detect the crop size.
9085 It calculates the necessary cropping parameters and prints the
9086 recommended parameters via the logging system. The detected dimensions
9087 correspond to the non-black area of the input video.
9089 It accepts the following parameters:
9094 Set higher black value threshold, which can be optionally specified
9095 from nothing (0) to everything (255 for 8-bit based formats). An intensity
9096 value greater to the set value is considered non-black. It defaults to 24.
9097 You can also specify a value between 0.0 and 1.0 which will be scaled depending
9098 on the bitdepth of the pixel format.
9101 The value which the width/height should be divisible by. It defaults to
9102 16. The offset is automatically adjusted to center the video. Use 2 to
9103 get only even dimensions (needed for 4:2:2 video). 16 is best when
9104 encoding to most video codecs.
9107 Set the number of initial frames for which evaluation is skipped.
9108 Default is 2. Range is 0 to INT_MAX.
9110 @item reset_count, reset
9111 Set the counter that determines after how many frames cropdetect will
9112 reset the previously detected largest video area and start over to
9113 detect the current optimal crop area. Default value is 0.
9115 This can be useful when channel logos distort the video area. 0
9116 indicates 'never reset', and returns the largest area encountered during
9123 Delay video filtering until a given wallclock timestamp. The filter first
9124 passes on @option{preroll} amount of frames, then it buffers at most
9125 @option{buffer} amount of frames and waits for the cue. After reaching the cue
9126 it forwards the buffered frames and also any subsequent frames coming in its
9129 The filter can be used synchronize the output of multiple ffmpeg processes for
9130 realtime output devices like decklink. By putting the delay in the filtering
9131 chain and pre-buffering frames the process can pass on data to output almost
9132 immediately after the target wallclock timestamp is reached.
9134 Perfect frame accuracy cannot be guaranteed, but the result is good enough for
9140 The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0.
9143 The duration of content to pass on as preroll expressed in seconds. Default is 0.
9146 The maximum duration of content to buffer before waiting for the cue expressed
9147 in seconds. Default is 0.
9154 Apply color adjustments using curves.
9156 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
9157 component (red, green and blue) has its values defined by @var{N} key points
9158 tied from each other using a smooth curve. The x-axis represents the pixel
9159 values from the input frame, and the y-axis the new pixel values to be set for
9162 By default, a component curve is defined by the two points @var{(0;0)} and
9163 @var{(1;1)}. This creates a straight line where each original pixel value is
9164 "adjusted" to its own value, which means no change to the image.
9166 The filter allows you to redefine these two points and add some more. A new
9167 curve (using a natural cubic spline interpolation) will be define to pass
9168 smoothly through all these new coordinates. The new defined points needs to be
9169 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
9170 be in the @var{[0;1]} interval. If the computed curves happened to go outside
9171 the vector spaces, the values will be clipped accordingly.
9173 The filter accepts the following options:
9177 Select one of the available color presets. This option can be used in addition
9178 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
9179 options takes priority on the preset values.
9180 Available presets are:
9183 @item color_negative
9186 @item increase_contrast
9188 @item linear_contrast
9189 @item medium_contrast
9191 @item strong_contrast
9194 Default is @code{none}.
9196 Set the master key points. These points will define a second pass mapping. It
9197 is sometimes called a "luminance" or "value" mapping. It can be used with
9198 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
9199 post-processing LUT.
9201 Set the key points for the red component.
9203 Set the key points for the green component.
9205 Set the key points for the blue component.
9207 Set the key points for all components (not including master).
9208 Can be used in addition to the other key points component
9209 options. In this case, the unset component(s) will fallback on this
9210 @option{all} setting.
9212 Specify a Photoshop curves file (@code{.acv}) to import the settings from.
9214 Save Gnuplot script of the curves in specified file.
9217 To avoid some filtergraph syntax conflicts, each key points list need to be
9218 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
9220 @subsection Examples
9224 Increase slightly the middle level of blue:
9226 curves=blue='0/0 0.5/0.58 1/1'
9232 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'
9234 Here we obtain the following coordinates for each components:
9237 @code{(0;0.11) (0.42;0.51) (1;0.95)}
9239 @code{(0;0) (0.50;0.48) (1;1)}
9241 @code{(0;0.22) (0.49;0.44) (1;0.80)}
9245 The previous example can also be achieved with the associated built-in preset:
9247 curves=preset=vintage
9257 Use a Photoshop preset and redefine the points of the green component:
9259 curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
9263 Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
9264 and @command{gnuplot}:
9266 ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
9267 gnuplot -p /tmp/curves.plt
9273 Video data analysis filter.
9275 This filter shows hexadecimal pixel values of part of video.
9277 The filter accepts the following options:
9281 Set output video size.
9284 Set x offset from where to pick pixels.
9287 Set y offset from where to pick pixels.
9290 Set scope mode, can be one of the following:
9293 Draw hexadecimal pixel values with white color on black background.
9296 Draw hexadecimal pixel values with input video pixel color on black
9300 Draw hexadecimal pixel values on color background picked from input video,
9301 the text color is picked in such way so its always visible.
9305 Draw rows and columns numbers on left and top of video.
9308 Set background opacity.
9311 Set display number format. Can be @code{hex}, or @code{dec}. Default is @code{hex}.
9314 Set pixel components to display. By default all pixel components are displayed.
9318 Apply Directional blur filter.
9320 The filter accepts the following options:
9324 Set angle of directional blur. Default is @code{45}.
9327 Set radius of directional blur. Default is @code{5}.
9330 Set which planes to filter. By default all planes are filtered.
9333 @subsection Commands
9334 This filter supports same @ref{commands} as options.
9335 The command accepts the same syntax of the corresponding option.
9337 If the specified expression is not valid, it is kept at its current
9342 Denoise frames using 2D DCT (frequency domain filtering).
9344 This filter is not designed for real time.
9346 The filter accepts the following options:
9350 Set the noise sigma constant.
9352 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
9353 coefficient (absolute value) below this threshold with be dropped.
9355 If you need a more advanced filtering, see @option{expr}.
9357 Default is @code{0}.
9360 Set number overlapping pixels for each block. Since the filter can be slow, you
9361 may want to reduce this value, at the cost of a less effective filter and the
9362 risk of various artefacts.
9364 If the overlapping value doesn't permit processing the whole input width or
9365 height, a warning will be displayed and according borders won't be denoised.
9367 Default value is @var{blocksize}-1, which is the best possible setting.
9370 Set the coefficient factor expression.
9372 For each coefficient of a DCT block, this expression will be evaluated as a
9373 multiplier value for the coefficient.
9375 If this is option is set, the @option{sigma} option will be ignored.
9377 The absolute value of the coefficient can be accessed through the @var{c}
9381 Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
9382 @var{blocksize}, which is the width and height of the processed blocks.
9384 The default value is @var{3} (8x8) and can be raised to @var{4} for a
9385 @var{blocksize} of 16x16. Note that changing this setting has huge consequences
9386 on the speed processing. Also, a larger block size does not necessarily means a
9390 @subsection Examples
9392 Apply a denoise with a @option{sigma} of @code{4.5}:
9397 The same operation can be achieved using the expression system:
9399 dctdnoiz=e='gte(c, 4.5*3)'
9402 Violent denoise using a block size of @code{16x16}:
9409 Remove banding artifacts from input video.
9410 It works by replacing banded pixels with average value of referenced pixels.
9412 The filter accepts the following options:
9419 Set banding detection threshold for each plane. Default is 0.02.
9420 Valid range is 0.00003 to 0.5.
9421 If difference between current pixel and reference pixel is less than threshold,
9422 it will be considered as banded.
9425 Banding detection range in pixels. Default is 16. If positive, random number
9426 in range 0 to set value will be used. If negative, exact absolute value
9428 The range defines square of four pixels around current pixel.
9431 Set direction in radians from which four pixel will be compared. If positive,
9432 random direction from 0 to set direction will be picked. If negative, exact of
9433 absolute value will be picked. For example direction 0, -PI or -2*PI radians
9434 will pick only pixels on same row and -PI/2 will pick only pixels on same
9438 If enabled, current pixel is compared with average value of all four
9439 surrounding pixels. The default is enabled. If disabled current pixel is
9440 compared with all four surrounding pixels. The pixel is considered banded
9441 if only all four differences with surrounding pixels are less than threshold.
9444 If enabled, current pixel is changed if and only if all pixel components are banded,
9445 e.g. banding detection threshold is triggered for all color components.
9446 The default is disabled.
9451 Remove blocking artifacts from input video.
9453 The filter accepts the following options:
9457 Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}.
9458 This controls what kind of deblocking is applied.
9461 Set size of block, allowed range is from 4 to 512. Default is @var{8}.
9467 Set blocking detection thresholds. Allowed range is 0 to 1.
9468 Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest.
9469 Using higher threshold gives more deblocking strength.
9470 Setting @var{alpha} controls threshold detection at exact edge of block.
9471 Remaining options controls threshold detection near the edge. Each one for
9472 below/above or left/right. Setting any of those to @var{0} disables
9476 Set planes to filter. Default is to filter all available planes.
9479 @subsection Examples
9483 Deblock using weak filter and block size of 4 pixels.
9485 deblock=filter=weak:block=4
9489 Deblock using strong filter, block size of 4 pixels and custom thresholds for
9490 deblocking more edges.
9492 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
9496 Similar as above, but filter only first plane.
9498 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
9502 Similar as above, but filter only second and third plane.
9504 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
9511 Drop duplicated frames at regular intervals.
9513 The filter accepts the following options:
9517 Set the number of frames from which one will be dropped. Setting this to
9518 @var{N} means one frame in every batch of @var{N} frames will be dropped.
9519 Default is @code{5}.
9522 Set the threshold for duplicate detection. If the difference metric for a frame
9523 is less than or equal to this value, then it is declared as duplicate. Default
9527 Set scene change threshold. Default is @code{15}.
9531 Set the size of the x and y-axis blocks used during metric calculations.
9532 Larger blocks give better noise suppression, but also give worse detection of
9533 small movements. Must be a power of two. Default is @code{32}.
9536 Mark main input as a pre-processed input and activate clean source input
9537 stream. This allows the input to be pre-processed with various filters to help
9538 the metrics calculation while keeping the frame selection lossless. When set to
9539 @code{1}, the first stream is for the pre-processed input, and the second
9540 stream is the clean source from where the kept frames are chosen. Default is
9544 Set whether or not chroma is considered in the metric calculations. Default is
9550 Apply 2D deconvolution of video stream in frequency domain using second stream
9553 The filter accepts the following options:
9557 Set which planes to process.
9560 Set which impulse video frames will be processed, can be @var{first}
9561 or @var{all}. Default is @var{all}.
9564 Set noise when doing divisions. Default is @var{0.0000001}. Useful when width
9565 and height are not same and not power of 2 or if stream prior to convolving
9569 The @code{deconvolve} filter also supports the @ref{framesync} options.
9573 Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video.
9575 It accepts the following options:
9579 Set mode of operation. Can be combination of @var{dotcrawl} for cross-luminance reduction and/or
9580 @var{rainbows} for cross-color reduction.
9583 Set spatial luma threshold. Lower values increases reduction of cross-luminance.
9586 Set tolerance for temporal luma. Higher values increases reduction of cross-luminance.
9589 Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color.
9592 Set temporal chroma threshold. Lower values increases reduction of cross-color.
9597 Apply deflate effect to the video.
9599 This filter replaces the pixel by the local(3x3) average by taking into account
9600 only values lower than the pixel.
9602 It accepts the following options:
9609 Limit the maximum change for each plane, default is 65535.
9610 If 0, plane will remain unchanged.
9613 @subsection Commands
9615 This filter supports the all above options as @ref{commands}.
9619 Remove temporal frame luminance variations.
9621 It accepts the following options:
9625 Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129.
9628 Set averaging mode to smooth temporal luminance variations.
9630 Available values are:
9655 Do not actually modify frame. Useful when one only wants metadata.
9660 Remove judder produced by partially interlaced telecined content.
9662 Judder can be introduced, for instance, by @ref{pullup} filter. If the original
9663 source was partially telecined content then the output of @code{pullup,dejudder}
9664 will have a variable frame rate. May change the recorded frame rate of the
9665 container. Aside from that change, this filter will not affect constant frame
9668 The option available in this filter is:
9672 Specify the length of the window over which the judder repeats.
9674 Accepts any integer greater than 1. Useful values are:
9678 If the original was telecined from 24 to 30 fps (Film to NTSC).
9681 If the original was telecined from 25 to 30 fps (PAL to NTSC).
9684 If a mixture of the two.
9687 The default is @samp{4}.
9692 Suppress a TV station logo by a simple interpolation of the surrounding
9693 pixels. Just set a rectangle covering the logo and watch it disappear
9694 (and sometimes something even uglier appear - your mileage may vary).
9696 It accepts the following parameters:
9701 Specify the top left corner coordinates of the logo. They must be
9706 Specify the width and height of the logo to clear. They must be
9710 Specify the thickness of the fuzzy edge of the rectangle (added to
9711 @var{w} and @var{h}). The default value is 1. This option is
9712 deprecated, setting higher values should no longer be necessary and
9716 When set to 1, a green rectangle is drawn on the screen to simplify
9717 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
9718 The default value is 0.
9720 The rectangle is drawn on the outermost pixels which will be (partly)
9721 replaced with interpolated values. The values of the next pixels
9722 immediately outside this rectangle in each direction will be used to
9723 compute the interpolated pixel values inside the rectangle.
9727 @subsection Examples
9731 Set a rectangle covering the area with top left corner coordinates 0,0
9732 and size 100x77, and a band of size 10:
9734 delogo=x=0:y=0:w=100:h=77:band=10
9742 Remove the rain in the input image/video by applying the derain methods based on
9743 convolutional neural networks. Supported models:
9747 Recurrent Squeeze-and-Excitation Context Aggregation Net (RESCAN).
9748 See @url{http://openaccess.thecvf.com/content_ECCV_2018/papers/Xia_Li_Recurrent_Squeeze-and-Excitation_Context_ECCV_2018_paper.pdf}.
9751 Training as well as model generation scripts are provided in
9752 the repository at @url{https://github.com/XueweiMeng/derain_filter.git}.
9754 Native model files (.model) can be generated from TensorFlow model
9755 files (.pb) by using tools/python/convert.py
9757 The filter accepts the following options:
9761 Specify which filter to use. This option accepts the following values:
9765 Derain filter. To conduct derain filter, you need to use a derain model.
9768 Dehaze filter. To conduct dehaze filter, you need to use a dehaze model.
9770 Default value is @samp{derain}.
9773 Specify which DNN backend to use for model loading and execution. This option accepts
9774 the following values:
9778 Native implementation of DNN loading and execution.
9781 TensorFlow backend. To enable this backend you
9782 need to install the TensorFlow for C library (see
9783 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
9784 @code{--enable-libtensorflow}
9786 Default value is @samp{native}.
9789 Set path to model file specifying network architecture and its parameters.
9790 Note that different backends use different file formats. TensorFlow and native
9791 backend can load files for only its format.
9794 It can also be finished with @ref{dnn_processing} filter.
9798 Attempt to fix small changes in horizontal and/or vertical shift. This
9799 filter helps remove camera shake from hand-holding a camera, bumping a
9800 tripod, moving on a vehicle, etc.
9802 The filter accepts the following options:
9810 Specify a rectangular area where to limit the search for motion
9812 If desired the search for motion vectors can be limited to a
9813 rectangular area of the frame defined by its top left corner, width
9814 and height. These parameters have the same meaning as the drawbox
9815 filter which can be used to visualise the position of the bounding
9818 This is useful when simultaneous movement of subjects within the frame
9819 might be confused for camera motion by the motion vector search.
9821 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
9822 then the full frame is used. This allows later options to be set
9823 without specifying the bounding box for the motion vector search.
9825 Default - search the whole frame.
9829 Specify the maximum extent of movement in x and y directions in the
9830 range 0-64 pixels. Default 16.
9833 Specify how to generate pixels to fill blanks at the edge of the
9834 frame. Available values are:
9837 Fill zeroes at blank locations
9839 Original image at blank locations
9841 Extruded edge value at blank locations
9843 Mirrored edge at blank locations
9845 Default value is @samp{mirror}.
9848 Specify the blocksize to use for motion search. Range 4-128 pixels,
9852 Specify the contrast threshold for blocks. Only blocks with more than
9853 the specified contrast (difference between darkest and lightest
9854 pixels) will be considered. Range 1-255, default 125.
9857 Specify the search strategy. Available values are:
9860 Set exhaustive search
9862 Set less exhaustive search.
9864 Default value is @samp{exhaustive}.
9867 If set then a detailed log of the motion search is written to the
9874 Remove unwanted contamination of foreground colors, caused by reflected color of
9875 greenscreen or bluescreen.
9877 This filter accepts the following options:
9881 Set what type of despill to use.
9884 Set how spillmap will be generated.
9887 Set how much to get rid of still remaining spill.
9890 Controls amount of red in spill area.
9893 Controls amount of green in spill area.
9894 Should be -1 for greenscreen.
9897 Controls amount of blue in spill area.
9898 Should be -1 for bluescreen.
9901 Controls brightness of spill area, preserving colors.
9904 Modify alpha from generated spillmap.
9907 @subsection Commands
9909 This filter supports the all above options as @ref{commands}.
9913 Apply an exact inverse of the telecine operation. It requires a predefined
9914 pattern specified using the pattern option which must be the same as that passed
9915 to the telecine filter.
9917 This filter accepts the following options:
9926 The default value is @code{top}.
9930 A string of numbers representing the pulldown pattern you wish to apply.
9931 The default value is @code{23}.
9934 A number representing position of the first frame with respect to the telecine
9935 pattern. This is to be used if the stream is cut. The default value is @code{0}.
9940 Apply dilation effect to the video.
9942 This filter replaces the pixel by the local(3x3) maximum.
9944 It accepts the following options:
9951 Limit the maximum change for each plane, default is 65535.
9952 If 0, plane will remain unchanged.
9955 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
9958 Flags to local 3x3 coordinates maps like this:
9965 @subsection Commands
9967 This filter supports the all above options as @ref{commands}.
9971 Displace pixels as indicated by second and third input stream.
9973 It takes three input streams and outputs one stream, the first input is the
9974 source, and second and third input are displacement maps.
9976 The second input specifies how much to displace pixels along the
9977 x-axis, while the third input specifies how much to displace pixels
9979 If one of displacement map streams terminates, last frame from that
9980 displacement map will be used.
9982 Note that once generated, displacements maps can be reused over and over again.
9984 A description of the accepted options follows.
9988 Set displace behavior for pixels that are out of range.
9990 Available values are:
9993 Missing pixels are replaced by black pixels.
9996 Adjacent pixels will spread out to replace missing pixels.
9999 Out of range pixels are wrapped so they point to pixels of other side.
10002 Out of range pixels will be replaced with mirrored pixels.
10004 Default is @samp{smear}.
10008 @subsection Examples
10012 Add ripple effect to rgb input of video size hd720:
10014 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
10018 Add wave effect to rgb input of video size hd720:
10020 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
10024 @anchor{dnn_processing}
10025 @section dnn_processing
10027 Do image processing with deep neural networks. It works together with another filter
10028 which converts the pixel format of the Frame to what the dnn network requires.
10030 The filter accepts the following options:
10034 Specify which DNN backend to use for model loading and execution. This option accepts
10035 the following values:
10039 Native implementation of DNN loading and execution.
10042 TensorFlow backend. To enable this backend you
10043 need to install the TensorFlow for C library (see
10044 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
10045 @code{--enable-libtensorflow}
10048 OpenVINO backend. To enable this backend you
10049 need to build and install the OpenVINO for C library (see
10050 @url{https://github.com/openvinotoolkit/openvino/blob/master/build-instruction.md}) and configure FFmpeg with
10051 @code{--enable-libopenvino} (--extra-cflags=-I... --extra-ldflags=-L... might
10052 be needed if the header files and libraries are not installed into system path)
10056 Default value is @samp{native}.
10059 Set path to model file specifying network architecture and its parameters.
10060 Note that different backends use different file formats. TensorFlow, OpenVINO and native
10061 backend can load files for only its format.
10063 Native model file (.model) can be generated from TensorFlow model file (.pb) by using tools/python/convert.py
10066 Set the input name of the dnn network.
10069 Set the output name of the dnn network.
10072 use DNN async execution if set (default: set),
10073 roll back to sync execution if the backend does not support async.
10077 @subsection Examples
10081 Remove rain in rgb24 frame with can.pb (see @ref{derain} filter):
10083 ./ffmpeg -i rain.jpg -vf format=rgb24,dnn_processing=dnn_backend=tensorflow:model=can.pb:input=x:output=y derain.jpg
10087 Halve the pixel value of the frame with format gray32f:
10089 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
10093 Handle the Y channel with srcnn.pb (see @ref{sr} filter) for frame with yuv420p (planar YUV formats supported):
10095 ./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
10099 Handle the Y channel with espcn.pb (see @ref{sr} filter), which changes frame size, for format yuv420p (planar YUV formats supported):
10101 ./ffmpeg -i 480p.jpg -vf format=yuv420p,dnn_processing=dnn_backend=tensorflow:model=espcn.pb:input=x:output=y -y tmp.espcn.jpg
10108 Draw a colored box on the input image.
10110 It accepts the following parameters:
10115 The expressions which specify the top left corner coordinates of the box. It defaults to 0.
10119 The expressions which specify the width and height of the box; if 0 they are interpreted as
10120 the input width and height. It defaults to 0.
10123 Specify the color of the box to write. For the general syntax of this option,
10124 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
10125 value @code{invert} is used, the box edge color is the same as the
10126 video with inverted luma.
10129 The expression which sets the thickness of the box edge.
10130 A value of @code{fill} will create a filled box. Default value is @code{3}.
10132 See below for the list of accepted constants.
10135 Applicable if the input has alpha. With value @code{1}, the pixels of the painted box
10136 will overwrite the video's color and alpha pixels.
10137 Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact.
10140 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
10141 following constants:
10145 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
10149 horizontal and vertical chroma subsample values. For example for the
10150 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
10154 The input width and height.
10157 The input sample aspect ratio.
10161 The x and y offset coordinates where the box is drawn.
10165 The width and height of the drawn box.
10168 The thickness of the drawn box.
10170 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
10171 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
10175 @subsection Examples
10179 Draw a black box around the edge of the input image:
10185 Draw a box with color red and an opacity of 50%:
10187 drawbox=10:20:200:60:red@@0.5
10190 The previous example can be specified as:
10192 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
10196 Fill the box with pink color:
10198 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill
10202 Draw a 2-pixel red 2.40:1 mask:
10204 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
10208 @subsection Commands
10209 This filter supports same commands as options.
10210 The command accepts the same syntax of the corresponding option.
10212 If the specified expression is not valid, it is kept at its current
10217 Draw a graph using input video metadata.
10219 It accepts the following parameters:
10223 Set 1st frame metadata key from which metadata values will be used to draw a graph.
10226 Set 1st foreground color expression.
10229 Set 2nd frame metadata key from which metadata values will be used to draw a graph.
10232 Set 2nd foreground color expression.
10235 Set 3rd frame metadata key from which metadata values will be used to draw a graph.
10238 Set 3rd foreground color expression.
10241 Set 4th frame metadata key from which metadata values will be used to draw a graph.
10244 Set 4th foreground color expression.
10247 Set minimal value of metadata value.
10250 Set maximal value of metadata value.
10253 Set graph background color. Default is white.
10258 Available values for mode is:
10265 Default is @code{line}.
10270 Available values for slide is:
10273 Draw new frame when right border is reached.
10276 Replace old columns with new ones.
10279 Scroll from right to left.
10282 Scroll from left to right.
10285 Draw single picture.
10288 Default is @code{frame}.
10291 Set size of graph video. For the syntax of this option, check the
10292 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
10293 The default value is @code{900x256}.
10296 Set the output frame rate. Default value is @code{25}.
10298 The foreground color expressions can use the following variables:
10301 Minimal value of metadata value.
10304 Maximal value of metadata value.
10307 Current metadata key value.
10310 The color is defined as 0xAABBGGRR.
10313 Example using metadata from @ref{signalstats} filter:
10315 signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
10318 Example using metadata from @ref{ebur128} filter:
10320 ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
10325 Draw a grid on the input image.
10327 It accepts the following parameters:
10332 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
10336 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
10337 input width and height, respectively, minus @code{thickness}, so image gets
10338 framed. Default to 0.
10341 Specify the color of the grid. For the general syntax of this option,
10342 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
10343 value @code{invert} is used, the grid color is the same as the
10344 video with inverted luma.
10347 The expression which sets the thickness of the grid line. Default value is @code{1}.
10349 See below for the list of accepted constants.
10352 Applicable if the input has alpha. With @code{1} the pixels of the painted grid
10353 will overwrite the video's color and alpha pixels.
10354 Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact.
10357 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
10358 following constants:
10362 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
10366 horizontal and vertical chroma subsample values. For example for the
10367 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
10371 The input grid cell width and height.
10374 The input sample aspect ratio.
10378 The x and y coordinates of some point of grid intersection (meant to configure offset).
10382 The width and height of the drawn cell.
10385 The thickness of the drawn cell.
10387 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
10388 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
10392 @subsection Examples
10396 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
10398 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
10402 Draw a white 3x3 grid with an opacity of 50%:
10404 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
10408 @subsection Commands
10409 This filter supports same commands as options.
10410 The command accepts the same syntax of the corresponding option.
10412 If the specified expression is not valid, it is kept at its current
10418 Draw a text string or text from a specified file on top of a video, using the
10419 libfreetype library.
10421 To enable compilation of this filter, you need to configure FFmpeg with
10422 @code{--enable-libfreetype}.
10423 To enable default font fallback and the @var{font} option you need to
10424 configure FFmpeg with @code{--enable-libfontconfig}.
10425 To enable the @var{text_shaping} option, you need to configure FFmpeg with
10426 @code{--enable-libfribidi}.
10430 It accepts the following parameters:
10435 Used to draw a box around text using the background color.
10436 The value must be either 1 (enable) or 0 (disable).
10437 The default value of @var{box} is 0.
10440 Set the width of the border to be drawn around the box using @var{boxcolor}.
10441 The default value of @var{boxborderw} is 0.
10444 The color to be used for drawing box around text. For the syntax of this
10445 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
10447 The default value of @var{boxcolor} is "white".
10450 Set the line spacing in pixels of the border to be drawn around the box using @var{box}.
10451 The default value of @var{line_spacing} is 0.
10454 Set the width of the border to be drawn around the text using @var{bordercolor}.
10455 The default value of @var{borderw} is 0.
10458 Set the color to be used for drawing border around text. For the syntax of this
10459 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
10461 The default value of @var{bordercolor} is "black".
10464 Select how the @var{text} is expanded. Can be either @code{none},
10465 @code{strftime} (deprecated) or
10466 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
10470 Set a start time for the count. Value is in microseconds. Only applied
10471 in the deprecated strftime expansion mode. To emulate in normal expansion
10472 mode use the @code{pts} function, supplying the start time (in seconds)
10473 as the second argument.
10476 If true, check and fix text coords to avoid clipping.
10479 The color to be used for drawing fonts. For the syntax of this option, check
10480 the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
10482 The default value of @var{fontcolor} is "black".
10484 @item fontcolor_expr
10485 String which is expanded the same way as @var{text} to obtain dynamic
10486 @var{fontcolor} value. By default this option has empty value and is not
10487 processed. When this option is set, it overrides @var{fontcolor} option.
10490 The font family to be used for drawing text. By default Sans.
10493 The font file to be used for drawing text. The path must be included.
10494 This parameter is mandatory if the fontconfig support is disabled.
10497 Draw the text applying alpha blending. The value can
10498 be a number between 0.0 and 1.0.
10499 The expression accepts the same variables @var{x, y} as well.
10500 The default value is 1.
10501 Please see @var{fontcolor_expr}.
10504 The font size to be used for drawing text.
10505 The default value of @var{fontsize} is 16.
10508 If set to 1, attempt to shape the text (for example, reverse the order of
10509 right-to-left text and join Arabic characters) before drawing it.
10510 Otherwise, just draw the text exactly as given.
10511 By default 1 (if supported).
10513 @item ft_load_flags
10514 The flags to be used for loading the fonts.
10516 The flags map the corresponding flags supported by libfreetype, and are
10517 a combination of the following values:
10524 @item vertical_layout
10525 @item force_autohint
10528 @item ignore_global_advance_width
10530 @item ignore_transform
10532 @item linear_design
10536 Default value is "default".
10538 For more information consult the documentation for the FT_LOAD_*
10542 The color to be used for drawing a shadow behind the drawn text. For the
10543 syntax of this option, check the @ref{color syntax,,"Color" section in the
10544 ffmpeg-utils manual,ffmpeg-utils}.
10546 The default value of @var{shadowcolor} is "black".
10550 The x and y offsets for the text shadow position with respect to the
10551 position of the text. They can be either positive or negative
10552 values. The default value for both is "0".
10555 The starting frame number for the n/frame_num variable. The default value
10559 The size in number of spaces to use for rendering the tab.
10560 Default value is 4.
10563 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
10564 format. It can be used with or without text parameter. @var{timecode_rate}
10565 option must be specified.
10567 @item timecode_rate, rate, r
10568 Set the timecode frame rate (timecode only). Value will be rounded to nearest
10569 integer. Minimum value is "1".
10570 Drop-frame timecode is supported for frame rates 30 & 60.
10573 If set to 1, the output of the timecode option will wrap around at 24 hours.
10574 Default is 0 (disabled).
10577 The text string to be drawn. The text must be a sequence of UTF-8
10578 encoded characters.
10579 This parameter is mandatory if no file is specified with the parameter
10583 A text file containing text to be drawn. The text must be a sequence
10584 of UTF-8 encoded characters.
10586 This parameter is mandatory if no text string is specified with the
10587 parameter @var{text}.
10589 If both @var{text} and @var{textfile} are specified, an error is thrown.
10592 If set to 1, the @var{textfile} will be reloaded before each frame.
10593 Be sure to update it atomically, or it may be read partially, or even fail.
10597 The expressions which specify the offsets where text will be drawn
10598 within the video frame. They are relative to the top/left border of the
10601 The default value of @var{x} and @var{y} is "0".
10603 See below for the list of accepted constants and functions.
10606 The parameters for @var{x} and @var{y} are expressions containing the
10607 following constants and functions:
10611 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
10615 horizontal and vertical chroma subsample values. For example for the
10616 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
10619 the height of each text line
10627 @item max_glyph_a, ascent
10628 the maximum distance from the baseline to the highest/upper grid
10629 coordinate used to place a glyph outline point, for all the rendered
10631 It is a positive value, due to the grid's orientation with the Y axis
10634 @item max_glyph_d, descent
10635 the maximum distance from the baseline to the lowest grid coordinate
10636 used to place a glyph outline point, for all the rendered glyphs.
10637 This is a negative value, due to the grid's orientation, with the Y axis
10641 maximum glyph height, that is the maximum height for all the glyphs
10642 contained in the rendered text, it is equivalent to @var{ascent} -
10646 maximum glyph width, that is the maximum width for all the glyphs
10647 contained in the rendered text
10650 the number of input frame, starting from 0
10652 @item rand(min, max)
10653 return a random number included between @var{min} and @var{max}
10656 The input sample aspect ratio.
10659 timestamp expressed in seconds, NAN if the input timestamp is unknown
10662 the height of the rendered text
10665 the width of the rendered text
10669 the x and y offset coordinates where the text is drawn.
10671 These parameters allow the @var{x} and @var{y} expressions to refer
10672 to each other, so you can for example specify @code{y=x/dar}.
10675 A one character description of the current frame's picture type.
10678 The current packet's position in the input file or stream
10679 (in bytes, from the start of the input). A value of -1 indicates
10680 this info is not available.
10683 The current packet's duration, in seconds.
10686 The current packet's size (in bytes).
10689 @anchor{drawtext_expansion}
10690 @subsection Text expansion
10692 If @option{expansion} is set to @code{strftime},
10693 the filter recognizes strftime() sequences in the provided text and
10694 expands them accordingly. Check the documentation of strftime(). This
10695 feature is deprecated.
10697 If @option{expansion} is set to @code{none}, the text is printed verbatim.
10699 If @option{expansion} is set to @code{normal} (which is the default),
10700 the following expansion mechanism is used.
10702 The backslash character @samp{\}, followed by any character, always expands to
10703 the second character.
10705 Sequences of the form @code{%@{...@}} are expanded. The text between the
10706 braces is a function name, possibly followed by arguments separated by ':'.
10707 If the arguments contain special characters or delimiters (':' or '@}'),
10708 they should be escaped.
10710 Note that they probably must also be escaped as the value for the
10711 @option{text} option in the filter argument string and as the filter
10712 argument in the filtergraph description, and possibly also for the shell,
10713 that makes up to four levels of escaping; using a text file avoids these
10716 The following functions are available:
10721 The expression evaluation result.
10723 It must take one argument specifying the expression to be evaluated,
10724 which accepts the same constants and functions as the @var{x} and
10725 @var{y} values. Note that not all constants should be used, for
10726 example the text size is not known when evaluating the expression, so
10727 the constants @var{text_w} and @var{text_h} will have an undefined
10730 @item expr_int_format, eif
10731 Evaluate the expression's value and output as formatted integer.
10733 The first argument is the expression to be evaluated, just as for the @var{expr} function.
10734 The second argument specifies the output format. Allowed values are @samp{x},
10735 @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
10736 @code{printf} function.
10737 The third parameter is optional and sets the number of positions taken by the output.
10738 It can be used to add padding with zeros from the left.
10741 The time at which the filter is running, expressed in UTC.
10742 It can accept an argument: a strftime() format string.
10745 The time at which the filter is running, expressed in the local time zone.
10746 It can accept an argument: a strftime() format string.
10749 Frame metadata. Takes one or two arguments.
10751 The first argument is mandatory and specifies the metadata key.
10753 The second argument is optional and specifies a default value, used when the
10754 metadata key is not found or empty.
10756 Available metadata can be identified by inspecting entries
10757 starting with TAG included within each frame section
10758 printed by running @code{ffprobe -show_frames}.
10760 String metadata generated in filters leading to
10761 the drawtext filter are also available.
10764 The frame number, starting from 0.
10767 A one character description of the current picture type.
10770 The timestamp of the current frame.
10771 It can take up to three arguments.
10773 The first argument is the format of the timestamp; it defaults to @code{flt}
10774 for seconds as a decimal number with microsecond accuracy; @code{hms} stands
10775 for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
10776 @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
10777 @code{localtime} stands for the timestamp of the frame formatted as
10778 local time zone time.
10780 The second argument is an offset added to the timestamp.
10782 If the format is set to @code{hms}, a third argument @code{24HH} may be
10783 supplied to present the hour part of the formatted timestamp in 24h format
10786 If the format is set to @code{localtime} or @code{gmtime},
10787 a third argument may be supplied: a strftime() format string.
10788 By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
10791 @subsection Commands
10793 This filter supports altering parameters via commands:
10796 Alter existing filter parameters.
10798 Syntax for the argument is the same as for filter invocation, e.g.
10801 fontsize=56:fontcolor=green:text='Hello World'
10804 Full filter invocation with sendcmd would look like this:
10807 sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World'
10811 If the entire argument can't be parsed or applied as valid values then the filter will
10812 continue with its existing parameters.
10814 @subsection Examples
10818 Draw "Test Text" with font FreeSerif, using the default values for the
10819 optional parameters.
10822 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
10826 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
10827 and y=50 (counting from the top-left corner of the screen), text is
10828 yellow with a red box around it. Both the text and the box have an
10832 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
10833 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
10836 Note that the double quotes are not necessary if spaces are not used
10837 within the parameter list.
10840 Show the text at the center of the video frame:
10842 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
10846 Show the text at a random position, switching to a new position every 30 seconds:
10848 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)"
10852 Show a text line sliding from right to left in the last row of the video
10853 frame. The file @file{LONG_LINE} is assumed to contain a single line
10856 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
10860 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
10862 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
10866 Draw a single green letter "g", at the center of the input video.
10867 The glyph baseline is placed at half screen height.
10869 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
10873 Show text for 1 second every 3 seconds:
10875 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
10879 Use fontconfig to set the font. Note that the colons need to be escaped.
10881 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
10885 Draw "Test Text" with font size dependent on height of the video.
10887 drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)"
10891 Print the date of a real-time encoding (see strftime(3)):
10893 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
10897 Show text fading in and out (appearing/disappearing):
10900 DS=1.0 # display start
10901 DE=10.0 # display end
10902 FID=1.5 # fade in duration
10903 FOD=5 # fade out duration
10904 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 @}"
10908 Horizontally align multiple separate texts. Note that @option{max_glyph_a}
10909 and the @option{fontsize} value are included in the @option{y} offset.
10911 drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
10912 drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
10916 Plot special @var{lavf.image2dec.source_basename} metadata onto each frame if
10917 such metadata exists. Otherwise, plot the string "NA". Note that image2 demuxer
10918 must have option @option{-export_path_metadata 1} for the special metadata fields
10919 to be available for filters.
10921 drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%@{metadata\:lavf.image2dec.source_basename\:NA@}':x=10:y=10"
10926 For more information about libfreetype, check:
10927 @url{http://www.freetype.org/}.
10929 For more information about fontconfig, check:
10930 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
10932 For more information about libfribidi, check:
10933 @url{http://fribidi.org/}.
10935 @section edgedetect
10937 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
10939 The filter accepts the following options:
10944 Set low and high threshold values used by the Canny thresholding
10947 The high threshold selects the "strong" edge pixels, which are then
10948 connected through 8-connectivity with the "weak" edge pixels selected
10949 by the low threshold.
10951 @var{low} and @var{high} threshold values must be chosen in the range
10952 [0,1], and @var{low} should be lesser or equal to @var{high}.
10954 Default value for @var{low} is @code{20/255}, and default value for @var{high}
10958 Define the drawing mode.
10962 Draw white/gray wires on black background.
10965 Mix the colors to create a paint/cartoon effect.
10968 Apply Canny edge detector on all selected planes.
10970 Default value is @var{wires}.
10973 Select planes for filtering. By default all available planes are filtered.
10976 @subsection Examples
10980 Standard edge detection with custom values for the hysteresis thresholding:
10982 edgedetect=low=0.1:high=0.4
10986 Painting effect without thresholding:
10988 edgedetect=mode=colormix:high=0
10994 Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
10996 For each input image, the filter will compute the optimal mapping from
10997 the input to the output given the codebook length, that is the number
10998 of distinct output colors.
11000 This filter accepts the following options.
11003 @item codebook_length, l
11004 Set codebook length. The value must be a positive integer, and
11005 represents the number of distinct output colors. Default value is 256.
11008 Set the maximum number of iterations to apply for computing the optimal
11009 mapping. The higher the value the better the result and the higher the
11010 computation time. Default value is 1.
11013 Set a random seed, must be an integer included between 0 and
11014 UINT32_MAX. If not specified, or if explicitly set to -1, the filter
11015 will try to use a good random seed on a best effort basis.
11018 Set pal8 output pixel format. This option does not work with codebook
11019 length greater than 256.
11024 Measure graylevel entropy in histogram of color channels of video frames.
11026 It accepts the following parameters:
11030 Can be either @var{normal} or @var{diff}. Default is @var{normal}.
11032 @var{diff} mode measures entropy of histogram delta values, absolute differences
11033 between neighbour histogram values.
11037 Apply the EPX magnification filter which is designed for pixel art.
11039 It accepts the following option:
11043 Set the scaling dimension: @code{2} for @code{2xEPX}, @code{3} for
11045 Default is @code{3}.
11049 Set brightness, contrast, saturation and approximate gamma adjustment.
11051 The filter accepts the following options:
11055 Set the contrast expression. The value must be a float value in range
11056 @code{-1000.0} to @code{1000.0}. The default value is "1".
11059 Set the brightness expression. The value must be a float value in
11060 range @code{-1.0} to @code{1.0}. The default value is "0".
11063 Set the saturation expression. The value must be a float in
11064 range @code{0.0} to @code{3.0}. The default value is "1".
11067 Set the gamma expression. The value must be a float in range
11068 @code{0.1} to @code{10.0}. The default value is "1".
11071 Set the gamma expression for red. The value must be a float in
11072 range @code{0.1} to @code{10.0}. The default value is "1".
11075 Set the gamma expression for green. The value must be a float in range
11076 @code{0.1} to @code{10.0}. The default value is "1".
11079 Set the gamma expression for blue. The value must be a float in range
11080 @code{0.1} to @code{10.0}. The default value is "1".
11083 Set the gamma weight expression. It can be used to reduce the effect
11084 of a high gamma value on bright image areas, e.g. keep them from
11085 getting overamplified and just plain white. The value must be a float
11086 in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
11087 gamma correction all the way down while @code{1.0} leaves it at its
11088 full strength. Default is "1".
11091 Set when the expressions for brightness, contrast, saturation and
11092 gamma expressions are evaluated.
11094 It accepts the following values:
11097 only evaluate expressions once during the filter initialization or
11098 when a command is processed
11101 evaluate expressions for each incoming frame
11104 Default value is @samp{init}.
11107 The expressions accept the following parameters:
11110 frame count of the input frame starting from 0
11113 byte position of the corresponding packet in the input file, NAN if
11117 frame rate of the input video, NAN if the input frame rate is unknown
11120 timestamp expressed in seconds, NAN if the input timestamp is unknown
11123 @subsection Commands
11124 The filter supports the following commands:
11128 Set the contrast expression.
11131 Set the brightness expression.
11134 Set the saturation expression.
11137 Set the gamma expression.
11140 Set the gamma_r expression.
11143 Set gamma_g expression.
11146 Set gamma_b expression.
11149 Set gamma_weight expression.
11151 The command accepts the same syntax of the corresponding option.
11153 If the specified expression is not valid, it is kept at its current
11160 Apply erosion effect to the video.
11162 This filter replaces the pixel by the local(3x3) minimum.
11164 It accepts the following options:
11171 Limit the maximum change for each plane, default is 65535.
11172 If 0, plane will remain unchanged.
11175 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
11178 Flags to local 3x3 coordinates maps like this:
11185 @subsection Commands
11187 This filter supports the all above options as @ref{commands}.
11191 Deinterlace the input video ("estdif" stands for "Edge Slope
11192 Tracing Deinterlacing Filter").
11194 Spatial only filter that uses edge slope tracing algorithm
11195 to interpolate missing lines.
11196 It accepts the following parameters:
11200 The interlacing mode to adopt. It accepts one of the following values:
11204 Output one frame for each frame.
11206 Output one frame for each field.
11209 The default value is @code{field}.
11212 The picture field parity assumed for the input interlaced video. It accepts one
11213 of the following values:
11217 Assume the top field is first.
11219 Assume the bottom field is first.
11221 Enable automatic detection of field parity.
11224 The default value is @code{auto}.
11225 If the interlacing is unknown or the decoder does not export this information,
11226 top field first will be assumed.
11229 Specify which frames to deinterlace. Accepts one of the following
11234 Deinterlace all frames.
11236 Only deinterlace frames marked as interlaced.
11239 The default value is @code{all}.
11242 Specify the search radius for edge slope tracing. Default value is 1.
11243 Allowed range is from 1 to 15.
11246 Specify the search radius for best edge matching. Default value is 2.
11247 Allowed range is from 0 to 15.
11250 Specify the interpolation used. Default is 4-point interpolation. It accepts one
11251 of the following values:
11255 Two-point interpolation.
11257 Four-point interpolation.
11259 Six-point interpolation.
11263 @subsection Commands
11264 This filter supports same @ref{commands} as options.
11266 @section extractplanes
11268 Extract color channel components from input video stream into
11269 separate grayscale video streams.
11271 The filter accepts the following option:
11275 Set plane(s) to extract.
11277 Available values for planes are:
11288 Choosing planes not available in the input will result in an error.
11289 That means you cannot select @code{r}, @code{g}, @code{b} planes
11290 with @code{y}, @code{u}, @code{v} planes at same time.
11293 @subsection Examples
11297 Extract luma, u and v color channel component from input video frame
11298 into 3 grayscale outputs:
11300 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
11306 Apply a fade-in/out effect to the input video.
11308 It accepts the following parameters:
11312 The effect type can be either "in" for a fade-in, or "out" for a fade-out
11314 Default is @code{in}.
11316 @item start_frame, s
11317 Specify the number of the frame to start applying the fade
11318 effect at. Default is 0.
11321 The number of frames that the fade effect lasts. At the end of the
11322 fade-in effect, the output video will have the same intensity as the input video.
11323 At the end of the fade-out transition, the output video will be filled with the
11324 selected @option{color}.
11328 If set to 1, fade only alpha channel, if one exists on the input.
11329 Default value is 0.
11331 @item start_time, st
11332 Specify the timestamp (in seconds) of the frame to start to apply the fade
11333 effect. If both start_frame and start_time are specified, the fade will start at
11334 whichever comes last. Default is 0.
11337 The number of seconds for which the fade effect has to last. At the end of the
11338 fade-in effect the output video will have the same intensity as the input video,
11339 at the end of the fade-out transition the output video will be filled with the
11340 selected @option{color}.
11341 If both duration and nb_frames are specified, duration is used. Default is 0
11342 (nb_frames is used by default).
11345 Specify the color of the fade. Default is "black".
11348 @subsection Examples
11352 Fade in the first 30 frames of video:
11357 The command above is equivalent to:
11363 Fade out the last 45 frames of a 200-frame video:
11366 fade=type=out:start_frame=155:nb_frames=45
11370 Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
11372 fade=in:0:25, fade=out:975:25
11376 Make the first 5 frames yellow, then fade in from frame 5-24:
11378 fade=in:5:20:color=yellow
11382 Fade in alpha over first 25 frames of video:
11384 fade=in:0:25:alpha=1
11388 Make the first 5.5 seconds black, then fade in for 0.5 seconds:
11390 fade=t=in:st=5.5:d=0.5
11396 Denoise frames using 3D FFT (frequency domain filtering).
11398 The filter accepts the following options:
11402 Set the noise sigma constant. This sets denoising strength.
11403 Default value is 1. Allowed range is from 0 to 30.
11404 Using very high sigma with low overlap may give blocking artifacts.
11407 Set amount of denoising. By default all detected noise is reduced.
11408 Default value is 1. Allowed range is from 0 to 1.
11411 Set size of block, Default is 4, can be 3, 4, 5 or 6.
11412 Actual size of block in pixels is 2 to power of @var{block}, so by default
11413 block size in pixels is 2^4 which is 16.
11416 Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8.
11419 Set number of previous frames to use for denoising. By default is set to 0.
11422 Set number of next frames to to use for denoising. By default is set to 0.
11425 Set planes which will be filtered, by default are all available filtered
11430 Apply arbitrary expressions to samples in frequency domain
11434 Adjust the dc value (gain) of the luma plane of the image. The filter
11435 accepts an integer value in range @code{0} to @code{1000}. The default
11436 value is set to @code{0}.
11439 Adjust the dc value (gain) of the 1st chroma plane of the image. The
11440 filter accepts an integer value in range @code{0} to @code{1000}. The
11441 default value is set to @code{0}.
11444 Adjust the dc value (gain) of the 2nd chroma plane of the image. The
11445 filter accepts an integer value in range @code{0} to @code{1000}. The
11446 default value is set to @code{0}.
11449 Set the frequency domain weight expression for the luma plane.
11452 Set the frequency domain weight expression for the 1st chroma plane.
11455 Set the frequency domain weight expression for the 2nd chroma plane.
11458 Set when the expressions are evaluated.
11460 It accepts the following values:
11463 Only evaluate expressions once during the filter initialization.
11466 Evaluate expressions for each incoming frame.
11469 Default value is @samp{init}.
11471 The filter accepts the following variables:
11474 The coordinates of the current sample.
11478 The width and height of the image.
11481 The number of input frame, starting from 0.
11484 @subsection Examples
11490 fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
11496 fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
11502 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
11508 fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
11515 Extract a single field from an interlaced image using stride
11516 arithmetic to avoid wasting CPU time. The output frames are marked as
11519 The filter accepts the following options:
11523 Specify whether to extract the top (if the value is @code{0} or
11524 @code{top}) or the bottom field (if the value is @code{1} or
11530 Create new frames by copying the top and bottom fields from surrounding frames
11531 supplied as numbers by the hint file.
11535 Set file containing hints: absolute/relative frame numbers.
11537 There must be one line for each frame in a clip. Each line must contain two
11538 numbers separated by the comma, optionally followed by @code{-} or @code{+}.
11539 Numbers supplied on each line of file can not be out of [N-1,N+1] where N
11540 is current frame number for @code{absolute} mode or out of [-1, 1] range
11541 for @code{relative} mode. First number tells from which frame to pick up top
11542 field and second number tells from which frame to pick up bottom field.
11544 If optionally followed by @code{+} output frame will be marked as interlaced,
11545 else if followed by @code{-} output frame will be marked as progressive, else
11546 it will be marked same as input frame.
11547 If optionally followed by @code{t} output frame will use only top field, or in
11548 case of @code{b} it will use only bottom field.
11549 If line starts with @code{#} or @code{;} that line is skipped.
11552 Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
11555 Example of first several lines of @code{hint} file for @code{relative} mode:
11557 0,0 - # first frame
11558 1,0 - # second frame, use third's frame top field and second's frame bottom field
11559 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
11574 @section fieldmatch
11576 Field matching filter for inverse telecine. It is meant to reconstruct the
11577 progressive frames from a telecined stream. The filter does not drop duplicated
11578 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
11579 followed by a decimation filter such as @ref{decimate} in the filtergraph.
11581 The separation of the field matching and the decimation is notably motivated by
11582 the possibility of inserting a de-interlacing filter fallback between the two.
11583 If the source has mixed telecined and real interlaced content,
11584 @code{fieldmatch} will not be able to match fields for the interlaced parts.
11585 But these remaining combed frames will be marked as interlaced, and thus can be
11586 de-interlaced by a later filter such as @ref{yadif} before decimation.
11588 In addition to the various configuration options, @code{fieldmatch} can take an
11589 optional second stream, activated through the @option{ppsrc} option. If
11590 enabled, the frames reconstruction will be based on the fields and frames from
11591 this second stream. This allows the first input to be pre-processed in order to
11592 help the various algorithms of the filter, while keeping the output lossless
11593 (assuming the fields are matched properly). Typically, a field-aware denoiser,
11594 or brightness/contrast adjustments can help.
11596 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
11597 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
11598 which @code{fieldmatch} is based on. While the semantic and usage are very
11599 close, some behaviour and options names can differ.
11601 The @ref{decimate} filter currently only works for constant frame rate input.
11602 If your input has mixed telecined (30fps) and progressive content with a lower
11603 framerate like 24fps use the following filterchain to produce the necessary cfr
11604 stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
11606 The filter accepts the following options:
11610 Specify the assumed field order of the input stream. Available values are:
11614 Auto detect parity (use FFmpeg's internal parity value).
11616 Assume bottom field first.
11618 Assume top field first.
11621 Note that it is sometimes recommended not to trust the parity announced by the
11624 Default value is @var{auto}.
11627 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
11628 sense that it won't risk creating jerkiness due to duplicate frames when
11629 possible, but if there are bad edits or blended fields it will end up
11630 outputting combed frames when a good match might actually exist. On the other
11631 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
11632 but will almost always find a good frame if there is one. The other values are
11633 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
11634 jerkiness and creating duplicate frames versus finding good matches in sections
11635 with bad edits, orphaned fields, blended fields, etc.
11637 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
11639 Available values are:
11643 2-way matching (p/c)
11645 2-way matching, and trying 3rd match if still combed (p/c + n)
11647 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
11649 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
11650 still combed (p/c + n + u/b)
11652 3-way matching (p/c/n)
11654 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
11655 detected as combed (p/c/n + u/b)
11658 The parenthesis at the end indicate the matches that would be used for that
11659 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
11662 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
11665 Default value is @var{pc_n}.
11668 Mark the main input stream as a pre-processed input, and enable the secondary
11669 input stream as the clean source to pick the fields from. See the filter
11670 introduction for more details. It is similar to the @option{clip2} feature from
11673 Default value is @code{0} (disabled).
11676 Set the field to match from. It is recommended to set this to the same value as
11677 @option{order} unless you experience matching failures with that setting. In
11678 certain circumstances changing the field that is used to match from can have a
11679 large impact on matching performance. Available values are:
11683 Automatic (same value as @option{order}).
11685 Match from the bottom field.
11687 Match from the top field.
11690 Default value is @var{auto}.
11693 Set whether or not chroma is included during the match comparisons. In most
11694 cases it is recommended to leave this enabled. You should set this to @code{0}
11695 only if your clip has bad chroma problems such as heavy rainbowing or other
11696 artifacts. Setting this to @code{0} could also be used to speed things up at
11697 the cost of some accuracy.
11699 Default value is @code{1}.
11703 These define an exclusion band which excludes the lines between @option{y0} and
11704 @option{y1} from being included in the field matching decision. An exclusion
11705 band can be used to ignore subtitles, a logo, or other things that may
11706 interfere with the matching. @option{y0} sets the starting scan line and
11707 @option{y1} sets the ending line; all lines in between @option{y0} and
11708 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
11709 @option{y0} and @option{y1} to the same value will disable the feature.
11710 @option{y0} and @option{y1} defaults to @code{0}.
11713 Set the scene change detection threshold as a percentage of maximum change on
11714 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
11715 detection is only relevant in case @option{combmatch}=@var{sc}. The range for
11716 @option{scthresh} is @code{[0.0, 100.0]}.
11718 Default value is @code{12.0}.
11721 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
11722 account the combed scores of matches when deciding what match to use as the
11723 final match. Available values are:
11727 No final matching based on combed scores.
11729 Combed scores are only used when a scene change is detected.
11731 Use combed scores all the time.
11734 Default is @var{sc}.
11737 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
11738 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
11739 Available values are:
11743 No forced calculation.
11745 Force p/c/n calculations.
11747 Force p/c/n/u/b calculations.
11750 Default value is @var{none}.
11753 This is the area combing threshold used for combed frame detection. This
11754 essentially controls how "strong" or "visible" combing must be to be detected.
11755 Larger values mean combing must be more visible and smaller values mean combing
11756 can be less visible or strong and still be detected. Valid settings are from
11757 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
11758 be detected as combed). This is basically a pixel difference value. A good
11759 range is @code{[8, 12]}.
11761 Default value is @code{9}.
11764 Sets whether or not chroma is considered in the combed frame decision. Only
11765 disable this if your source has chroma problems (rainbowing, etc.) that are
11766 causing problems for the combed frame detection with chroma enabled. Actually,
11767 using @option{chroma}=@var{0} is usually more reliable, except for the case
11768 where there is chroma only combing in the source.
11770 Default value is @code{0}.
11774 Respectively set the x-axis and y-axis size of the window used during combed
11775 frame detection. This has to do with the size of the area in which
11776 @option{combpel} pixels are required to be detected as combed for a frame to be
11777 declared combed. See the @option{combpel} parameter description for more info.
11778 Possible values are any number that is a power of 2 starting at 4 and going up
11781 Default value is @code{16}.
11784 The number of combed pixels inside any of the @option{blocky} by
11785 @option{blockx} size blocks on the frame for the frame to be detected as
11786 combed. While @option{cthresh} controls how "visible" the combing must be, this
11787 setting controls "how much" combing there must be in any localized area (a
11788 window defined by the @option{blockx} and @option{blocky} settings) on the
11789 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
11790 which point no frames will ever be detected as combed). This setting is known
11791 as @option{MI} in TFM/VFM vocabulary.
11793 Default value is @code{80}.
11796 @anchor{p/c/n/u/b meaning}
11797 @subsection p/c/n/u/b meaning
11799 @subsubsection p/c/n
11801 We assume the following telecined stream:
11804 Top fields: 1 2 2 3 4
11805 Bottom fields: 1 2 3 4 4
11808 The numbers correspond to the progressive frame the fields relate to. Here, the
11809 first two frames are progressive, the 3rd and 4th are combed, and so on.
11811 When @code{fieldmatch} is configured to run a matching from bottom
11812 (@option{field}=@var{bottom}) this is how this input stream get transformed:
11817 B 1 2 3 4 4 <-- matching reference
11826 As a result of the field matching, we can see that some frames get duplicated.
11827 To perform a complete inverse telecine, you need to rely on a decimation filter
11828 after this operation. See for instance the @ref{decimate} filter.
11830 The same operation now matching from top fields (@option{field}=@var{top})
11835 T 1 2 2 3 4 <-- matching reference
11845 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
11846 basically, they refer to the frame and field of the opposite parity:
11849 @item @var{p} matches the field of the opposite parity in the previous frame
11850 @item @var{c} matches the field of the opposite parity in the current frame
11851 @item @var{n} matches the field of the opposite parity in the next frame
11856 The @var{u} and @var{b} matching are a bit special in the sense that they match
11857 from the opposite parity flag. In the following examples, we assume that we are
11858 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
11859 'x' is placed above and below each matched fields.
11861 With bottom matching (@option{field}=@var{bottom}):
11866 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
11867 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
11875 With top matching (@option{field}=@var{top}):
11880 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
11881 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
11889 @subsection Examples
11891 Simple IVTC of a top field first telecined stream:
11893 fieldmatch=order=tff:combmatch=none, decimate
11896 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
11898 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
11901 @section fieldorder
11903 Transform the field order of the input video.
11905 It accepts the following parameters:
11910 The output field order. Valid values are @var{tff} for top field first or @var{bff}
11911 for bottom field first.
11914 The default value is @samp{tff}.
11916 The transformation is done by shifting the picture content up or down
11917 by one line, and filling the remaining line with appropriate picture content.
11918 This method is consistent with most broadcast field order converters.
11920 If the input video is not flagged as being interlaced, or it is already
11921 flagged as being of the required output field order, then this filter does
11922 not alter the incoming video.
11924 It is very useful when converting to or from PAL DV material,
11925 which is bottom field first.
11929 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
11932 @section fifo, afifo
11934 Buffer input images and send them when they are requested.
11936 It is mainly useful when auto-inserted by the libavfilter
11939 It does not take parameters.
11941 @section fillborders
11943 Fill borders of the input video, without changing video stream dimensions.
11944 Sometimes video can have garbage at the four edges and you may not want to
11945 crop video input to keep size multiple of some number.
11947 This filter accepts the following options:
11951 Number of pixels to fill from left border.
11954 Number of pixels to fill from right border.
11957 Number of pixels to fill from top border.
11960 Number of pixels to fill from bottom border.
11965 It accepts the following values:
11968 fill pixels using outermost pixels
11971 fill pixels using mirroring (half sample symmetric)
11974 fill pixels with constant value
11977 fill pixels using reflecting (whole sample symmetric)
11980 fill pixels using wrapping
11983 fade pixels to constant value
11986 Default is @var{smear}.
11989 Set color for pixels in fixed or fade mode. Default is @var{black}.
11992 @subsection Commands
11993 This filter supports same @ref{commands} as options.
11994 The command accepts the same syntax of the corresponding option.
11996 If the specified expression is not valid, it is kept at its current
12001 Find a rectangular object
12003 It accepts the following options:
12007 Filepath of the object image, needs to be in gray8.
12010 Detection threshold, default is 0.5.
12013 Number of mipmaps, default is 3.
12015 @item xmin, ymin, xmax, ymax
12016 Specifies the rectangle in which to search.
12019 @subsection Examples
12023 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
12025 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
12031 Flood area with values of same pixel components with another values.
12033 It accepts the following options:
12036 Set pixel x coordinate.
12039 Set pixel y coordinate.
12042 Set source #0 component value.
12045 Set source #1 component value.
12048 Set source #2 component value.
12051 Set source #3 component value.
12054 Set destination #0 component value.
12057 Set destination #1 component value.
12060 Set destination #2 component value.
12063 Set destination #3 component value.
12069 Convert the input video to one of the specified pixel formats.
12070 Libavfilter will try to pick one that is suitable as input to
12073 It accepts the following parameters:
12077 A '|'-separated list of pixel format names, such as
12078 "pix_fmts=yuv420p|monow|rgb24".
12082 @subsection Examples
12086 Convert the input video to the @var{yuv420p} format
12088 format=pix_fmts=yuv420p
12091 Convert the input video to any of the formats in the list
12093 format=pix_fmts=yuv420p|yuv444p|yuv410p
12100 Convert the video to specified constant frame rate by duplicating or dropping
12101 frames as necessary.
12103 It accepts the following parameters:
12107 The desired output frame rate. The default is @code{25}.
12110 Assume the first PTS should be the given value, in seconds. This allows for
12111 padding/trimming at the start of stream. By default, no assumption is made
12112 about the first frame's expected PTS, so no padding or trimming is done.
12113 For example, this could be set to 0 to pad the beginning with duplicates of
12114 the first frame if a video stream starts after the audio stream or to trim any
12115 frames with a negative PTS.
12118 Timestamp (PTS) rounding method.
12120 Possible values are:
12127 round towards -infinity
12129 round towards +infinity
12133 The default is @code{near}.
12136 Action performed when reading the last frame.
12138 Possible values are:
12141 Use same timestamp rounding method as used for other frames.
12143 Pass through last frame if input duration has not been reached yet.
12145 The default is @code{round}.
12149 Alternatively, the options can be specified as a flat string:
12150 @var{fps}[:@var{start_time}[:@var{round}]].
12152 See also the @ref{setpts} filter.
12154 @subsection Examples
12158 A typical usage in order to set the fps to 25:
12164 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
12166 fps=fps=film:round=near
12172 Pack two different video streams into a stereoscopic video, setting proper
12173 metadata on supported codecs. The two views should have the same size and
12174 framerate and processing will stop when the shorter video ends. Please note
12175 that you may conveniently adjust view properties with the @ref{scale} and
12178 It accepts the following parameters:
12182 The desired packing format. Supported values are:
12187 The views are next to each other (default).
12190 The views are on top of each other.
12193 The views are packed by line.
12196 The views are packed by column.
12199 The views are temporally interleaved.
12208 # Convert left and right views into a frame-sequential video
12209 ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
12211 # Convert views into a side-by-side video with the same output resolution as the input
12212 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
12217 Change the frame rate by interpolating new video output frames from the source
12220 This filter is not designed to function correctly with interlaced media. If
12221 you wish to change the frame rate of interlaced media then you are required
12222 to deinterlace before this filter and re-interlace after this filter.
12224 A description of the accepted options follows.
12228 Specify the output frames per second. This option can also be specified
12229 as a value alone. The default is @code{50}.
12232 Specify the start of a range where the output frame will be created as a
12233 linear interpolation of two frames. The range is [@code{0}-@code{255}],
12234 the default is @code{15}.
12237 Specify the end of a range where the output frame will be created as a
12238 linear interpolation of two frames. The range is [@code{0}-@code{255}],
12239 the default is @code{240}.
12242 Specify the level at which a scene change is detected as a value between
12243 0 and 100 to indicate a new scene; a low value reflects a low
12244 probability for the current frame to introduce a new scene, while a higher
12245 value means the current frame is more likely to be one.
12246 The default is @code{8.2}.
12249 Specify flags influencing the filter process.
12251 Available value for @var{flags} is:
12254 @item scene_change_detect, scd
12255 Enable scene change detection using the value of the option @var{scene}.
12256 This flag is enabled by default.
12262 Select one frame every N-th frame.
12264 This filter accepts the following option:
12267 Select frame after every @code{step} frames.
12268 Allowed values are positive integers higher than 0. Default value is @code{1}.
12271 @section freezedetect
12273 Detect frozen video.
12275 This filter logs a message and sets frame metadata when it detects that the
12276 input video has no significant change in content during a specified duration.
12277 Video freeze detection calculates the mean average absolute difference of all
12278 the components of video frames and compares it to a noise floor.
12280 The printed times and duration are expressed in seconds. The
12281 @code{lavfi.freezedetect.freeze_start} metadata key is set on the first frame
12282 whose timestamp equals or exceeds the detection duration and it contains the
12283 timestamp of the first frame of the freeze. The
12284 @code{lavfi.freezedetect.freeze_duration} and
12285 @code{lavfi.freezedetect.freeze_end} metadata keys are set on the first frame
12288 The filter accepts the following options:
12292 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
12293 specified value) or as a difference ratio between 0 and 1. Default is -60dB, or
12297 Set freeze duration until notification (default is 2 seconds).
12300 @section freezeframes
12302 Freeze video frames.
12304 This filter freezes video frames using frame from 2nd input.
12306 The filter accepts the following options:
12310 Set number of first frame from which to start freeze.
12313 Set number of last frame from which to end freeze.
12316 Set number of frame from 2nd input which will be used instead of replaced frames.
12322 Apply a frei0r effect to the input video.
12324 To enable the compilation of this filter, you need to install the frei0r
12325 header and configure FFmpeg with @code{--enable-frei0r}.
12327 It accepts the following parameters:
12332 The name of the frei0r effect to load. If the environment variable
12333 @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
12334 directories specified by the colon-separated list in @env{FREI0R_PATH}.
12335 Otherwise, the standard frei0r paths are searched, in this order:
12336 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
12337 @file{/usr/lib/frei0r-1/}.
12339 @item filter_params
12340 A '|'-separated list of parameters to pass to the frei0r effect.
12344 A frei0r effect parameter can be a boolean (its value is either
12345 "y" or "n"), a double, a color (specified as
12346 @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
12347 numbers between 0.0 and 1.0, inclusive) or a color description as specified in the
12348 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils},
12349 a position (specified as @var{X}/@var{Y}, where
12350 @var{X} and @var{Y} are floating point numbers) and/or a string.
12352 The number and types of parameters depend on the loaded effect. If an
12353 effect parameter is not specified, the default value is set.
12355 @subsection Examples
12359 Apply the distort0r effect, setting the first two double parameters:
12361 frei0r=filter_name=distort0r:filter_params=0.5|0.01
12365 Apply the colordistance effect, taking a color as the first parameter:
12367 frei0r=colordistance:0.2/0.3/0.4
12368 frei0r=colordistance:violet
12369 frei0r=colordistance:0x112233
12373 Apply the perspective effect, specifying the top left and top right image
12376 frei0r=perspective:0.2/0.2|0.8/0.2
12380 For more information, see
12381 @url{http://frei0r.dyne.org}
12383 @subsection Commands
12385 This filter supports the @option{filter_params} option as @ref{commands}.
12389 Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
12391 It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
12392 processing filter, one of them is performed once per block, not per pixel.
12393 This allows for much higher speed.
12395 The filter accepts the following options:
12399 Set quality. This option defines the number of levels for averaging. It accepts
12400 an integer in the range 4-5. Default value is @code{4}.
12403 Force a constant quantization parameter. It accepts an integer in range 0-63.
12404 If not set, the filter will use the QP from the video stream (if available).
12407 Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
12408 more details but also more artifacts, while higher values make the image smoother
12409 but also blurrier. Default value is @code{0} − PSNR optimal.
12411 @item use_bframe_qp
12412 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
12413 option may cause flicker since the B-Frames have often larger QP. Default is
12414 @code{0} (not enabled).
12420 Apply Gaussian blur filter.
12422 The filter accepts the following options:
12426 Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
12429 Set number of steps for Gaussian approximation. Default is @code{1}.
12432 Set which planes to filter. By default all planes are filtered.
12435 Set vertical sigma, if negative it will be same as @code{sigma}.
12436 Default is @code{-1}.
12439 @subsection Commands
12440 This filter supports same commands as options.
12441 The command accepts the same syntax of the corresponding option.
12443 If the specified expression is not valid, it is kept at its current
12448 Apply generic equation to each pixel.
12450 The filter accepts the following options:
12453 @item lum_expr, lum
12454 Set the luminance expression.
12456 Set the chrominance blue expression.
12458 Set the chrominance red expression.
12459 @item alpha_expr, a
12460 Set the alpha expression.
12462 Set the red expression.
12463 @item green_expr, g
12464 Set the green expression.
12466 Set the blue expression.
12469 The colorspace is selected according to the specified options. If one
12470 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
12471 options is specified, the filter will automatically select a YCbCr
12472 colorspace. If one of the @option{red_expr}, @option{green_expr}, or
12473 @option{blue_expr} options is specified, it will select an RGB
12476 If one of the chrominance expression is not defined, it falls back on the other
12477 one. If no alpha expression is specified it will evaluate to opaque value.
12478 If none of chrominance expressions are specified, they will evaluate
12479 to the luminance expression.
12481 The expressions can use the following variables and functions:
12485 The sequential number of the filtered frame, starting from @code{0}.
12489 The coordinates of the current sample.
12493 The width and height of the image.
12497 Width and height scale depending on the currently filtered plane. It is the
12498 ratio between the corresponding luma plane number of pixels and the current
12499 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
12500 @code{0.5,0.5} for chroma planes.
12503 Time of the current frame, expressed in seconds.
12506 Return the value of the pixel at location (@var{x},@var{y}) of the current
12510 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
12514 Return the value of the pixel at location (@var{x},@var{y}) of the
12515 blue-difference chroma plane. Return 0 if there is no such plane.
12518 Return the value of the pixel at location (@var{x},@var{y}) of the
12519 red-difference chroma plane. Return 0 if there is no such plane.
12524 Return the value of the pixel at location (@var{x},@var{y}) of the
12525 red/green/blue component. Return 0 if there is no such component.
12528 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
12529 plane. Return 0 if there is no such plane.
12531 @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)
12532 Sum of sample values in the rectangle from (0,0) to (x,y), this allows obtaining
12533 sums of samples within a rectangle. See the functions without the sum postfix.
12535 @item interpolation
12536 Set one of interpolation methods:
12541 Default is bilinear.
12544 For functions, if @var{x} and @var{y} are outside the area, the value will be
12545 automatically clipped to the closer edge.
12547 Please note that this filter can use multiple threads in which case each slice
12548 will have its own expression state. If you want to use only a single expression
12549 state because your expressions depend on previous state then you should limit
12550 the number of filter threads to 1.
12552 @subsection Examples
12556 Flip the image horizontally:
12562 Generate a bidimensional sine wave, with angle @code{PI/3} and a
12563 wavelength of 100 pixels:
12565 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
12569 Generate a fancy enigmatic moving light:
12571 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
12575 Generate a quick emboss effect:
12577 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
12581 Modify RGB components depending on pixel position:
12583 geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
12587 Create a radial gradient that is the same size as the input (also see
12588 the @ref{vignette} filter):
12590 geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
12596 Fix the banding artifacts that are sometimes introduced into nearly flat
12597 regions by truncation to 8-bit color depth.
12598 Interpolate the gradients that should go where the bands are, and
12601 It is designed for playback only. Do not use it prior to
12602 lossy compression, because compression tends to lose the dither and
12603 bring back the bands.
12605 It accepts the following parameters:
12610 The maximum amount by which the filter will change any one pixel. This is also
12611 the threshold for detecting nearly flat regions. Acceptable values range from
12612 .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
12616 The neighborhood to fit the gradient to. A larger radius makes for smoother
12617 gradients, but also prevents the filter from modifying the pixels near detailed
12618 regions. Acceptable values are 8-32; the default value is 16. Out-of-range
12619 values will be clipped to the valid range.
12623 Alternatively, the options can be specified as a flat string:
12624 @var{strength}[:@var{radius}]
12626 @subsection Examples
12630 Apply the filter with a @code{3.5} strength and radius of @code{8}:
12636 Specify radius, omitting the strength (which will fall-back to the default
12644 @anchor{graphmonitor}
12645 @section graphmonitor
12646 Show various filtergraph stats.
12648 With this filter one can debug complete filtergraph.
12649 Especially issues with links filling with queued frames.
12651 The filter accepts the following options:
12655 Set video output size. Default is @var{hd720}.
12658 Set video opacity. Default is @var{0.9}. Allowed range is from @var{0} to @var{1}.
12661 Set output mode, can be @var{fulll} or @var{compact}.
12662 In @var{compact} mode only filters with some queued frames have displayed stats.
12665 Set flags which enable which stats are shown in video.
12667 Available values for flags are:
12670 Display number of queued frames in each link.
12672 @item frame_count_in
12673 Display number of frames taken from filter.
12675 @item frame_count_out
12676 Display number of frames given out from filter.
12679 Display current filtered frame pts.
12682 Display current filtered frame time.
12685 Display time base for filter link.
12688 Display used format for filter link.
12691 Display video size or number of audio channels in case of audio used by filter link.
12694 Display video frame rate or sample rate in case of audio used by filter link.
12697 Display link output status.
12701 Set upper limit for video rate of output stream, Default value is @var{25}.
12702 This guarantee that output video frame rate will not be higher than this value.
12706 A color constancy variation filter which estimates scene illumination via grey edge algorithm
12707 and corrects the scene colors accordingly.
12709 See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf}
12711 The filter accepts the following options:
12715 The order of differentiation to be applied on the scene. Must be chosen in the range
12716 [0,2] and default value is 1.
12719 The Minkowski parameter to be used for calculating the Minkowski distance. Must
12720 be chosen in the range [0,20] and default value is 1. Set to 0 for getting
12721 max value instead of calculating Minkowski distance.
12724 The standard deviation of Gaussian blur to be applied on the scene. Must be
12725 chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) )
12726 can't be equal to 0 if @var{difford} is greater than 0.
12729 @subsection Examples
12735 greyedge=difford=1:minknorm=5:sigma=2
12741 greyedge=difford=1:minknorm=0:sigma=2
12749 Apply a Hald CLUT to a video stream.
12751 First input is the video stream to process, and second one is the Hald CLUT.
12752 The Hald CLUT input can be a simple picture or a complete video stream.
12754 The filter accepts the following options:
12758 Force termination when the shortest input terminates. Default is @code{0}.
12760 Continue applying the last CLUT after the end of the stream. A value of
12761 @code{0} disable the filter after the last frame of the CLUT is reached.
12762 Default is @code{1}.
12765 @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
12766 filters share the same internals).
12768 This filter also supports the @ref{framesync} options.
12770 More information about the Hald CLUT can be found on Eskil Steenberg's website
12771 (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
12773 @subsection Workflow examples
12775 @subsubsection Hald CLUT video stream
12777 Generate an identity Hald CLUT stream altered with various effects:
12779 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
12782 Note: make sure you use a lossless codec.
12784 Then use it with @code{haldclut} to apply it on some random stream:
12786 ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
12789 The Hald CLUT will be applied to the 10 first seconds (duration of
12790 @file{clut.nut}), then the latest picture of that CLUT stream will be applied
12791 to the remaining frames of the @code{mandelbrot} stream.
12793 @subsubsection Hald CLUT with preview
12795 A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
12796 @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
12797 biggest possible square starting at the top left of the picture. The remaining
12798 padding pixels (bottom or right) will be ignored. This area can be used to add
12799 a preview of the Hald CLUT.
12801 Typically, the following generated Hald CLUT will be supported by the
12802 @code{haldclut} filter:
12805 ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
12806 pad=iw+320 [padded_clut];
12807 smptebars=s=320x256, split [a][b];
12808 [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
12809 [main][b] overlay=W-320" -frames:v 1 clut.png
12812 It contains the original and a preview of the effect of the CLUT: SMPTE color
12813 bars are displayed on the right-top, and below the same color bars processed by
12816 Then, the effect of this Hald CLUT can be visualized with:
12818 ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
12823 Flip the input video horizontally.
12825 For example, to horizontally flip the input video with @command{ffmpeg}:
12827 ffmpeg -i in.avi -vf "hflip" out.avi
12831 This filter applies a global color histogram equalization on a
12834 It can be used to correct video that has a compressed range of pixel
12835 intensities. The filter redistributes the pixel intensities to
12836 equalize their distribution across the intensity range. It may be
12837 viewed as an "automatically adjusting contrast filter". This filter is
12838 useful only for correcting degraded or poorly captured source
12841 The filter accepts the following options:
12845 Determine the amount of equalization to be applied. As the strength
12846 is reduced, the distribution of pixel intensities more-and-more
12847 approaches that of the input frame. The value must be a float number
12848 in the range [0,1] and defaults to 0.200.
12851 Set the maximum intensity that can generated and scale the output
12852 values appropriately. The strength should be set as desired and then
12853 the intensity can be limited if needed to avoid washing-out. The value
12854 must be a float number in the range [0,1] and defaults to 0.210.
12857 Set the antibanding level. If enabled the filter will randomly vary
12858 the luminance of output pixels by a small amount to avoid banding of
12859 the histogram. Possible values are @code{none}, @code{weak} or
12860 @code{strong}. It defaults to @code{none}.
12866 Compute and draw a color distribution histogram for the input video.
12868 The computed histogram is a representation of the color component
12869 distribution in an image.
12871 Standard histogram displays the color components distribution in an image.
12872 Displays color graph for each color component. Shows distribution of
12873 the Y, U, V, A or R, G, B components, depending on input format, in the
12874 current frame. Below each graph a color component scale meter is shown.
12876 The filter accepts the following options:
12880 Set height of level. Default value is @code{200}.
12881 Allowed range is [50, 2048].
12884 Set height of color scale. Default value is @code{12}.
12885 Allowed range is [0, 40].
12889 It accepts the following values:
12892 Per color component graphs are placed below each other.
12895 Per color component graphs are placed side by side.
12898 Presents information identical to that in the @code{parade}, except
12899 that the graphs representing color components are superimposed directly
12902 Default is @code{stack}.
12905 Set mode. Can be either @code{linear}, or @code{logarithmic}.
12906 Default is @code{linear}.
12909 Set what color components to display.
12910 Default is @code{7}.
12913 Set foreground opacity. Default is @code{0.7}.
12916 Set background opacity. Default is @code{0.5}.
12919 @subsection Examples
12924 Calculate and draw histogram:
12926 ffplay -i input -vf histogram
12934 This is a high precision/quality 3d denoise filter. It aims to reduce
12935 image noise, producing smooth images and making still images really
12936 still. It should enhance compressibility.
12938 It accepts the following optional parameters:
12942 A non-negative floating point number which specifies spatial luma strength.
12943 It defaults to 4.0.
12945 @item chroma_spatial
12946 A non-negative floating point number which specifies spatial chroma strength.
12947 It defaults to 3.0*@var{luma_spatial}/4.0.
12950 A floating point number which specifies luma temporal strength. It defaults to
12951 6.0*@var{luma_spatial}/4.0.
12954 A floating point number which specifies chroma temporal strength. It defaults to
12955 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
12958 @subsection Commands
12959 This filter supports same @ref{commands} as options.
12960 The command accepts the same syntax of the corresponding option.
12962 If the specified expression is not valid, it is kept at its current
12965 @anchor{hwdownload}
12966 @section hwdownload
12968 Download hardware frames to system memory.
12970 The input must be in hardware frames, and the output a non-hardware format.
12971 Not all formats will be supported on the output - it may be necessary to insert
12972 an additional @option{format} filter immediately following in the graph to get
12973 the output in a supported format.
12977 Map hardware frames to system memory or to another device.
12979 This filter has several different modes of operation; which one is used depends
12980 on the input and output formats:
12983 Hardware frame input, normal frame output
12985 Map the input frames to system memory and pass them to the output. If the
12986 original hardware frame is later required (for example, after overlaying
12987 something else on part of it), the @option{hwmap} filter can be used again
12988 in the next mode to retrieve it.
12990 Normal frame input, hardware frame output
12992 If the input is actually a software-mapped hardware frame, then unmap it -
12993 that is, return the original hardware frame.
12995 Otherwise, a device must be provided. Create new hardware surfaces on that
12996 device for the output, then map them back to the software format at the input
12997 and give those frames to the preceding filter. This will then act like the
12998 @option{hwupload} filter, but may be able to avoid an additional copy when
12999 the input is already in a compatible format.
13001 Hardware frame input and output
13003 A device must be supplied for the output, either directly or with the
13004 @option{derive_device} option. The input and output devices must be of
13005 different types and compatible - the exact meaning of this is
13006 system-dependent, but typically it means that they must refer to the same
13007 underlying hardware context (for example, refer to the same graphics card).
13009 If the input frames were originally created on the output device, then unmap
13010 to retrieve the original frames.
13012 Otherwise, map the frames to the output device - create new hardware frames
13013 on the output corresponding to the frames on the input.
13016 The following additional parameters are accepted:
13020 Set the frame mapping mode. Some combination of:
13023 The mapped frame should be readable.
13025 The mapped frame should be writeable.
13027 The mapping will always overwrite the entire frame.
13029 This may improve performance in some cases, as the original contents of the
13030 frame need not be loaded.
13032 The mapping must not involve any copying.
13034 Indirect mappings to copies of frames are created in some cases where either
13035 direct mapping is not possible or it would have unexpected properties.
13036 Setting this flag ensures that the mapping is direct and will fail if that is
13039 Defaults to @var{read+write} if not specified.
13041 @item derive_device @var{type}
13042 Rather than using the device supplied at initialisation, instead derive a new
13043 device of type @var{type} from the device the input frames exist on.
13046 In a hardware to hardware mapping, map in reverse - create frames in the sink
13047 and map them back to the source. This may be necessary in some cases where
13048 a mapping in one direction is required but only the opposite direction is
13049 supported by the devices being used.
13051 This option is dangerous - it may break the preceding filter in undefined
13052 ways if there are any additional constraints on that filter's output.
13053 Do not use it without fully understanding the implications of its use.
13059 Upload system memory frames to hardware surfaces.
13061 The device to upload to must be supplied when the filter is initialised. If
13062 using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
13063 option or with the @option{derive_device} option. The input and output devices
13064 must be of different types and compatible - the exact meaning of this is
13065 system-dependent, but typically it means that they must refer to the same
13066 underlying hardware context (for example, refer to the same graphics card).
13068 The following additional parameters are accepted:
13071 @item derive_device @var{type}
13072 Rather than using the device supplied at initialisation, instead derive a new
13073 device of type @var{type} from the device the input frames exist on.
13076 @anchor{hwupload_cuda}
13077 @section hwupload_cuda
13079 Upload system memory frames to a CUDA device.
13081 It accepts the following optional parameters:
13085 The number of the CUDA device to use
13090 Apply a high-quality magnification filter designed for pixel art. This filter
13091 was originally created by Maxim Stepin.
13093 It accepts the following option:
13097 Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
13098 @code{hq3x} and @code{4} for @code{hq4x}.
13099 Default is @code{3}.
13103 Stack input videos horizontally.
13105 All streams must be of same pixel format and of same height.
13107 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
13108 to create same output.
13110 The filter accepts the following option:
13114 Set number of input streams. Default is 2.
13117 If set to 1, force the output to terminate when the shortest input
13118 terminates. Default value is 0.
13123 Modify the hue and/or the saturation of the input.
13125 It accepts the following parameters:
13129 Specify the hue angle as a number of degrees. It accepts an expression,
13130 and defaults to "0".
13133 Specify the saturation in the [-10,10] range. It accepts an expression and
13137 Specify the hue angle as a number of radians. It accepts an
13138 expression, and defaults to "0".
13141 Specify the brightness in the [-10,10] range. It accepts an expression and
13145 @option{h} and @option{H} are mutually exclusive, and can't be
13146 specified at the same time.
13148 The @option{b}, @option{h}, @option{H} and @option{s} option values are
13149 expressions containing the following constants:
13153 frame count of the input frame starting from 0
13156 presentation timestamp of the input frame expressed in time base units
13159 frame rate of the input video, NAN if the input frame rate is unknown
13162 timestamp expressed in seconds, NAN if the input timestamp is unknown
13165 time base of the input video
13168 @subsection Examples
13172 Set the hue to 90 degrees and the saturation to 1.0:
13178 Same command but expressing the hue in radians:
13184 Rotate hue and make the saturation swing between 0
13185 and 2 over a period of 1 second:
13187 hue="H=2*PI*t: s=sin(2*PI*t)+1"
13191 Apply a 3 seconds saturation fade-in effect starting at 0:
13193 hue="s=min(t/3\,1)"
13196 The general fade-in expression can be written as:
13198 hue="s=min(0\, max((t-START)/DURATION\, 1))"
13202 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
13204 hue="s=max(0\, min(1\, (8-t)/3))"
13207 The general fade-out expression can be written as:
13209 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
13214 @subsection Commands
13216 This filter supports the following commands:
13222 Modify the hue and/or the saturation and/or brightness of the input video.
13223 The command accepts the same syntax of the corresponding option.
13225 If the specified expression is not valid, it is kept at its current
13229 @section hysteresis
13231 Grow first stream into second stream by connecting components.
13232 This makes it possible to build more robust edge masks.
13234 This filter accepts the following options:
13238 Set which planes will be processed as bitmap, unprocessed planes will be
13239 copied from first stream.
13240 By default value 0xf, all planes will be processed.
13243 Set threshold which is used in filtering. If pixel component value is higher than
13244 this value filter algorithm for connecting components is activated.
13245 By default value is 0.
13248 The @code{hysteresis} filter also supports the @ref{framesync} options.
13252 Detect video interlacing type.
13254 This filter tries to detect if the input frames are interlaced, progressive,
13255 top or bottom field first. It will also try to detect fields that are
13256 repeated between adjacent frames (a sign of telecine).
13258 Single frame detection considers only immediately adjacent frames when classifying each frame.
13259 Multiple frame detection incorporates the classification history of previous frames.
13261 The filter will log these metadata values:
13264 @item single.current_frame
13265 Detected type of current frame using single-frame detection. One of:
13266 ``tff'' (top field first), ``bff'' (bottom field first),
13267 ``progressive'', or ``undetermined''
13270 Cumulative number of frames detected as top field first using single-frame detection.
13273 Cumulative number of frames detected as top field first using multiple-frame detection.
13276 Cumulative number of frames detected as bottom field first using single-frame detection.
13278 @item multiple.current_frame
13279 Detected type of current frame using multiple-frame detection. One of:
13280 ``tff'' (top field first), ``bff'' (bottom field first),
13281 ``progressive'', or ``undetermined''
13284 Cumulative number of frames detected as bottom field first using multiple-frame detection.
13286 @item single.progressive
13287 Cumulative number of frames detected as progressive using single-frame detection.
13289 @item multiple.progressive
13290 Cumulative number of frames detected as progressive using multiple-frame detection.
13292 @item single.undetermined
13293 Cumulative number of frames that could not be classified using single-frame detection.
13295 @item multiple.undetermined
13296 Cumulative number of frames that could not be classified using multiple-frame detection.
13298 @item repeated.current_frame
13299 Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
13301 @item repeated.neither
13302 Cumulative number of frames with no repeated field.
13305 Cumulative number of frames with the top field repeated from the previous frame's top field.
13307 @item repeated.bottom
13308 Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
13311 The filter accepts the following options:
13315 Set interlacing threshold.
13317 Set progressive threshold.
13319 Threshold for repeated field detection.
13321 Number of frames after which a given frame's contribution to the
13322 statistics is halved (i.e., it contributes only 0.5 to its
13323 classification). The default of 0 means that all frames seen are given
13324 full weight of 1.0 forever.
13325 @item analyze_interlaced_flag
13326 When this is not 0 then idet will use the specified number of frames to determine
13327 if the interlaced flag is accurate, it will not count undetermined frames.
13328 If the flag is found to be accurate it will be used without any further
13329 computations, if it is found to be inaccurate it will be cleared without any
13330 further computations. This allows inserting the idet filter as a low computational
13331 method to clean up the interlaced flag
13336 Deinterleave or interleave fields.
13338 This filter allows one to process interlaced images fields without
13339 deinterlacing them. Deinterleaving splits the input frame into 2
13340 fields (so called half pictures). Odd lines are moved to the top
13341 half of the output image, even lines to the bottom half.
13342 You can process (filter) them independently and then re-interleave them.
13344 The filter accepts the following options:
13348 @item chroma_mode, c
13349 @item alpha_mode, a
13350 Available values for @var{luma_mode}, @var{chroma_mode} and
13351 @var{alpha_mode} are:
13357 @item deinterleave, d
13358 Deinterleave fields, placing one above the other.
13360 @item interleave, i
13361 Interleave fields. Reverse the effect of deinterleaving.
13363 Default value is @code{none}.
13365 @item luma_swap, ls
13366 @item chroma_swap, cs
13367 @item alpha_swap, as
13368 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
13371 @subsection Commands
13373 This filter supports the all above options as @ref{commands}.
13377 Apply inflate effect to the video.
13379 This filter replaces the pixel by the local(3x3) average by taking into account
13380 only values higher than the pixel.
13382 It accepts the following options:
13389 Limit the maximum change for each plane, default is 65535.
13390 If 0, plane will remain unchanged.
13393 @subsection Commands
13395 This filter supports the all above options as @ref{commands}.
13399 Simple interlacing filter from progressive contents. This interleaves upper (or
13400 lower) lines from odd frames with lower (or upper) lines from even frames,
13401 halving the frame rate and preserving image height.
13404 Original Original New Frame
13405 Frame 'j' Frame 'j+1' (tff)
13406 ========== =========== ==================
13407 Line 0 --------------------> Frame 'j' Line 0
13408 Line 1 Line 1 ----> Frame 'j+1' Line 1
13409 Line 2 ---------------------> Frame 'j' Line 2
13410 Line 3 Line 3 ----> Frame 'j+1' Line 3
13412 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
13415 It accepts the following optional parameters:
13419 This determines whether the interlaced frame is taken from the even
13420 (tff - default) or odd (bff) lines of the progressive frame.
13423 Vertical lowpass filter to avoid twitter interlacing and
13424 reduce moire patterns.
13428 Disable vertical lowpass filter
13431 Enable linear filter (default)
13434 Enable complex filter. This will slightly less reduce twitter and moire
13435 but better retain detail and subjective sharpness impression.
13442 Deinterlace input video by applying Donald Graft's adaptive kernel
13443 deinterling. Work on interlaced parts of a video to produce
13444 progressive frames.
13446 The description of the accepted parameters follows.
13450 Set the threshold which affects the filter's tolerance when
13451 determining if a pixel line must be processed. It must be an integer
13452 in the range [0,255] and defaults to 10. A value of 0 will result in
13453 applying the process on every pixels.
13456 Paint pixels exceeding the threshold value to white if set to 1.
13460 Set the fields order. Swap fields if set to 1, leave fields alone if
13464 Enable additional sharpening if set to 1. Default is 0.
13467 Enable twoway sharpening if set to 1. Default is 0.
13470 @subsection Examples
13474 Apply default values:
13476 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
13480 Enable additional sharpening:
13486 Paint processed pixels in white:
13493 Apply kirsch operator to input video stream.
13495 The filter accepts the following option:
13499 Set which planes will be processed, unprocessed planes will be copied.
13500 By default value 0xf, all planes will be processed.
13503 Set value which will be multiplied with filtered result.
13506 Set value which will be added to filtered result.
13509 @subsection Commands
13511 This filter supports the all above options as @ref{commands}.
13515 Slowly update darker pixels.
13517 This filter makes short flashes of light appear longer.
13518 This filter accepts the following options:
13522 Set factor for decaying. Default is .95. Allowed range is from 0 to 1.
13525 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
13528 @subsection Commands
13530 This filter supports the all above options as @ref{commands}.
13532 @section lenscorrection
13534 Correct radial lens distortion
13536 This filter can be used to correct for radial distortion as can result from the use
13537 of wide angle lenses, and thereby re-rectify the image. To find the right parameters
13538 one can use tools available for example as part of opencv or simply trial-and-error.
13539 To use opencv use the calibration sample (under samples/cpp) from the opencv sources
13540 and extract the k1 and k2 coefficients from the resulting matrix.
13542 Note that effectively the same filter is available in the open-source tools Krita and
13543 Digikam from the KDE project.
13545 In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
13546 this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
13547 brightness distribution, so you may want to use both filters together in certain
13548 cases, though you will have to take care of ordering, i.e. whether vignetting should
13549 be applied before or after lens correction.
13551 @subsection Options
13553 The filter accepts the following options:
13557 Relative x-coordinate of the focal point of the image, and thereby the center of the
13558 distortion. This value has a range [0,1] and is expressed as fractions of the image
13559 width. Default is 0.5.
13561 Relative y-coordinate of the focal point of the image, and thereby the center of the
13562 distortion. This value has a range [0,1] and is expressed as fractions of the image
13563 height. Default is 0.5.
13565 Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means
13566 no correction. Default is 0.
13568 Coefficient of the double quadratic correction term. This value has a range [-1,1].
13569 0 means no correction. Default is 0.
13571 Set interpolation type. Can be @code{nearest} or @code{bilinear}.
13572 Default is @code{nearest}.
13574 Specify the color of the unmapped pixels. For the syntax of this option,
13575 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
13576 manual,ffmpeg-utils}. Default color is @code{black@@0}.
13579 The formula that generates the correction is:
13581 @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)
13583 where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
13584 distances from the focal point in the source and target images, respectively.
13586 @subsection Commands
13588 This filter supports the all above options as @ref{commands}.
13592 Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}).
13594 The @code{lensfun} filter requires the camera make, camera model, and lens model
13595 to apply the lens correction. The filter will load the lensfun database and
13596 query it to find the corresponding camera and lens entries in the database. As
13597 long as these entries can be found with the given options, the filter can
13598 perform corrections on frames. Note that incomplete strings will result in the
13599 filter choosing the best match with the given options, and the filter will
13600 output the chosen camera and lens models (logged with level "info"). You must
13601 provide the make, camera model, and lens model as they are required.
13603 The filter accepts the following options:
13607 The make of the camera (for example, "Canon"). This option is required.
13610 The model of the camera (for example, "Canon EOS 100D"). This option is
13614 The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This
13615 option is required.
13618 The type of correction to apply. The following values are valid options:
13622 Enables fixing lens vignetting.
13625 Enables fixing lens geometry. This is the default.
13628 Enables fixing chromatic aberrations.
13631 Enables fixing lens vignetting and lens geometry.
13634 Enables fixing lens vignetting and chromatic aberrations.
13637 Enables fixing both lens geometry and chromatic aberrations.
13640 Enables all possible corrections.
13644 The focal length of the image/video (zoom; expected constant for video). For
13645 example, a 18--55mm lens has focal length range of [18--55], so a value in that
13646 range should be chosen when using that lens. Default 18.
13649 The aperture of the image/video (expected constant for video). Note that
13650 aperture is only used for vignetting correction. Default 3.5.
13652 @item focus_distance
13653 The focus distance of the image/video (expected constant for video). Note that
13654 focus distance is only used for vignetting and only slightly affects the
13655 vignetting correction process. If unknown, leave it at the default value (which
13659 The scale factor which is applied after transformation. After correction the
13660 video is no longer necessarily rectangular. This parameter controls how much of
13661 the resulting image is visible. The value 0 means that a value will be chosen
13662 automatically such that there is little or no unmapped area in the output
13663 image. 1.0 means that no additional scaling is done. Lower values may result
13664 in more of the corrected image being visible, while higher values may avoid
13665 unmapped areas in the output.
13667 @item target_geometry
13668 The target geometry of the output image/video. The following values are valid
13672 @item rectilinear (default)
13675 @item equirectangular
13676 @item fisheye_orthographic
13677 @item fisheye_stereographic
13678 @item fisheye_equisolid
13679 @item fisheye_thoby
13682 Apply the reverse of image correction (instead of correcting distortion, apply
13685 @item interpolation
13686 The type of interpolation used when correcting distortion. The following values
13691 @item linear (default)
13696 @subsection Examples
13700 Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens
13701 model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and
13705 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
13709 Apply the same as before, but only for the first 5 seconds of video.
13712 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
13719 Obtain the VMAF (Video Multi-Method Assessment Fusion)
13720 score between two input videos.
13722 The obtained VMAF score is printed through the logging system.
13724 It requires Netflix's vmaf library (libvmaf) as a pre-requisite.
13725 After installing the library it can be enabled using:
13726 @code{./configure --enable-libvmaf}.
13727 If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}.
13729 The filter has following options:
13733 Set the model path which is to be used for SVM.
13734 Default value: @code{"/usr/local/share/model/vmaf_v0.6.1.pkl"}
13737 Set the file path to be used to store logs.
13740 Set the format of the log file (csv, json or xml).
13742 @item enable_transform
13743 This option can enable/disable the @code{score_transform} applied to the final predicted VMAF score,
13744 if you have specified score_transform option in the input parameter file passed to @code{run_vmaf_training.py}
13745 Default value: @code{false}
13748 Invokes the phone model which will generate VMAF scores higher than in the
13749 regular model, which is more suitable for laptop, TV, etc. viewing conditions.
13750 Default value: @code{false}
13753 Enables computing psnr along with vmaf.
13754 Default value: @code{false}
13757 Enables computing ssim along with vmaf.
13758 Default value: @code{false}
13761 Enables computing ms_ssim along with vmaf.
13762 Default value: @code{false}
13765 Set the pool method to be used for computing vmaf.
13766 Options are @code{min}, @code{harmonic_mean} or @code{mean} (default).
13769 Set number of threads to be used when computing vmaf.
13770 Default value: @code{0}, which makes use of all available logical processors.
13773 Set interval for frame subsampling used when computing vmaf.
13774 Default value: @code{1}
13776 @item enable_conf_interval
13777 Enables confidence interval.
13778 Default value: @code{false}
13781 This filter also supports the @ref{framesync} options.
13783 @subsection Examples
13786 On the below examples the input file @file{main.mpg} being processed is
13787 compared with the reference file @file{ref.mpg}.
13790 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
13794 Example with options:
13796 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:log_fmt=json" -f null -
13800 Example with options and different containers:
13802 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 -
13808 Limits the pixel components values to the specified range [min, max].
13810 The filter accepts the following options:
13814 Lower bound. Defaults to the lowest allowed value for the input.
13817 Upper bound. Defaults to the highest allowed value for the input.
13820 Specify which planes will be processed. Defaults to all available.
13823 @subsection Commands
13825 This filter supports the all above options as @ref{commands}.
13831 The filter accepts the following options:
13835 Set the number of loops. Setting this value to -1 will result in infinite loops.
13839 Set maximal size in number of frames. Default is 0.
13842 Set first frame of loop. Default is 0.
13845 @subsection Examples
13849 Loop single first frame infinitely:
13851 loop=loop=-1:size=1:start=0
13855 Loop single first frame 10 times:
13857 loop=loop=10:size=1:start=0
13861 Loop 10 first frames 5 times:
13863 loop=loop=5:size=10:start=0
13869 Apply a 1D LUT to an input video.
13871 The filter accepts the following options:
13875 Set the 1D LUT file name.
13877 Currently supported formats:
13886 Select interpolation mode.
13888 Available values are:
13892 Use values from the nearest defined point.
13894 Interpolate values using the linear interpolation.
13896 Interpolate values using the cosine interpolation.
13898 Interpolate values using the cubic interpolation.
13900 Interpolate values using the spline interpolation.
13907 Apply a 3D LUT to an input video.
13909 The filter accepts the following options:
13913 Set the 3D LUT file name.
13915 Currently supported formats:
13929 Select interpolation mode.
13931 Available values are:
13935 Use values from the nearest defined point.
13937 Interpolate values using the 8 points defining a cube.
13939 Interpolate values using a tetrahedron.
13941 Interpolate values using a pyramid.
13943 Interpolate values using a prism.
13949 Turn certain luma values into transparency.
13951 The filter accepts the following options:
13955 Set the luma which will be used as base for transparency.
13956 Default value is @code{0}.
13959 Set the range of luma values to be keyed out.
13960 Default value is @code{0.01}.
13963 Set the range of softness. Default value is @code{0}.
13964 Use this to control gradual transition from zero to full transparency.
13967 @subsection Commands
13968 This filter supports same @ref{commands} as options.
13969 The command accepts the same syntax of the corresponding option.
13971 If the specified expression is not valid, it is kept at its current
13974 @section lut, lutrgb, lutyuv
13976 Compute a look-up table for binding each pixel component input value
13977 to an output value, and apply it to the input video.
13979 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
13980 to an RGB input video.
13982 These filters accept the following parameters:
13985 set first pixel component expression
13987 set second pixel component expression
13989 set third pixel component expression
13991 set fourth pixel component expression, corresponds to the alpha component
13994 set red component expression
13996 set green component expression
13998 set blue component expression
14000 alpha component expression
14003 set Y/luminance component expression
14005 set U/Cb component expression
14007 set V/Cr component expression
14010 Each of them specifies the expression to use for computing the lookup table for
14011 the corresponding pixel component values.
14013 The exact component associated to each of the @var{c*} options depends on the
14016 The @var{lut} filter requires either YUV or RGB pixel formats in input,
14017 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
14019 The expressions can contain the following constants and functions:
14024 The input width and height.
14027 The input value for the pixel component.
14030 The input value, clipped to the @var{minval}-@var{maxval} range.
14033 The maximum value for the pixel component.
14036 The minimum value for the pixel component.
14039 The negated value for the pixel component value, clipped to the
14040 @var{minval}-@var{maxval} range; it corresponds to the expression
14041 "maxval-clipval+minval".
14044 The computed value in @var{val}, clipped to the
14045 @var{minval}-@var{maxval} range.
14047 @item gammaval(gamma)
14048 The computed gamma correction value of the pixel component value,
14049 clipped to the @var{minval}-@var{maxval} range. It corresponds to the
14051 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
14055 All expressions default to "val".
14057 @subsection Examples
14061 Negate input video:
14063 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
14064 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
14067 The above is the same as:
14069 lutrgb="r=negval:g=negval:b=negval"
14070 lutyuv="y=negval:u=negval:v=negval"
14080 Remove chroma components, turning the video into a graytone image:
14082 lutyuv="u=128:v=128"
14086 Apply a luma burning effect:
14092 Remove green and blue components:
14098 Set a constant alpha channel value on input:
14100 format=rgba,lutrgb=a="maxval-minval/2"
14104 Correct luminance gamma by a factor of 0.5:
14106 lutyuv=y=gammaval(0.5)
14110 Discard least significant bits of luma:
14112 lutyuv=y='bitand(val, 128+64+32)'
14116 Technicolor like effect:
14118 lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
14122 @section lut2, tlut2
14124 The @code{lut2} filter takes two input streams and outputs one
14127 The @code{tlut2} (time lut2) filter takes two consecutive frames
14128 from one single stream.
14130 This filter accepts the following parameters:
14133 set first pixel component expression
14135 set second pixel component expression
14137 set third pixel component expression
14139 set fourth pixel component expression, corresponds to the alpha component
14142 set output bit depth, only available for @code{lut2} filter. By default is 0,
14143 which means bit depth is automatically picked from first input format.
14146 The @code{lut2} filter also supports the @ref{framesync} options.
14148 Each of them specifies the expression to use for computing the lookup table for
14149 the corresponding pixel component values.
14151 The exact component associated to each of the @var{c*} options depends on the
14154 The expressions can contain the following constants:
14159 The input width and height.
14162 The first input value for the pixel component.
14165 The second input value for the pixel component.
14168 The first input video bit depth.
14171 The second input video bit depth.
14174 All expressions default to "x".
14176 @subsection Examples
14180 Highlight differences between two RGB video streams:
14182 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)'
14186 Highlight differences between two YUV video streams:
14188 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)'
14192 Show max difference between two video streams:
14194 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)))'
14198 @section maskedclamp
14200 Clamp the first input stream with the second input and third input stream.
14202 Returns the value of first stream to be between second input
14203 stream - @code{undershoot} and third input stream + @code{overshoot}.
14205 This filter accepts the following options:
14208 Default value is @code{0}.
14211 Default value is @code{0}.
14214 Set which planes will be processed as bitmap, unprocessed planes will be
14215 copied from first stream.
14216 By default value 0xf, all planes will be processed.
14219 @subsection Commands
14221 This filter supports the all above options as @ref{commands}.
14225 Merge the second and third input stream into output stream using absolute differences
14226 between second input stream and first input stream and absolute difference between
14227 third input stream and first input stream. The picked value will be from second input
14228 stream if second absolute difference is greater than first one or from third input stream
14231 This filter accepts the following options:
14234 Set which planes will be processed as bitmap, unprocessed planes will be
14235 copied from first stream.
14236 By default value 0xf, all planes will be processed.
14239 @subsection Commands
14241 This filter supports the all above options as @ref{commands}.
14243 @section maskedmerge
14245 Merge the first input stream with the second input stream using per pixel
14246 weights in the third input stream.
14248 A value of 0 in the third stream pixel component means that pixel component
14249 from first stream is returned unchanged, while maximum value (eg. 255 for
14250 8-bit videos) means that pixel component from second stream is returned
14251 unchanged. Intermediate values define the amount of merging between both
14252 input stream's pixel components.
14254 This filter accepts the following options:
14257 Set which planes will be processed as bitmap, unprocessed planes will be
14258 copied from first stream.
14259 By default value 0xf, all planes will be processed.
14262 @subsection Commands
14264 This filter supports the all above options as @ref{commands}.
14268 Merge the second and third input stream into output stream using absolute differences
14269 between second input stream and first input stream and absolute difference between
14270 third input stream and first input stream. The picked value will be from second input
14271 stream if second absolute difference is less than first one or from third input stream
14274 This filter accepts the following options:
14277 Set which planes will be processed as bitmap, unprocessed planes will be
14278 copied from first stream.
14279 By default value 0xf, all planes will be processed.
14282 @subsection Commands
14284 This filter supports the all above options as @ref{commands}.
14286 @section maskedthreshold
14287 Pick pixels comparing absolute difference of two video streams with fixed
14290 If absolute difference between pixel component of first and second video
14291 stream is equal or lower than user supplied threshold than pixel component
14292 from first video stream is picked, otherwise pixel component from second
14293 video stream is picked.
14295 This filter accepts the following options:
14298 Set threshold used when picking pixels from absolute difference from two input
14302 Set which planes will be processed as bitmap, unprocessed planes will be
14303 copied from second stream.
14304 By default value 0xf, all planes will be processed.
14307 @subsection Commands
14309 This filter supports the all above options as @ref{commands}.
14312 Create mask from input video.
14314 For example it is useful to create motion masks after @code{tblend} filter.
14316 This filter accepts the following options:
14320 Set low threshold. Any pixel component lower or exact than this value will be set to 0.
14323 Set high threshold. Any pixel component higher than this value will be set to max value
14324 allowed for current pixel format.
14327 Set planes to filter, by default all available planes are filtered.
14330 Fill all frame pixels with this value.
14333 Set max average pixel value for frame. If sum of all pixel components is higher that this
14334 average, output frame will be completely filled with value set by @var{fill} option.
14335 Typically useful for scene changes when used in combination with @code{tblend} filter.
14340 Apply motion-compensation deinterlacing.
14342 It needs one field per frame as input and must thus be used together
14343 with yadif=1/3 or equivalent.
14345 This filter accepts the following options:
14348 Set the deinterlacing mode.
14350 It accepts one of the following values:
14355 use iterative motion estimation
14357 like @samp{slow}, but use multiple reference frames.
14359 Default value is @samp{fast}.
14362 Set the picture field parity assumed for the input video. It must be
14363 one of the following values:
14367 assume top field first
14369 assume bottom field first
14372 Default value is @samp{bff}.
14375 Set per-block quantization parameter (QP) used by the internal
14378 Higher values should result in a smoother motion vector field but less
14379 optimal individual vectors. Default value is 1.
14384 Pick median pixel from certain rectangle defined by radius.
14386 This filter accepts the following options:
14390 Set horizontal radius size. Default value is @code{1}.
14391 Allowed range is integer from 1 to 127.
14394 Set which planes to process. Default is @code{15}, which is all available planes.
14397 Set vertical radius size. Default value is @code{0}.
14398 Allowed range is integer from 0 to 127.
14399 If it is 0, value will be picked from horizontal @code{radius} option.
14402 Set median percentile. Default value is @code{0.5}.
14403 Default value of @code{0.5} will pick always median values, while @code{0} will pick
14404 minimum values, and @code{1} maximum values.
14407 @subsection Commands
14408 This filter supports same @ref{commands} as options.
14409 The command accepts the same syntax of the corresponding option.
14411 If the specified expression is not valid, it is kept at its current
14414 @section mergeplanes
14416 Merge color channel components from several video streams.
14418 The filter accepts up to 4 input streams, and merge selected input
14419 planes to the output video.
14421 This filter accepts the following options:
14424 Set input to output plane mapping. Default is @code{0}.
14426 The mappings is specified as a bitmap. It should be specified as a
14427 hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
14428 mapping for the first plane of the output stream. 'A' sets the number of
14429 the input stream to use (from 0 to 3), and 'a' the plane number of the
14430 corresponding input to use (from 0 to 3). The rest of the mappings is
14431 similar, 'Bb' describes the mapping for the output stream second
14432 plane, 'Cc' describes the mapping for the output stream third plane and
14433 'Dd' describes the mapping for the output stream fourth plane.
14436 Set output pixel format. Default is @code{yuva444p}.
14439 @subsection Examples
14443 Merge three gray video streams of same width and height into single video stream:
14445 [a0][a1][a2]mergeplanes=0x001020:yuv444p
14449 Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
14451 [a0][a1]mergeplanes=0x00010210:yuva444p
14455 Swap Y and A plane in yuva444p stream:
14457 format=yuva444p,mergeplanes=0x03010200:yuva444p
14461 Swap U and V plane in yuv420p stream:
14463 format=yuv420p,mergeplanes=0x000201:yuv420p
14467 Cast a rgb24 clip to yuv444p:
14469 format=rgb24,mergeplanes=0x000102:yuv444p
14475 Estimate and export motion vectors using block matching algorithms.
14476 Motion vectors are stored in frame side data to be used by other filters.
14478 This filter accepts the following options:
14481 Specify the motion estimation method. Accepts one of the following values:
14485 Exhaustive search algorithm.
14487 Three step search algorithm.
14489 Two dimensional logarithmic search algorithm.
14491 New three step search algorithm.
14493 Four step search algorithm.
14495 Diamond search algorithm.
14497 Hexagon-based search algorithm.
14499 Enhanced predictive zonal search algorithm.
14501 Uneven multi-hexagon search algorithm.
14503 Default value is @samp{esa}.
14506 Macroblock size. Default @code{16}.
14509 Search parameter. Default @code{7}.
14512 @section midequalizer
14514 Apply Midway Image Equalization effect using two video streams.
14516 Midway Image Equalization adjusts a pair of images to have the same
14517 histogram, while maintaining their dynamics as much as possible. It's
14518 useful for e.g. matching exposures from a pair of stereo cameras.
14520 This filter has two inputs and one output, which must be of same pixel format, but
14521 may be of different sizes. The output of filter is first input adjusted with
14522 midway histogram of both inputs.
14524 This filter accepts the following option:
14528 Set which planes to process. Default is @code{15}, which is all available planes.
14531 @section minterpolate
14533 Convert the video to specified frame rate using motion interpolation.
14535 This filter accepts the following options:
14538 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}.
14541 Motion interpolation mode. Following values are accepted:
14544 Duplicate previous or next frame for interpolating new ones.
14546 Blend source frames. Interpolated frame is mean of previous and next frames.
14548 Motion compensated interpolation. Following options are effective when this mode is selected:
14552 Motion compensation mode. Following values are accepted:
14555 Overlapped block motion compensation.
14557 Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
14559 Default mode is @samp{obmc}.
14562 Motion estimation mode. Following values are accepted:
14565 Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
14567 Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
14569 Default mode is @samp{bilat}.
14572 The algorithm to be used for motion estimation. Following values are accepted:
14575 Exhaustive search algorithm.
14577 Three step search algorithm.
14579 Two dimensional logarithmic search algorithm.
14581 New three step search algorithm.
14583 Four step search algorithm.
14585 Diamond search algorithm.
14587 Hexagon-based search algorithm.
14589 Enhanced predictive zonal search algorithm.
14591 Uneven multi-hexagon search algorithm.
14593 Default algorithm is @samp{epzs}.
14596 Macroblock size. Default @code{16}.
14599 Motion estimation search parameter. Default @code{32}.
14602 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).
14607 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:
14610 Disable scene change detection.
14612 Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected.
14614 Default method is @samp{fdiff}.
14616 @item scd_threshold
14617 Scene change detection threshold. Default is @code{10.}.
14622 Mix several video input streams into one video stream.
14624 A description of the accepted options follows.
14628 The number of inputs. If unspecified, it defaults to 2.
14631 Specify weight of each input video stream as sequence.
14632 Each weight is separated by space. If number of weights
14633 is smaller than number of @var{frames} last specified
14634 weight will be used for all remaining unset weights.
14637 Specify scale, if it is set it will be multiplied with sum
14638 of each weight multiplied with pixel values to give final destination
14639 pixel value. By default @var{scale} is auto scaled to sum of weights.
14642 Specify how end of stream is determined.
14645 The duration of the longest input. (default)
14648 The duration of the shortest input.
14651 The duration of the first input.
14655 @section mpdecimate
14657 Drop frames that do not differ greatly from the previous frame in
14658 order to reduce frame rate.
14660 The main use of this filter is for very-low-bitrate encoding
14661 (e.g. streaming over dialup modem), but it could in theory be used for
14662 fixing movies that were inverse-telecined incorrectly.
14664 A description of the accepted options follows.
14668 Set the maximum number of consecutive frames which can be dropped (if
14669 positive), or the minimum interval between dropped frames (if
14670 negative). If the value is 0, the frame is dropped disregarding the
14671 number of previous sequentially dropped frames.
14673 Default value is 0.
14678 Set the dropping threshold values.
14680 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
14681 represent actual pixel value differences, so a threshold of 64
14682 corresponds to 1 unit of difference for each pixel, or the same spread
14683 out differently over the block.
14685 A frame is a candidate for dropping if no 8x8 blocks differ by more
14686 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
14687 meaning the whole image) differ by more than a threshold of @option{lo}.
14689 Default value for @option{hi} is 64*12, default value for @option{lo} is
14690 64*5, and default value for @option{frac} is 0.33.
14696 Negate (invert) the input video.
14698 It accepts the following option:
14703 With value 1, it negates the alpha component, if present. Default value is 0.
14709 Denoise frames using Non-Local Means algorithm.
14711 Each pixel is adjusted by looking for other pixels with similar contexts. This
14712 context similarity is defined by comparing their surrounding patches of size
14713 @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
14716 Note that the research area defines centers for patches, which means some
14717 patches will be made of pixels outside that research area.
14719 The filter accepts the following options.
14723 Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0].
14726 Set patch size. Default is 7. Must be odd number in range [0, 99].
14729 Same as @option{p} but for chroma planes.
14731 The default value is @var{0} and means automatic.
14734 Set research size. Default is 15. Must be odd number in range [0, 99].
14737 Same as @option{r} but for chroma planes.
14739 The default value is @var{0} and means automatic.
14744 Deinterlace video using neural network edge directed interpolation.
14746 This filter accepts the following options:
14750 Mandatory option, without binary file filter can not work.
14751 Currently file can be found here:
14752 https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
14755 Set which frames to deinterlace, by default it is @code{all}.
14756 Can be @code{all} or @code{interlaced}.
14759 Set mode of operation.
14761 Can be one of the following:
14765 Use frame flags, both fields.
14767 Use frame flags, single field.
14769 Use top field only.
14771 Use bottom field only.
14773 Use both fields, top first.
14775 Use both fields, bottom first.
14779 Set which planes to process, by default filter process all frames.
14782 Set size of local neighborhood around each pixel, used by the predictor neural
14785 Can be one of the following:
14798 Set the number of neurons in predictor neural network.
14799 Can be one of the following:
14810 Controls the number of different neural network predictions that are blended
14811 together to compute the final output value. Can be @code{fast}, default or
14815 Set which set of weights to use in the predictor.
14816 Can be one of the following:
14820 weights trained to minimize absolute error
14822 weights trained to minimize squared error
14826 Controls whether or not the prescreener neural network is used to decide
14827 which pixels should be processed by the predictor neural network and which
14828 can be handled by simple cubic interpolation.
14829 The prescreener is trained to know whether cubic interpolation will be
14830 sufficient for a pixel or whether it should be predicted by the predictor nn.
14831 The computational complexity of the prescreener nn is much less than that of
14832 the predictor nn. Since most pixels can be handled by cubic interpolation,
14833 using the prescreener generally results in much faster processing.
14834 The prescreener is pretty accurate, so the difference between using it and not
14835 using it is almost always unnoticeable.
14837 Can be one of the following:
14847 Default is @code{new}.
14850 @subsection Commands
14851 This filter supports same @ref{commands} as options, excluding @var{weights} option.
14855 Force libavfilter not to use any of the specified pixel formats for the
14856 input to the next filter.
14858 It accepts the following parameters:
14862 A '|'-separated list of pixel format names, such as
14863 pix_fmts=yuv420p|monow|rgb24".
14867 @subsection Examples
14871 Force libavfilter to use a format different from @var{yuv420p} for the
14872 input to the vflip filter:
14874 noformat=pix_fmts=yuv420p,vflip
14878 Convert the input video to any of the formats not contained in the list:
14880 noformat=yuv420p|yuv444p|yuv410p
14886 Add noise on video input frame.
14888 The filter accepts the following options:
14896 Set noise seed for specific pixel component or all pixel components in case
14897 of @var{all_seed}. Default value is @code{123457}.
14899 @item all_strength, alls
14900 @item c0_strength, c0s
14901 @item c1_strength, c1s
14902 @item c2_strength, c2s
14903 @item c3_strength, c3s
14904 Set noise strength for specific pixel component or all pixel components in case
14905 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
14907 @item all_flags, allf
14908 @item c0_flags, c0f
14909 @item c1_flags, c1f
14910 @item c2_flags, c2f
14911 @item c3_flags, c3f
14912 Set pixel component flags or set flags for all components if @var{all_flags}.
14913 Available values for component flags are:
14916 averaged temporal noise (smoother)
14918 mix random noise with a (semi)regular pattern
14920 temporal noise (noise pattern changes between frames)
14922 uniform noise (gaussian otherwise)
14926 @subsection Examples
14928 Add temporal and uniform noise to input video:
14930 noise=alls=20:allf=t+u
14935 Normalize RGB video (aka histogram stretching, contrast stretching).
14936 See: https://en.wikipedia.org/wiki/Normalization_(image_processing)
14938 For each channel of each frame, the filter computes the input range and maps
14939 it linearly to the user-specified output range. The output range defaults
14940 to the full dynamic range from pure black to pure white.
14942 Temporal smoothing can be used on the input range to reduce flickering (rapid
14943 changes in brightness) caused when small dark or bright objects enter or leave
14944 the scene. This is similar to the auto-exposure (automatic gain control) on a
14945 video camera, and, like a video camera, it may cause a period of over- or
14946 under-exposure of the video.
14948 The R,G,B channels can be normalized independently, which may cause some
14949 color shifting, or linked together as a single channel, which prevents
14950 color shifting. Linked normalization preserves hue. Independent normalization
14951 does not, so it can be used to remove some color casts. Independent and linked
14952 normalization can be combined in any ratio.
14954 The normalize filter accepts the following options:
14959 Colors which define the output range. The minimum input value is mapped to
14960 the @var{blackpt}. The maximum input value is mapped to the @var{whitept}.
14961 The defaults are black and white respectively. Specifying white for
14962 @var{blackpt} and black for @var{whitept} will give color-inverted,
14963 normalized video. Shades of grey can be used to reduce the dynamic range
14964 (contrast). Specifying saturated colors here can create some interesting
14968 The number of previous frames to use for temporal smoothing. The input range
14969 of each channel is smoothed using a rolling average over the current frame
14970 and the @var{smoothing} previous frames. The default is 0 (no temporal
14974 Controls the ratio of independent (color shifting) channel normalization to
14975 linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully
14976 independent. Defaults to 1.0 (fully independent).
14979 Overall strength of the filter. 1.0 is full strength. 0.0 is a rather
14980 expensive no-op. Defaults to 1.0 (full strength).
14984 @subsection Commands
14985 This filter supports same @ref{commands} as options, excluding @var{smoothing} option.
14986 The command accepts the same syntax of the corresponding option.
14988 If the specified expression is not valid, it is kept at its current
14991 @subsection Examples
14993 Stretch video contrast to use the full dynamic range, with no temporal
14994 smoothing; may flicker depending on the source content:
14996 normalize=blackpt=black:whitept=white:smoothing=0
14999 As above, but with 50 frames of temporal smoothing; flicker should be
15000 reduced, depending on the source content:
15002 normalize=blackpt=black:whitept=white:smoothing=50
15005 As above, but with hue-preserving linked channel normalization:
15007 normalize=blackpt=black:whitept=white:smoothing=50:independence=0
15010 As above, but with half strength:
15012 normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
15015 Map the darkest input color to red, the brightest input color to cyan:
15017 normalize=blackpt=red:whitept=cyan
15022 Pass the video source unchanged to the output.
15025 Optical Character Recognition
15027 This filter uses Tesseract for optical character recognition. To enable
15028 compilation of this filter, you need to configure FFmpeg with
15029 @code{--enable-libtesseract}.
15031 It accepts the following options:
15035 Set datapath to tesseract data. Default is to use whatever was
15036 set at installation.
15039 Set language, default is "eng".
15042 Set character whitelist.
15045 Set character blacklist.
15048 The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
15049 The filter exports confidence of recognized words as the frame metadata @code{lavfi.ocr.confidence}.
15053 Apply a video transform using libopencv.
15055 To enable this filter, install the libopencv library and headers and
15056 configure FFmpeg with @code{--enable-libopencv}.
15058 It accepts the following parameters:
15063 The name of the libopencv filter to apply.
15065 @item filter_params
15066 The parameters to pass to the libopencv filter. If not specified, the default
15067 values are assumed.
15071 Refer to the official libopencv documentation for more precise
15073 @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
15075 Several libopencv filters are supported; see the following subsections.
15080 Dilate an image by using a specific structuring element.
15081 It corresponds to the libopencv function @code{cvDilate}.
15083 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
15085 @var{struct_el} represents a structuring element, and has the syntax:
15086 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
15088 @var{cols} and @var{rows} represent the number of columns and rows of
15089 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
15090 point, and @var{shape} the shape for the structuring element. @var{shape}
15091 must be "rect", "cross", "ellipse", or "custom".
15093 If the value for @var{shape} is "custom", it must be followed by a
15094 string of the form "=@var{filename}". The file with name
15095 @var{filename} is assumed to represent a binary image, with each
15096 printable character corresponding to a bright pixel. When a custom
15097 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
15098 or columns and rows of the read file are assumed instead.
15100 The default value for @var{struct_el} is "3x3+0x0/rect".
15102 @var{nb_iterations} specifies the number of times the transform is
15103 applied to the image, and defaults to 1.
15107 # Use the default values
15110 # Dilate using a structuring element with a 5x5 cross, iterating two times
15111 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
15113 # Read the shape from the file diamond.shape, iterating two times.
15114 # The file diamond.shape may contain a pattern of characters like this
15120 # The specified columns and rows are ignored
15121 # but the anchor point coordinates are not
15122 ocv=dilate:0x0+2x2/custom=diamond.shape|2
15127 Erode an image by using a specific structuring element.
15128 It corresponds to the libopencv function @code{cvErode}.
15130 It accepts the parameters: @var{struct_el}:@var{nb_iterations},
15131 with the same syntax and semantics as the @ref{dilate} filter.
15135 Smooth the input video.
15137 The filter takes the following parameters:
15138 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
15140 @var{type} is the type of smooth filter to apply, and must be one of
15141 the following values: "blur", "blur_no_scale", "median", "gaussian",
15142 or "bilateral". The default value is "gaussian".
15144 The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
15145 depends on the smooth type. @var{param1} and
15146 @var{param2} accept integer positive values or 0. @var{param3} and
15147 @var{param4} accept floating point values.
15149 The default value for @var{param1} is 3. The default value for the
15150 other parameters is 0.
15152 These parameters correspond to the parameters assigned to the
15153 libopencv function @code{cvSmooth}.
15155 @section oscilloscope
15157 2D Video Oscilloscope.
15159 Useful to measure spatial impulse, step responses, chroma delays, etc.
15161 It accepts the following parameters:
15165 Set scope center x position.
15168 Set scope center y position.
15171 Set scope size, relative to frame diagonal.
15174 Set scope tilt/rotation.
15180 Set trace center x position.
15183 Set trace center y position.
15186 Set trace width, relative to width of frame.
15189 Set trace height, relative to height of frame.
15192 Set which components to trace. By default it traces first three components.
15195 Draw trace grid. By default is enabled.
15198 Draw some statistics. By default is enabled.
15201 Draw scope. By default is enabled.
15204 @subsection Commands
15205 This filter supports same @ref{commands} as options.
15206 The command accepts the same syntax of the corresponding option.
15208 If the specified expression is not valid, it is kept at its current
15211 @subsection Examples
15215 Inspect full first row of video frame.
15217 oscilloscope=x=0.5:y=0:s=1
15221 Inspect full last row of video frame.
15223 oscilloscope=x=0.5:y=1:s=1
15227 Inspect full 5th line of video frame of height 1080.
15229 oscilloscope=x=0.5:y=5/1080:s=1
15233 Inspect full last column of video frame.
15235 oscilloscope=x=1:y=0.5:s=1:t=1
15243 Overlay one video on top of another.
15245 It takes two inputs and has one output. The first input is the "main"
15246 video on which the second input is overlaid.
15248 It accepts the following parameters:
15250 A description of the accepted options follows.
15255 Set the expression for the x and y coordinates of the overlaid video
15256 on the main video. Default value is "0" for both expressions. In case
15257 the expression is invalid, it is set to a huge value (meaning that the
15258 overlay will not be displayed within the output visible area).
15261 See @ref{framesync}.
15264 Set when the expressions for @option{x}, and @option{y} are evaluated.
15266 It accepts the following values:
15269 only evaluate expressions once during the filter initialization or
15270 when a command is processed
15273 evaluate expressions for each incoming frame
15276 Default value is @samp{frame}.
15279 See @ref{framesync}.
15282 Set the format for the output video.
15284 It accepts the following values:
15287 force YUV420 output
15290 force YUV420p10 output
15293 force YUV422 output
15296 force YUV422p10 output
15299 force YUV444 output
15302 force packed RGB output
15305 force planar RGB output
15308 automatically pick format
15311 Default value is @samp{yuv420}.
15314 See @ref{framesync}.
15317 Set format of alpha of the overlaid video, it can be @var{straight} or
15318 @var{premultiplied}. Default is @var{straight}.
15321 The @option{x}, and @option{y} expressions can contain the following
15327 The main input width and height.
15331 The overlay input width and height.
15335 The computed values for @var{x} and @var{y}. They are evaluated for
15340 horizontal and vertical chroma subsample values of the output
15341 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
15345 the number of input frame, starting from 0
15348 the position in the file of the input frame, NAN if unknown
15351 The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
15355 This filter also supports the @ref{framesync} options.
15357 Note that the @var{n}, @var{pos}, @var{t} variables are available only
15358 when evaluation is done @emph{per frame}, and will evaluate to NAN
15359 when @option{eval} is set to @samp{init}.
15361 Be aware that frames are taken from each input video in timestamp
15362 order, hence, if their initial timestamps differ, it is a good idea
15363 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
15364 have them begin in the same zero timestamp, as the example for
15365 the @var{movie} filter does.
15367 You can chain together more overlays but you should test the
15368 efficiency of such approach.
15370 @subsection Commands
15372 This filter supports the following commands:
15376 Modify the x and y of the overlay input.
15377 The command accepts the same syntax of the corresponding option.
15379 If the specified expression is not valid, it is kept at its current
15383 @subsection Examples
15387 Draw the overlay at 10 pixels from the bottom right corner of the main
15390 overlay=main_w-overlay_w-10:main_h-overlay_h-10
15393 Using named options the example above becomes:
15395 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
15399 Insert a transparent PNG logo in the bottom left corner of the input,
15400 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
15402 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
15406 Insert 2 different transparent PNG logos (second logo on bottom
15407 right corner) using the @command{ffmpeg} tool:
15409 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
15413 Add a transparent color layer on top of the main video; @code{WxH}
15414 must specify the size of the main input to the overlay filter:
15416 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
15420 Play an original video and a filtered version (here with the deshake
15421 filter) side by side using the @command{ffplay} tool:
15423 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
15426 The above command is the same as:
15428 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
15432 Make a sliding overlay appearing from the left to the right top part of the
15433 screen starting since time 2:
15435 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
15439 Compose output by putting two input videos side to side:
15441 ffmpeg -i left.avi -i right.avi -filter_complex "
15442 nullsrc=size=200x100 [background];
15443 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
15444 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
15445 [background][left] overlay=shortest=1 [background+left];
15446 [background+left][right] overlay=shortest=1:x=100 [left+right]
15451 Mask 10-20 seconds of a video by applying the delogo filter to a section
15453 ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
15454 -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]'
15459 Chain several overlays in cascade:
15461 nullsrc=s=200x200 [bg];
15462 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
15463 [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
15464 [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
15465 [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
15466 [in3] null, [mid2] overlay=100:100 [out0]
15471 @anchor{overlay_cuda}
15472 @section overlay_cuda
15474 Overlay one video on top of another.
15476 This is the CUDA variant of the @ref{overlay} filter.
15477 It only accepts CUDA frames. The underlying input pixel formats have to match.
15479 It takes two inputs and has one output. The first input is the "main"
15480 video on which the second input is overlaid.
15482 It accepts the following parameters:
15487 Set the x and y coordinates of the overlaid video on the main video.
15488 Default value is "0" for both expressions.
15491 See @ref{framesync}.
15494 See @ref{framesync}.
15497 See @ref{framesync}.
15501 This filter also supports the @ref{framesync} options.
15505 Apply Overcomplete Wavelet denoiser.
15507 The filter accepts the following options:
15513 Larger depth values will denoise lower frequency components more, but
15514 slow down filtering.
15516 Must be an int in the range 8-16, default is @code{8}.
15518 @item luma_strength, ls
15521 Must be a double value in the range 0-1000, default is @code{1.0}.
15523 @item chroma_strength, cs
15524 Set chroma strength.
15526 Must be a double value in the range 0-1000, default is @code{1.0}.
15532 Add paddings to the input image, and place the original input at the
15533 provided @var{x}, @var{y} coordinates.
15535 It accepts the following parameters:
15540 Specify an expression for the size of the output image with the
15541 paddings added. If the value for @var{width} or @var{height} is 0, the
15542 corresponding input size is used for the output.
15544 The @var{width} expression can reference the value set by the
15545 @var{height} expression, and vice versa.
15547 The default value of @var{width} and @var{height} is 0.
15551 Specify the offsets to place the input image at within the padded area,
15552 with respect to the top/left border of the output image.
15554 The @var{x} expression can reference the value set by the @var{y}
15555 expression, and vice versa.
15557 The default value of @var{x} and @var{y} is 0.
15559 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
15560 so the input image is centered on the padded area.
15563 Specify the color of the padded area. For the syntax of this option,
15564 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
15565 manual,ffmpeg-utils}.
15567 The default value of @var{color} is "black".
15570 Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression.
15572 It accepts the following values:
15576 Only evaluate expressions once during the filter initialization or when
15577 a command is processed.
15580 Evaluate expressions for each incoming frame.
15584 Default value is @samp{init}.
15587 Pad to aspect instead to a resolution.
15591 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
15592 options are expressions containing the following constants:
15597 The input video width and height.
15601 These are the same as @var{in_w} and @var{in_h}.
15605 The output width and height (the size of the padded area), as
15606 specified by the @var{width} and @var{height} expressions.
15610 These are the same as @var{out_w} and @var{out_h}.
15614 The x and y offsets as specified by the @var{x} and @var{y}
15615 expressions, or NAN if not yet specified.
15618 same as @var{iw} / @var{ih}
15621 input sample aspect ratio
15624 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
15628 The horizontal and vertical chroma subsample values. For example for the
15629 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
15632 @subsection Examples
15636 Add paddings with the color "violet" to the input video. The output video
15637 size is 640x480, and the top-left corner of the input video is placed at
15640 pad=640:480:0:40:violet
15643 The example above is equivalent to the following command:
15645 pad=width=640:height=480:x=0:y=40:color=violet
15649 Pad the input to get an output with dimensions increased by 3/2,
15650 and put the input video at the center of the padded area:
15652 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
15656 Pad the input to get a squared output with size equal to the maximum
15657 value between the input width and height, and put the input video at
15658 the center of the padded area:
15660 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
15664 Pad the input to get a final w/h ratio of 16:9:
15666 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
15670 In case of anamorphic video, in order to set the output display aspect
15671 correctly, it is necessary to use @var{sar} in the expression,
15672 according to the relation:
15674 (ih * X / ih) * sar = output_dar
15675 X = output_dar / sar
15678 Thus the previous example needs to be modified to:
15680 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
15684 Double the output size and put the input video in the bottom-right
15685 corner of the output padded area:
15687 pad="2*iw:2*ih:ow-iw:oh-ih"
15691 @anchor{palettegen}
15692 @section palettegen
15694 Generate one palette for a whole video stream.
15696 It accepts the following options:
15700 Set the maximum number of colors to quantize in the palette.
15701 Note: the palette will still contain 256 colors; the unused palette entries
15704 @item reserve_transparent
15705 Create a palette of 255 colors maximum and reserve the last one for
15706 transparency. Reserving the transparency color is useful for GIF optimization.
15707 If not set, the maximum of colors in the palette will be 256. You probably want
15708 to disable this option for a standalone image.
15711 @item transparency_color
15712 Set the color that will be used as background for transparency.
15715 Set statistics mode.
15717 It accepts the following values:
15720 Compute full frame histograms.
15722 Compute histograms only for the part that differs from previous frame. This
15723 might be relevant to give more importance to the moving part of your input if
15724 the background is static.
15726 Compute new histogram for each frame.
15729 Default value is @var{full}.
15732 The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
15733 (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
15734 color quantization of the palette. This information is also visible at
15735 @var{info} logging level.
15737 @subsection Examples
15741 Generate a representative palette of a given video using @command{ffmpeg}:
15743 ffmpeg -i input.mkv -vf palettegen palette.png
15747 @section paletteuse
15749 Use a palette to downsample an input video stream.
15751 The filter takes two inputs: one video stream and a palette. The palette must
15752 be a 256 pixels image.
15754 It accepts the following options:
15758 Select dithering mode. Available algorithms are:
15761 Ordered 8x8 bayer dithering (deterministic)
15763 Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
15764 Note: this dithering is sometimes considered "wrong" and is included as a
15766 @item floyd_steinberg
15767 Floyd and Steingberg dithering (error diffusion)
15769 Frankie Sierra dithering v2 (error diffusion)
15771 Frankie Sierra dithering v2 "Lite" (error diffusion)
15774 Default is @var{sierra2_4a}.
15777 When @var{bayer} dithering is selected, this option defines the scale of the
15778 pattern (how much the crosshatch pattern is visible). A low value means more
15779 visible pattern for less banding, and higher value means less visible pattern
15780 at the cost of more banding.
15782 The option must be an integer value in the range [0,5]. Default is @var{2}.
15785 If set, define the zone to process
15789 Only the changing rectangle will be reprocessed. This is similar to GIF
15790 cropping/offsetting compression mechanism. This option can be useful for speed
15791 if only a part of the image is changing, and has use cases such as limiting the
15792 scope of the error diffusal @option{dither} to the rectangle that bounds the
15793 moving scene (it leads to more deterministic output if the scene doesn't change
15794 much, and as a result less moving noise and better GIF compression).
15797 Default is @var{none}.
15800 Take new palette for each output frame.
15802 @item alpha_threshold
15803 Sets the alpha threshold for transparency. Alpha values above this threshold
15804 will be treated as completely opaque, and values below this threshold will be
15805 treated as completely transparent.
15807 The option must be an integer value in the range [0,255]. Default is @var{128}.
15810 @subsection Examples
15814 Use a palette (generated for example with @ref{palettegen}) to encode a GIF
15815 using @command{ffmpeg}:
15817 ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
15821 @section perspective
15823 Correct perspective of video not recorded perpendicular to the screen.
15825 A description of the accepted parameters follows.
15836 Set coordinates expression for top left, top right, bottom left and bottom right corners.
15837 Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
15838 If the @code{sense} option is set to @code{source}, then the specified points will be sent
15839 to the corners of the destination. If the @code{sense} option is set to @code{destination},
15840 then the corners of the source will be sent to the specified coordinates.
15842 The expressions can use the following variables:
15847 the width and height of video frame.
15851 Output frame count.
15854 @item interpolation
15855 Set interpolation for perspective correction.
15857 It accepts the following values:
15863 Default value is @samp{linear}.
15866 Set interpretation of coordinate options.
15868 It accepts the following values:
15872 Send point in the source specified by the given coordinates to
15873 the corners of the destination.
15875 @item 1, destination
15877 Send the corners of the source to the point in the destination specified
15878 by the given coordinates.
15880 Default value is @samp{source}.
15884 Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
15886 It accepts the following values:
15889 only evaluate expressions once during the filter initialization or
15890 when a command is processed
15893 evaluate expressions for each incoming frame
15896 Default value is @samp{init}.
15901 Delay interlaced video by one field time so that the field order changes.
15903 The intended use is to fix PAL movies that have been captured with the
15904 opposite field order to the film-to-video transfer.
15906 A description of the accepted parameters follows.
15912 It accepts the following values:
15915 Capture field order top-first, transfer bottom-first.
15916 Filter will delay the bottom field.
15919 Capture field order bottom-first, transfer top-first.
15920 Filter will delay the top field.
15923 Capture and transfer with the same field order. This mode only exists
15924 for the documentation of the other options to refer to, but if you
15925 actually select it, the filter will faithfully do nothing.
15928 Capture field order determined automatically by field flags, transfer
15930 Filter selects among @samp{t} and @samp{b} modes on a frame by frame
15931 basis using field flags. If no field information is available,
15932 then this works just like @samp{u}.
15935 Capture unknown or varying, transfer opposite.
15936 Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
15937 analyzing the images and selecting the alternative that produces best
15938 match between the fields.
15941 Capture top-first, transfer unknown or varying.
15942 Filter selects among @samp{t} and @samp{p} using image analysis.
15945 Capture bottom-first, transfer unknown or varying.
15946 Filter selects among @samp{b} and @samp{p} using image analysis.
15949 Capture determined by field flags, transfer unknown or varying.
15950 Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
15951 image analysis. If no field information is available, then this works just
15952 like @samp{U}. This is the default mode.
15955 Both capture and transfer unknown or varying.
15956 Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
15960 @subsection Commands
15962 This filter supports the all above options as @ref{commands}.
15964 @section photosensitivity
15965 Reduce various flashes in video, so to help users with epilepsy.
15967 It accepts the following options:
15970 Set how many frames to use when filtering. Default is 30.
15973 Set detection threshold factor. Default is 1.
15977 Set how many pixels to skip when sampling frames. Default is 1.
15978 Allowed range is from 1 to 1024.
15981 Leave frames unchanged. Default is disabled.
15984 @section pixdesctest
15986 Pixel format descriptor test filter, mainly useful for internal
15987 testing. The output video should be equal to the input video.
15991 format=monow, pixdesctest
15994 can be used to test the monowhite pixel format descriptor definition.
15998 Display sample values of color channels. Mainly useful for checking color
15999 and levels. Minimum supported resolution is 640x480.
16001 The filters accept the following options:
16005 Set scope X position, relative offset on X axis.
16008 Set scope Y position, relative offset on Y axis.
16017 Set window opacity. This window also holds statistics about pixel area.
16020 Set window X position, relative offset on X axis.
16023 Set window Y position, relative offset on Y axis.
16028 Enable the specified chain of postprocessing subfilters using libpostproc. This
16029 library should be automatically selected with a GPL build (@code{--enable-gpl}).
16030 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
16031 Each subfilter and some options have a short and a long name that can be used
16032 interchangeably, i.e. dr/dering are the same.
16034 The filters accept the following options:
16038 Set postprocessing subfilters string.
16041 All subfilters share common options to determine their scope:
16045 Honor the quality commands for this subfilter.
16048 Do chrominance filtering, too (default).
16051 Do luminance filtering only (no chrominance).
16054 Do chrominance filtering only (no luminance).
16057 These options can be appended after the subfilter name, separated by a '|'.
16059 Available subfilters are:
16062 @item hb/hdeblock[|difference[|flatness]]
16063 Horizontal deblocking filter
16066 Difference factor where higher values mean more deblocking (default: @code{32}).
16068 Flatness threshold where lower values mean more deblocking (default: @code{39}).
16071 @item vb/vdeblock[|difference[|flatness]]
16072 Vertical deblocking filter
16075 Difference factor where higher values mean more deblocking (default: @code{32}).
16077 Flatness threshold where lower values mean more deblocking (default: @code{39}).
16080 @item ha/hadeblock[|difference[|flatness]]
16081 Accurate horizontal deblocking filter
16084 Difference factor where higher values mean more deblocking (default: @code{32}).
16086 Flatness threshold where lower values mean more deblocking (default: @code{39}).
16089 @item va/vadeblock[|difference[|flatness]]
16090 Accurate vertical deblocking filter
16093 Difference factor where higher values mean more deblocking (default: @code{32}).
16095 Flatness threshold where lower values mean more deblocking (default: @code{39}).
16099 The horizontal and vertical deblocking filters share the difference and
16100 flatness values so you cannot set different horizontal and vertical
16104 @item h1/x1hdeblock
16105 Experimental horizontal deblocking filter
16107 @item v1/x1vdeblock
16108 Experimental vertical deblocking filter
16113 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
16116 larger -> stronger filtering
16118 larger -> stronger filtering
16120 larger -> stronger filtering
16123 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
16126 Stretch luminance to @code{0-255}.
16129 @item lb/linblenddeint
16130 Linear blend deinterlacing filter that deinterlaces the given block by
16131 filtering all lines with a @code{(1 2 1)} filter.
16133 @item li/linipoldeint
16134 Linear interpolating deinterlacing filter that deinterlaces the given block by
16135 linearly interpolating every second line.
16137 @item ci/cubicipoldeint
16138 Cubic interpolating deinterlacing filter deinterlaces the given block by
16139 cubically interpolating every second line.
16141 @item md/mediandeint
16142 Median deinterlacing filter that deinterlaces the given block by applying a
16143 median filter to every second line.
16145 @item fd/ffmpegdeint
16146 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
16147 second line with a @code{(-1 4 2 4 -1)} filter.
16150 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
16151 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
16153 @item fq/forceQuant[|quantizer]
16154 Overrides the quantizer table from the input with the constant quantizer you
16162 Default pp filter combination (@code{hb|a,vb|a,dr|a})
16165 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
16168 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
16171 @subsection Examples
16175 Apply horizontal and vertical deblocking, deringing and automatic
16176 brightness/contrast:
16182 Apply default filters without brightness/contrast correction:
16188 Apply default filters and temporal denoiser:
16190 pp=default/tmpnoise|1|2|3
16194 Apply deblocking on luminance only, and switch vertical deblocking on or off
16195 automatically depending on available CPU time:
16202 Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
16203 similar to spp = 6 with 7 point DCT, where only the center sample is
16206 The filter accepts the following options:
16210 Force a constant quantization parameter. It accepts an integer in range
16211 0 to 63. If not set, the filter will use the QP from the video stream
16215 Set thresholding mode. Available modes are:
16219 Set hard thresholding.
16221 Set soft thresholding (better de-ringing effect, but likely blurrier).
16223 Set medium thresholding (good results, default).
16227 @section premultiply
16228 Apply alpha premultiply effect to input video stream using first plane
16229 of second stream as alpha.
16231 Both streams must have same dimensions and same pixel format.
16233 The filter accepts the following option:
16237 Set which planes will be processed, unprocessed planes will be copied.
16238 By default value 0xf, all planes will be processed.
16241 Do not require 2nd input for processing, instead use alpha plane from input stream.
16245 Apply prewitt operator to input video stream.
16247 The filter accepts the following option:
16251 Set which planes will be processed, unprocessed planes will be copied.
16252 By default value 0xf, all planes will be processed.
16255 Set value which will be multiplied with filtered result.
16258 Set value which will be added to filtered result.
16261 @subsection Commands
16263 This filter supports the all above options as @ref{commands}.
16265 @section pseudocolor
16267 Alter frame colors in video with pseudocolors.
16269 This filter accepts the following options:
16273 set pixel first component expression
16276 set pixel second component expression
16279 set pixel third component expression
16282 set pixel fourth component expression, corresponds to the alpha component
16285 set component to use as base for altering colors
16288 Pick one of built-in LUTs. By default is set to none.
16304 Each of them specifies the expression to use for computing the lookup table for
16305 the corresponding pixel component values.
16307 The expressions can contain the following constants and functions:
16312 The input width and height.
16315 The input value for the pixel component.
16317 @item ymin, umin, vmin, amin
16318 The minimum allowed component value.
16320 @item ymax, umax, vmax, amax
16321 The maximum allowed component value.
16324 All expressions default to "val".
16326 @subsection Commands
16328 This filter supports the all above options as @ref{commands}.
16330 @subsection Examples
16334 Change too high luma values to gradient:
16336 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'"
16342 Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
16343 Ratio) between two input videos.
16345 This filter takes in input two input videos, the first input is
16346 considered the "main" source and is passed unchanged to the
16347 output. The second input is used as a "reference" video for computing
16350 Both video inputs must have the same resolution and pixel format for
16351 this filter to work correctly. Also it assumes that both inputs
16352 have the same number of frames, which are compared one by one.
16354 The obtained average PSNR is printed through the logging system.
16356 The filter stores the accumulated MSE (mean squared error) of each
16357 frame, and at the end of the processing it is averaged across all frames
16358 equally, and the following formula is applied to obtain the PSNR:
16361 PSNR = 10*log10(MAX^2/MSE)
16364 Where MAX is the average of the maximum values of each component of the
16367 The description of the accepted parameters follows.
16370 @item stats_file, f
16371 If specified the filter will use the named file to save the PSNR of
16372 each individual frame. When filename equals "-" the data is sent to
16375 @item stats_version
16376 Specifies which version of the stats file format to use. Details of
16377 each format are written below.
16378 Default value is 1.
16380 @item stats_add_max
16381 Determines whether the max value is output to the stats log.
16382 Default value is 0.
16383 Requires stats_version >= 2. If this is set and stats_version < 2,
16384 the filter will return an error.
16387 This filter also supports the @ref{framesync} options.
16389 The file printed if @var{stats_file} is selected, contains a sequence of
16390 key/value pairs of the form @var{key}:@var{value} for each compared
16393 If a @var{stats_version} greater than 1 is specified, a header line precedes
16394 the list of per-frame-pair stats, with key value pairs following the frame
16395 format with the following parameters:
16398 @item psnr_log_version
16399 The version of the log file format. Will match @var{stats_version}.
16402 A comma separated list of the per-frame-pair parameters included in
16406 A description of each shown per-frame-pair parameter follows:
16410 sequential number of the input frame, starting from 1
16413 Mean Square Error pixel-by-pixel average difference of the compared
16414 frames, averaged over all the image components.
16416 @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
16417 Mean Square Error pixel-by-pixel average difference of the compared
16418 frames for the component specified by the suffix.
16420 @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
16421 Peak Signal to Noise ratio of the compared frames for the component
16422 specified by the suffix.
16424 @item max_avg, max_y, max_u, max_v
16425 Maximum allowed value for each channel, and average over all
16429 @subsection Examples
16434 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
16435 [main][ref] psnr="stats_file=stats.log" [out]
16438 On this example the input file being processed is compared with the
16439 reference file @file{ref_movie.mpg}. The PSNR of each individual frame
16440 is stored in @file{stats.log}.
16443 Another example with different containers:
16445 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 -
16452 Pulldown reversal (inverse telecine) filter, capable of handling mixed
16453 hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
16456 The pullup filter is designed to take advantage of future context in making
16457 its decisions. This filter is stateless in the sense that it does not lock
16458 onto a pattern to follow, but it instead looks forward to the following
16459 fields in order to identify matches and rebuild progressive frames.
16461 To produce content with an even framerate, insert the fps filter after
16462 pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
16463 @code{fps=24} for 30fps and the (rare) telecined 25fps input.
16465 The filter accepts the following options:
16472 These options set the amount of "junk" to ignore at the left, right, top, and
16473 bottom of the image, respectively. Left and right are in units of 8 pixels,
16474 while top and bottom are in units of 2 lines.
16475 The default is 8 pixels on each side.
16478 Set the strict breaks. Setting this option to 1 will reduce the chances of
16479 filter generating an occasional mismatched frame, but it may also cause an
16480 excessive number of frames to be dropped during high motion sequences.
16481 Conversely, setting it to -1 will make filter match fields more easily.
16482 This may help processing of video where there is slight blurring between
16483 the fields, but may also cause there to be interlaced frames in the output.
16484 Default value is @code{0}.
16487 Set the metric plane to use. It accepts the following values:
16493 Use chroma blue plane.
16496 Use chroma red plane.
16499 This option may be set to use chroma plane instead of the default luma plane
16500 for doing filter's computations. This may improve accuracy on very clean
16501 source material, but more likely will decrease accuracy, especially if there
16502 is chroma noise (rainbow effect) or any grayscale video.
16503 The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
16504 load and make pullup usable in realtime on slow machines.
16507 For best results (without duplicated frames in the output file) it is
16508 necessary to change the output frame rate. For example, to inverse
16509 telecine NTSC input:
16511 ffmpeg -i input -vf pullup -r 24000/1001 ...
16516 Change video quantization parameters (QP).
16518 The filter accepts the following option:
16522 Set expression for quantization parameter.
16525 The expression is evaluated through the eval API and can contain, among others,
16526 the following constants:
16530 1 if index is not 129, 0 otherwise.
16533 Sequential index starting from -129 to 128.
16536 @subsection Examples
16540 Some equation like:
16548 Flush video frames from internal cache of frames into a random order.
16549 No frame is discarded.
16550 Inspired by @ref{frei0r} nervous filter.
16554 Set size in number of frames of internal cache, in range from @code{2} to
16555 @code{512}. Default is @code{30}.
16558 Set seed for random number generator, must be an integer included between
16559 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
16560 less than @code{0}, the filter will try to use a good random seed on a
16564 @section readeia608
16566 Read closed captioning (EIA-608) information from the top lines of a video frame.
16568 This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and
16569 @code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line
16570 with EIA-608 data (starting from 0). A description of each metadata value follows:
16573 @item lavfi.readeia608.X.cc
16574 The two bytes stored as EIA-608 data (printed in hexadecimal).
16576 @item lavfi.readeia608.X.line
16577 The number of the line on which the EIA-608 data was identified and read.
16580 This filter accepts the following options:
16584 Set the line to start scanning for EIA-608 data. Default is @code{0}.
16587 Set the line to end scanning for EIA-608 data. Default is @code{29}.
16590 Set the ratio of width reserved for sync code detection.
16591 Default is @code{0.27}. Allowed range is @code{[0.1 - 0.7]}.
16594 Enable checking the parity bit. In the event of a parity error, the filter will output
16595 @code{0x00} for that character. Default is false.
16598 Lowpass lines prior to further processing. Default is enabled.
16601 @subsection Commands
16603 This filter supports the all above options as @ref{commands}.
16605 @subsection Examples
16609 Output a csv with presentation time and the first two lines of identified EIA-608 captioning data.
16611 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
16617 Read vertical interval timecode (VITC) information from the top lines of a
16620 The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
16621 timecode value, if a valid timecode has been detected. Further metadata key
16622 @code{lavfi.readvitc.found} is set to 0/1 depending on whether
16623 timecode data has been found or not.
16625 This filter accepts the following options:
16629 Set the maximum number of lines to scan for VITC data. If the value is set to
16630 @code{-1} the full video frame is scanned. Default is @code{45}.
16633 Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
16634 default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
16637 Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
16638 default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
16641 @subsection Examples
16645 Detect and draw VITC data onto the video frame; if no valid VITC is detected,
16646 draw @code{--:--:--:--} as a placeholder:
16648 ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
16654 Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
16656 Destination pixel at position (X, Y) will be picked from source (x, y) position
16657 where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
16658 value for pixel will be used for destination pixel.
16660 Xmap and Ymap input video streams must be of same dimensions. Output video stream
16661 will have Xmap/Ymap video stream dimensions.
16662 Xmap and Ymap input video streams are 16bit depth, single channel.
16666 Specify pixel format of output from this filter. Can be @code{color} or @code{gray}.
16667 Default is @code{color}.
16670 Specify the color of the unmapped pixels. For the syntax of this option,
16671 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
16672 manual,ffmpeg-utils}. Default color is @code{black}.
16675 @section removegrain
16677 The removegrain filter is a spatial denoiser for progressive video.
16681 Set mode for the first plane.
16684 Set mode for the second plane.
16687 Set mode for the third plane.
16690 Set mode for the fourth plane.
16693 Range of mode is from 0 to 24. Description of each mode follows:
16697 Leave input plane unchanged. Default.
16700 Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
16703 Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
16706 Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
16709 Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
16710 This is equivalent to a median filter.
16713 Line-sensitive clipping giving the minimal change.
16716 Line-sensitive clipping, intermediate.
16719 Line-sensitive clipping, intermediate.
16722 Line-sensitive clipping, intermediate.
16725 Line-sensitive clipping on a line where the neighbours pixels are the closest.
16728 Replaces the target pixel with the closest neighbour.
16731 [1 2 1] horizontal and vertical kernel blur.
16737 Bob mode, interpolates top field from the line where the neighbours
16738 pixels are the closest.
16741 Bob mode, interpolates bottom field from the line where the neighbours
16742 pixels are the closest.
16745 Bob mode, interpolates top field. Same as 13 but with a more complicated
16746 interpolation formula.
16749 Bob mode, interpolates bottom field. Same as 14 but with a more complicated
16750 interpolation formula.
16753 Clips the pixel with the minimum and maximum of respectively the maximum and
16754 minimum of each pair of opposite neighbour pixels.
16757 Line-sensitive clipping using opposite neighbours whose greatest distance from
16758 the current pixel is minimal.
16761 Replaces the pixel with the average of its 8 neighbours.
16764 Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
16767 Clips pixels using the averages of opposite neighbour.
16770 Same as mode 21 but simpler and faster.
16773 Small edge and halo removal, but reputed useless.
16779 @section removelogo
16781 Suppress a TV station logo, using an image file to determine which
16782 pixels comprise the logo. It works by filling in the pixels that
16783 comprise the logo with neighboring pixels.
16785 The filter accepts the following options:
16789 Set the filter bitmap file, which can be any image format supported by
16790 libavformat. The width and height of the image file must match those of the
16791 video stream being processed.
16794 Pixels in the provided bitmap image with a value of zero are not
16795 considered part of the logo, non-zero pixels are considered part of
16796 the logo. If you use white (255) for the logo and black (0) for the
16797 rest, you will be safe. For making the filter bitmap, it is
16798 recommended to take a screen capture of a black frame with the logo
16799 visible, and then using a threshold filter followed by the erode
16800 filter once or twice.
16802 If needed, little splotches can be fixed manually. Remember that if
16803 logo pixels are not covered, the filter quality will be much
16804 reduced. Marking too many pixels as part of the logo does not hurt as
16805 much, but it will increase the amount of blurring needed to cover over
16806 the image and will destroy more information than necessary, and extra
16807 pixels will slow things down on a large logo.
16809 @section repeatfields
16811 This filter uses the repeat_field flag from the Video ES headers and hard repeats
16812 fields based on its value.
16816 Reverse a video clip.
16818 Warning: This filter requires memory to buffer the entire clip, so trimming
16821 @subsection Examples
16825 Take the first 5 seconds of a clip, and reverse it.
16832 Shift R/G/B/A pixels horizontally and/or vertically.
16834 The filter accepts the following options:
16837 Set amount to shift red horizontally.
16839 Set amount to shift red vertically.
16841 Set amount to shift green horizontally.
16843 Set amount to shift green vertically.
16845 Set amount to shift blue horizontally.
16847 Set amount to shift blue vertically.
16849 Set amount to shift alpha horizontally.
16851 Set amount to shift alpha vertically.
16853 Set edge mode, can be @var{smear}, default, or @var{warp}.
16856 @subsection Commands
16858 This filter supports the all above options as @ref{commands}.
16861 Apply roberts cross operator to input video stream.
16863 The filter accepts the following option:
16867 Set which planes will be processed, unprocessed planes will be copied.
16868 By default value 0xf, all planes will be processed.
16871 Set value which will be multiplied with filtered result.
16874 Set value which will be added to filtered result.
16877 @subsection Commands
16879 This filter supports the all above options as @ref{commands}.
16883 Rotate video by an arbitrary angle expressed in radians.
16885 The filter accepts the following options:
16887 A description of the optional parameters follows.
16890 Set an expression for the angle by which to rotate the input video
16891 clockwise, expressed as a number of radians. A negative value will
16892 result in a counter-clockwise rotation. By default it is set to "0".
16894 This expression is evaluated for each frame.
16897 Set the output width expression, default value is "iw".
16898 This expression is evaluated just once during configuration.
16901 Set the output height expression, default value is "ih".
16902 This expression is evaluated just once during configuration.
16905 Enable bilinear interpolation if set to 1, a value of 0 disables
16906 it. Default value is 1.
16909 Set the color used to fill the output area not covered by the rotated
16910 image. For the general syntax of this option, check the
16911 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
16912 If the special value "none" is selected then no
16913 background is printed (useful for example if the background is never shown).
16915 Default value is "black".
16918 The expressions for the angle and the output size can contain the
16919 following constants and functions:
16923 sequential number of the input frame, starting from 0. It is always NAN
16924 before the first frame is filtered.
16927 time in seconds of the input frame, it is set to 0 when the filter is
16928 configured. It is always NAN before the first frame is filtered.
16932 horizontal and vertical chroma subsample values. For example for the
16933 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16937 the input video width and height
16941 the output width and height, that is the size of the padded area as
16942 specified by the @var{width} and @var{height} expressions
16946 the minimal width/height required for completely containing the input
16947 video rotated by @var{a} radians.
16949 These are only available when computing the @option{out_w} and
16950 @option{out_h} expressions.
16953 @subsection Examples
16957 Rotate the input by PI/6 radians clockwise:
16963 Rotate the input by PI/6 radians counter-clockwise:
16969 Rotate the input by 45 degrees clockwise:
16975 Apply a constant rotation with period T, starting from an angle of PI/3:
16977 rotate=PI/3+2*PI*t/T
16981 Make the input video rotation oscillating with a period of T
16982 seconds and an amplitude of A radians:
16984 rotate=A*sin(2*PI/T*t)
16988 Rotate the video, output size is chosen so that the whole rotating
16989 input video is always completely contained in the output:
16991 rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
16995 Rotate the video, reduce the output size so that no background is ever
16998 rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
17002 @subsection Commands
17004 The filter supports the following commands:
17008 Set the angle 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
17017 Apply Shape Adaptive Blur.
17019 The filter accepts the following options:
17022 @item luma_radius, lr
17023 Set luma blur filter strength, must be a value in range 0.1-4.0, default
17024 value is 1.0. A greater value will result in a more blurred image, and
17025 in slower processing.
17027 @item luma_pre_filter_radius, lpfr
17028 Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
17031 @item luma_strength, ls
17032 Set luma maximum difference between pixels to still be considered, must
17033 be a value in the 0.1-100.0 range, default value is 1.0.
17035 @item chroma_radius, cr
17036 Set chroma blur filter strength, must be a value in range -0.9-4.0. A
17037 greater value will result in a more blurred image, and in slower
17040 @item chroma_pre_filter_radius, cpfr
17041 Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
17043 @item chroma_strength, cs
17044 Set chroma maximum difference between pixels to still be considered,
17045 must be a value in the -0.9-100.0 range.
17048 Each chroma option value, if not explicitly specified, is set to the
17049 corresponding luma option value.
17054 Scale (resize) the input video, using the libswscale library.
17056 The scale filter forces the output display aspect ratio to be the same
17057 of the input, by changing the output sample aspect ratio.
17059 If the input image format is different from the format requested by
17060 the next filter, the scale filter will convert the input to the
17063 @subsection Options
17064 The filter accepts the following options, or any of the options
17065 supported by the libswscale scaler.
17067 See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
17068 the complete list of scaler options.
17073 Set the output video dimension expression. Default value is the input
17076 If the @var{width} or @var{w} value is 0, the input width is used for
17077 the output. If the @var{height} or @var{h} value is 0, the input height
17078 is used for the output.
17080 If one and only one of the values is -n with n >= 1, the scale filter
17081 will use a value that maintains the aspect ratio of the input image,
17082 calculated from the other specified dimension. After that it will,
17083 however, make sure that the calculated dimension is divisible by n and
17084 adjust the value if necessary.
17086 If both values are -n with n >= 1, the behavior will be identical to
17087 both values being set to 0 as previously detailed.
17089 See below for the list of accepted constants for use in the dimension
17093 Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
17097 Only evaluate expressions once during the filter initialization or when a command is processed.
17100 Evaluate expressions for each incoming frame.
17104 Default value is @samp{init}.
17108 Set the interlacing mode. It accepts the following values:
17112 Force interlaced aware scaling.
17115 Do not apply interlaced scaling.
17118 Select interlaced aware scaling depending on whether the source frames
17119 are flagged as interlaced or not.
17122 Default value is @samp{0}.
17125 Set libswscale scaling flags. See
17126 @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
17127 complete list of values. If not explicitly specified the filter applies
17131 @item param0, param1
17132 Set libswscale input parameters for scaling algorithms that need them. See
17133 @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
17134 complete documentation. If not explicitly specified the filter applies
17140 Set the video size. For the syntax of this option, check the
17141 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17143 @item in_color_matrix
17144 @item out_color_matrix
17145 Set in/output YCbCr color space type.
17147 This allows the autodetected value to be overridden as well as allows forcing
17148 a specific value used for the output and encoder.
17150 If not specified, the color space type depends on the pixel format.
17156 Choose automatically.
17159 Format conforming to International Telecommunication Union (ITU)
17160 Recommendation BT.709.
17163 Set color space conforming to the United States Federal Communications
17164 Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
17169 Set color space conforming to:
17173 ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
17176 ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
17179 Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
17184 Set color space conforming to SMPTE ST 240:1999.
17187 Set color space conforming to ITU-R BT.2020 non-constant luminance system.
17192 Set in/output YCbCr sample range.
17194 This allows the autodetected value to be overridden as well as allows forcing
17195 a specific value used for the output and encoder. If not specified, the
17196 range depends on the pixel format. Possible values:
17200 Choose automatically.
17203 Set full range (0-255 in case of 8-bit luma).
17205 @item mpeg/limited/tv
17206 Set "MPEG" range (16-235 in case of 8-bit luma).
17209 @item force_original_aspect_ratio
17210 Enable decreasing or increasing output video width or height if necessary to
17211 keep the original aspect ratio. Possible values:
17215 Scale the video as specified and disable this feature.
17218 The output video dimensions will automatically be decreased if needed.
17221 The output video dimensions will automatically be increased if needed.
17225 One useful instance of this option is that when you know a specific device's
17226 maximum allowed resolution, you can use this to limit the output video to
17227 that, while retaining the aspect ratio. For example, device A allows
17228 1280x720 playback, and your video is 1920x800. Using this option (set it to
17229 decrease) and specifying 1280x720 to the command line makes the output
17232 Please note that this is a different thing than specifying -1 for @option{w}
17233 or @option{h}, you still need to specify the output resolution for this option
17236 @item force_divisible_by
17237 Ensures that both the output dimensions, width and height, are divisible by the
17238 given integer when used together with @option{force_original_aspect_ratio}. This
17239 works similar to using @code{-n} in the @option{w} and @option{h} options.
17241 This option respects the value set for @option{force_original_aspect_ratio},
17242 increasing or decreasing the resolution accordingly. The video's aspect ratio
17243 may be slightly modified.
17245 This option can be handy if you need to have a video fit within or exceed
17246 a defined resolution using @option{force_original_aspect_ratio} but also have
17247 encoder restrictions on width or height divisibility.
17251 The values of the @option{w} and @option{h} options are expressions
17252 containing the following constants:
17257 The input width and height
17261 These are the same as @var{in_w} and @var{in_h}.
17265 The output (scaled) width and height
17269 These are the same as @var{out_w} and @var{out_h}
17272 The same as @var{iw} / @var{ih}
17275 input sample aspect ratio
17278 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
17282 horizontal and vertical input chroma subsample values. For example for the
17283 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
17287 horizontal and vertical output chroma subsample values. For example for the
17288 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
17291 The (sequential) number of the input frame, starting from 0.
17292 Only available with @code{eval=frame}.
17295 The presentation timestamp of the input frame, expressed as a number of
17296 seconds. Only available with @code{eval=frame}.
17299 The position (byte offset) of the frame in the input stream, or NaN if
17300 this information is unavailable and/or meaningless (for example in case of synthetic video).
17301 Only available with @code{eval=frame}.
17304 @subsection Examples
17308 Scale the input video to a size of 200x100
17313 This is equivalent to:
17324 Specify a size abbreviation for the output size:
17329 which can also be written as:
17335 Scale the input to 2x:
17337 scale=w=2*iw:h=2*ih
17341 The above is the same as:
17343 scale=2*in_w:2*in_h
17347 Scale the input to 2x with forced interlaced scaling:
17349 scale=2*iw:2*ih:interl=1
17353 Scale the input to half size:
17355 scale=w=iw/2:h=ih/2
17359 Increase the width, and set the height to the same size:
17365 Seek Greek harmony:
17372 Increase the height, and set the width to 3/2 of the height:
17374 scale=w=3/2*oh:h=3/5*ih
17378 Increase the size, making the size a multiple of the chroma
17381 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
17385 Increase the width to a maximum of 500 pixels,
17386 keeping the same aspect ratio as the input:
17388 scale=w='min(500\, iw*3/2):h=-1'
17392 Make pixels square by combining scale and setsar:
17394 scale='trunc(ih*dar):ih',setsar=1/1
17398 Make pixels square by combining scale and setsar,
17399 making sure the resulting resolution is even (required by some codecs):
17401 scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1
17405 @subsection Commands
17407 This filter supports the following commands:
17411 Set the output video dimension expression.
17412 The command accepts the same syntax of the corresponding option.
17414 If the specified expression is not valid, it is kept at its current
17420 Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
17421 format conversion on CUDA video frames. Setting the output width and height
17422 works in the same way as for the @var{scale} filter.
17424 The following additional options are accepted:
17427 The pixel format of the output CUDA frames. If set to the string "same" (the
17428 default), the input format will be kept. Note that automatic format negotiation
17429 and conversion is not yet supported for hardware frames
17432 The interpolation algorithm used for resizing. One of the following:
17439 @item cubic2p_bspline
17440 2-parameter cubic (B=1, C=0)
17442 @item cubic2p_catmullrom
17443 2-parameter cubic (B=0, C=1/2)
17445 @item cubic2p_b05c03
17446 2-parameter cubic (B=1/2, C=3/10)
17454 @item force_original_aspect_ratio
17455 Enable decreasing or increasing output video width or height if necessary to
17456 keep the original aspect ratio. Possible values:
17460 Scale the video as specified and disable this feature.
17463 The output video dimensions will automatically be decreased if needed.
17466 The output video dimensions will automatically be increased if needed.
17470 One useful instance of this option is that when you know a specific device's
17471 maximum allowed resolution, you can use this to limit the output video to
17472 that, while retaining the aspect ratio. For example, device A allows
17473 1280x720 playback, and your video is 1920x800. Using this option (set it to
17474 decrease) and specifying 1280x720 to the command line makes the output
17477 Please note that this is a different thing than specifying -1 for @option{w}
17478 or @option{h}, you still need to specify the output resolution for this option
17481 @item force_divisible_by
17482 Ensures that both the output dimensions, width and height, are divisible by the
17483 given integer when used together with @option{force_original_aspect_ratio}. This
17484 works similar to using @code{-n} in the @option{w} and @option{h} options.
17486 This option respects the value set for @option{force_original_aspect_ratio},
17487 increasing or decreasing the resolution accordingly. The video's aspect ratio
17488 may be slightly modified.
17490 This option can be handy if you need to have a video fit within or exceed
17491 a defined resolution using @option{force_original_aspect_ratio} but also have
17492 encoder restrictions on width or height divisibility.
17498 Scale (resize) the input video, based on a reference video.
17500 See the scale filter for available options, scale2ref supports the same but
17501 uses the reference video instead of the main input as basis. scale2ref also
17502 supports the following additional constants for the @option{w} and
17503 @option{h} options:
17508 The main input video's width and height
17511 The same as @var{main_w} / @var{main_h}
17514 The main input video's sample aspect ratio
17516 @item main_dar, mdar
17517 The main input video's display aspect ratio. Calculated from
17518 @code{(main_w / main_h) * main_sar}.
17522 The main input video's horizontal and vertical chroma subsample values.
17523 For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub}
17527 The (sequential) number of the main input frame, starting from 0.
17528 Only available with @code{eval=frame}.
17531 The presentation timestamp of the main input frame, expressed as a number of
17532 seconds. Only available with @code{eval=frame}.
17535 The position (byte offset) of the frame in the main input stream, or NaN if
17536 this information is unavailable and/or meaningless (for example in case of synthetic video).
17537 Only available with @code{eval=frame}.
17540 @subsection Examples
17544 Scale a subtitle stream (b) to match the main video (a) in size before overlaying
17546 'scale2ref[b][a];[a][b]overlay'
17550 Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio.
17552 [logo-in][video-in]scale2ref=w=oh*mdar:h=ih/10[logo-out][video-out]
17556 @subsection Commands
17558 This filter supports the following commands:
17562 Set the output video dimension expression.
17563 The command accepts the same syntax of the corresponding option.
17565 If the specified expression is not valid, it is kept at its current
17570 Scroll input video horizontally and/or vertically by constant speed.
17572 The filter accepts the following options:
17574 @item horizontal, h
17575 Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1.
17576 Negative values changes scrolling direction.
17579 Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1.
17580 Negative values changes scrolling direction.
17583 Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1.
17586 Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1.
17589 @subsection Commands
17591 This filter supports the following @ref{commands}:
17593 @item horizontal, h
17594 Set the horizontal scrolling speed.
17596 Set the vertical scrolling speed.
17602 Detect video scene change.
17604 This filter sets frame metadata with mafd between frame, the scene score, and
17605 forward the frame to the next filter, so they can use these metadata to detect
17606 scene change or others.
17608 In addition, this filter logs a message and sets frame metadata when it detects
17609 a scene change by @option{threshold}.
17611 @code{lavfi.scd.mafd} metadata keys are set with mafd for every frame.
17613 @code{lavfi.scd.score} metadata keys are set with scene change score for every frame
17614 to detect scene change.
17616 @code{lavfi.scd.time} metadata keys are set with current filtered frame time which
17617 detect scene change with @option{threshold}.
17619 The filter accepts the following options:
17623 Set the scene change detection threshold as a percentage of maximum change. Good
17624 values are in the @code{[8.0, 14.0]} range. The range for @option{threshold} is
17627 Default value is @code{10.}.
17630 Set the flag to pass scene change frames to the next filter. Default value is @code{0}
17631 You can enable it if you want to get snapshot of scene change frames only.
17634 @anchor{selectivecolor}
17635 @section selectivecolor
17637 Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
17638 as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
17639 by the "purity" of the color (that is, how saturated it already is).
17641 This filter is similar to the Adobe Photoshop Selective Color tool.
17643 The filter accepts the following options:
17646 @item correction_method
17647 Select color correction method.
17649 Available values are:
17652 Specified adjustments are applied "as-is" (added/subtracted to original pixel
17655 Specified adjustments are relative to the original component value.
17657 Default is @code{absolute}.
17659 Adjustments for red pixels (pixels where the red component is the maximum)
17661 Adjustments for yellow pixels (pixels where the blue component is the minimum)
17663 Adjustments for green pixels (pixels where the green component is the maximum)
17665 Adjustments for cyan pixels (pixels where the red component is the minimum)
17667 Adjustments for blue pixels (pixels where the blue component is the maximum)
17669 Adjustments for magenta pixels (pixels where the green component is the minimum)
17671 Adjustments for white pixels (pixels where all components are greater than 128)
17673 Adjustments for all pixels except pure black and pure white
17675 Adjustments for black pixels (pixels where all components are lesser than 128)
17677 Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
17680 All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
17681 4 space separated floating point adjustment values in the [-1,1] range,
17682 respectively to adjust the amount of cyan, magenta, yellow and black for the
17683 pixels of its range.
17685 @subsection Examples
17689 Increase cyan by 50% and reduce yellow by 33% in every green areas, and
17690 increase magenta by 27% in blue areas:
17692 selectivecolor=greens=.5 0 -.33 0:blues=0 .27
17696 Use a Photoshop selective color preset:
17698 selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
17702 @anchor{separatefields}
17703 @section separatefields
17705 The @code{separatefields} takes a frame-based video input and splits
17706 each frame into its components fields, producing a new half height clip
17707 with twice the frame rate and twice the frame count.
17709 This filter use field-dominance information in frame to decide which
17710 of each pair of fields to place first in the output.
17711 If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
17713 @section setdar, setsar
17715 The @code{setdar} filter sets the Display Aspect Ratio for the filter
17718 This is done by changing the specified Sample (aka Pixel) Aspect
17719 Ratio, according to the following equation:
17721 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
17724 Keep in mind that the @code{setdar} filter does not modify the pixel
17725 dimensions of the video frame. Also, the display aspect ratio set by
17726 this filter may be changed by later filters in the filterchain,
17727 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
17730 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
17731 the filter output video.
17733 Note that as a consequence of the application of this filter, the
17734 output display aspect ratio will change according to the equation
17737 Keep in mind that the sample aspect ratio set by the @code{setsar}
17738 filter may be changed by later filters in the filterchain, e.g. if
17739 another "setsar" or a "setdar" filter is applied.
17741 It accepts the following parameters:
17744 @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
17745 Set the aspect ratio used by the filter.
17747 The parameter can be a floating point number string, an expression, or
17748 a string of the form @var{num}:@var{den}, where @var{num} and
17749 @var{den} are the numerator and denominator of the aspect ratio. If
17750 the parameter is not specified, it is assumed the value "0".
17751 In case the form "@var{num}:@var{den}" is used, the @code{:} character
17755 Set the maximum integer value to use for expressing numerator and
17756 denominator when reducing the expressed aspect ratio to a rational.
17757 Default value is @code{100}.
17761 The parameter @var{sar} is an expression containing
17762 the following constants:
17766 These are approximated values for the mathematical constants e
17767 (Euler's number), pi (Greek pi), and phi (the golden ratio).
17770 The input width and height.
17773 These are the same as @var{w} / @var{h}.
17776 The input sample aspect ratio.
17779 The input display aspect ratio. It is the same as
17780 (@var{w} / @var{h}) * @var{sar}.
17783 Horizontal and vertical chroma subsample values. For example, for the
17784 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
17787 @subsection Examples
17792 To change the display aspect ratio to 16:9, specify one of the following:
17799 To change the sample aspect ratio to 10:11, specify:
17805 To set a display aspect ratio of 16:9, and specify a maximum integer value of
17806 1000 in the aspect ratio reduction, use the command:
17808 setdar=ratio=16/9:max=1000
17816 Force field for the output video frame.
17818 The @code{setfield} filter marks the interlace type field for the
17819 output frames. It does not change the input frame, but only sets the
17820 corresponding property, which affects how the frame is treated by
17821 following filters (e.g. @code{fieldorder} or @code{yadif}).
17823 The filter accepts the following options:
17828 Available values are:
17832 Keep the same field property.
17835 Mark the frame as bottom-field-first.
17838 Mark the frame as top-field-first.
17841 Mark the frame as progressive.
17848 Force frame parameter for the output video frame.
17850 The @code{setparams} filter marks interlace and color range for the
17851 output frames. It does not change the input frame, but only sets the
17852 corresponding property, which affects how the frame is treated by
17857 Available values are:
17861 Keep the same field property (default).
17864 Mark the frame as bottom-field-first.
17867 Mark the frame as top-field-first.
17870 Mark the frame as progressive.
17874 Available values are:
17878 Keep the same color range property (default).
17880 @item unspecified, unknown
17881 Mark the frame as unspecified color range.
17883 @item limited, tv, mpeg
17884 Mark the frame as limited range.
17886 @item full, pc, jpeg
17887 Mark the frame as full range.
17890 @item color_primaries
17891 Set the color primaries.
17892 Available values are:
17896 Keep the same color primaries property (default).
17913 Set the color transfer.
17914 Available values are:
17918 Keep the same color trc property (default).
17940 Set the colorspace.
17941 Available values are:
17945 Keep the same colorspace property (default).
17958 @item chroma-derived-nc
17959 @item chroma-derived-c
17965 Apply shear transform to input video.
17967 This filter supports the following options:
17971 Shear factor in X-direction. Default value is 0.
17972 Allowed range is from -2 to 2.
17975 Shear factor in Y-direction. Default value is 0.
17976 Allowed range is from -2 to 2.
17979 Set the color used to fill the output area not covered by the transformed
17980 video. For the general syntax of this option, check the
17981 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
17982 If the special value "none" is selected then no
17983 background is printed (useful for example if the background is never shown).
17985 Default value is "black".
17988 Set interpolation type. Can be @code{bilinear} or @code{nearest}. Default is @code{bilinear}.
17991 @subsection Commands
17993 This filter supports the all above options as @ref{commands}.
17997 Show a line containing various information for each input video frame.
17998 The input video is not modified.
18000 This filter supports the following options:
18004 Calculate checksums of each plane. By default enabled.
18007 The shown line contains a sequence of key/value pairs of the form
18008 @var{key}:@var{value}.
18010 The following values are shown in the output:
18014 The (sequential) number of the input frame, starting from 0.
18017 The Presentation TimeStamp of the input frame, expressed as a number of
18018 time base units. The time base unit depends on the filter input pad.
18021 The Presentation TimeStamp of the input frame, expressed as a number of
18025 The position of the frame in the input stream, or -1 if this information is
18026 unavailable and/or meaningless (for example in case of synthetic video).
18029 The pixel format name.
18032 The sample aspect ratio of the input frame, expressed in the form
18033 @var{num}/@var{den}.
18036 The size of the input frame. For the syntax of this option, check the
18037 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18040 The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
18041 for bottom field first).
18044 This is 1 if the frame is a key frame, 0 otherwise.
18047 The picture type of the input frame ("I" for an I-frame, "P" for a
18048 P-frame, "B" for a B-frame, or "?" for an unknown type).
18049 Also refer to the documentation of the @code{AVPictureType} enum and of
18050 the @code{av_get_picture_type_char} function defined in
18051 @file{libavutil/avutil.h}.
18054 The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
18056 @item plane_checksum
18057 The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
18058 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
18061 The mean value of pixels in each plane of the input frame, expressed in the form
18062 "[@var{mean0} @var{mean1} @var{mean2} @var{mean3}]".
18065 The standard deviation of pixel values in each plane of the input frame, expressed
18066 in the form "[@var{stdev0} @var{stdev1} @var{stdev2} @var{stdev3}]".
18070 @section showpalette
18072 Displays the 256 colors palette of each frame. This filter is only relevant for
18073 @var{pal8} pixel format frames.
18075 It accepts the following option:
18079 Set the size of the box used to represent one palette color entry. Default is
18080 @code{30} (for a @code{30x30} pixel box).
18083 @section shuffleframes
18085 Reorder and/or duplicate and/or drop video frames.
18087 It accepts the following parameters:
18091 Set the destination indexes of input frames.
18092 This is space or '|' separated list of indexes that maps input frames to output
18093 frames. Number of indexes also sets maximal value that each index may have.
18094 '-1' index have special meaning and that is to drop frame.
18097 The first frame has the index 0. The default is to keep the input unchanged.
18099 @subsection Examples
18103 Swap second and third frame of every three frames of the input:
18105 ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
18109 Swap 10th and 1st frame of every ten frames of the input:
18111 ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
18115 @section shufflepixels
18117 Reorder pixels in video frames.
18119 This filter accepts the following options:
18123 Set shuffle direction. Can be forward or inverse direction.
18124 Default direction is forward.
18127 Set shuffle mode. Can be horizontal, vertical or block mode.
18131 Set shuffle block_size. In case of horizontal shuffle mode only width
18132 part of size is used, and in case of vertical shuffle mode only height
18133 part of size is used.
18136 Set random seed used with shuffling pixels. Mainly useful to set to be able
18137 to reverse filtering process to get original input.
18138 For example, to reverse forward shuffle you need to use same parameters
18139 and exact same seed and to set direction to inverse.
18142 @section shuffleplanes
18144 Reorder and/or duplicate video planes.
18146 It accepts the following parameters:
18151 The index of the input plane to be used as the first output plane.
18154 The index of the input plane to be used as the second output plane.
18157 The index of the input plane to be used as the third output plane.
18160 The index of the input plane to be used as the fourth output plane.
18164 The first plane has the index 0. The default is to keep the input unchanged.
18166 @subsection Examples
18170 Swap the second and third planes of the input:
18172 ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
18176 @anchor{signalstats}
18177 @section signalstats
18178 Evaluate various visual metrics that assist in determining issues associated
18179 with the digitization of analog video media.
18181 By default the filter will log these metadata values:
18185 Display the minimal Y value contained within the input frame. Expressed in
18189 Display the Y value at the 10% percentile within the input frame. Expressed in
18193 Display the average Y value within the input frame. Expressed in range of
18197 Display the Y value at the 90% percentile within the input frame. Expressed in
18201 Display the maximum Y value contained within the input frame. Expressed in
18205 Display the minimal U value contained within the input frame. Expressed in
18209 Display the U value at the 10% percentile within the input frame. Expressed in
18213 Display the average U value within the input frame. Expressed in range of
18217 Display the U value at the 90% percentile within the input frame. Expressed in
18221 Display the maximum U value contained within the input frame. Expressed in
18225 Display the minimal V value contained within the input frame. Expressed in
18229 Display the V value at the 10% percentile within the input frame. Expressed in
18233 Display the average V value within the input frame. Expressed in range of
18237 Display the V value at the 90% percentile within the input frame. Expressed in
18241 Display the maximum V value contained within the input frame. Expressed in
18245 Display the minimal saturation value contained within the input frame.
18246 Expressed in range of [0-~181.02].
18249 Display the saturation value at the 10% percentile within the input frame.
18250 Expressed in range of [0-~181.02].
18253 Display the average saturation value within the input frame. Expressed in range
18257 Display the saturation value at the 90% percentile within the input frame.
18258 Expressed in range of [0-~181.02].
18261 Display the maximum saturation value contained within the input frame.
18262 Expressed in range of [0-~181.02].
18265 Display the median value for hue within the input frame. Expressed in range of
18269 Display the average value for hue within the input frame. Expressed in range of
18273 Display the average of sample value difference between all values of the Y
18274 plane in the current frame and corresponding values of the previous input frame.
18275 Expressed in range of [0-255].
18278 Display the average of sample value difference between all values of the U
18279 plane in the current frame and corresponding values of the previous input frame.
18280 Expressed in range of [0-255].
18283 Display the average of sample value difference between all values of the V
18284 plane in the current frame and corresponding values of the previous input frame.
18285 Expressed in range of [0-255].
18288 Display bit depth of Y plane in current frame.
18289 Expressed in range of [0-16].
18292 Display bit depth of U plane in current frame.
18293 Expressed in range of [0-16].
18296 Display bit depth of V plane in current frame.
18297 Expressed in range of [0-16].
18300 The filter accepts the following options:
18306 @option{stat} specify an additional form of image analysis.
18307 @option{out} output video with the specified type of pixel highlighted.
18309 Both options accept the following values:
18313 Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
18314 unlike the neighboring pixels of the same field. Examples of temporal outliers
18315 include the results of video dropouts, head clogs, or tape tracking issues.
18318 Identify @var{vertical line repetition}. Vertical line repetition includes
18319 similar rows of pixels within a frame. In born-digital video vertical line
18320 repetition is common, but this pattern is uncommon in video digitized from an
18321 analog source. When it occurs in video that results from the digitization of an
18322 analog source it can indicate concealment from a dropout compensator.
18325 Identify pixels that fall outside of legal broadcast range.
18329 Set the highlight color for the @option{out} option. The default color is
18333 @subsection Examples
18337 Output data of various video metrics:
18339 ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
18343 Output specific data about the minimum and maximum values of the Y plane per frame:
18345 ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
18349 Playback video while highlighting pixels that are outside of broadcast range in red.
18351 ffplay example.mov -vf signalstats="out=brng:color=red"
18355 Playback video with signalstats metadata drawn over the frame.
18357 ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
18360 The contents of signalstat_drawtext.txt used in the command are:
18363 Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
18364 U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
18365 V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
18366 saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
18374 Calculates the MPEG-7 Video Signature. The filter can handle more than one
18375 input. In this case the matching between the inputs can be calculated additionally.
18376 The filter always passes through the first input. The signature of each stream can
18377 be written into a file.
18379 It accepts the following options:
18383 Enable or disable the matching process.
18385 Available values are:
18389 Disable the calculation of a matching (default).
18391 Calculate the matching for the whole video and output whether the whole video
18392 matches or only parts.
18394 Calculate only until a matching is found or the video ends. Should be faster in
18399 Set the number of inputs. The option value must be a non negative integer.
18400 Default value is 1.
18403 Set the path to which the output is written. If there is more than one input,
18404 the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive
18405 integer), that will be replaced with the input number. If no filename is
18406 specified, no output will be written. This is the default.
18409 Choose the output format.
18411 Available values are:
18415 Use the specified binary representation (default).
18417 Use the specified xml representation.
18421 Set threshold to detect one word as similar. The option value must be an integer
18422 greater than zero. The default value is 9000.
18425 Set threshold to detect all words as similar. The option value must be an integer
18426 greater than zero. The default value is 60000.
18429 Set threshold to detect frames as similar. The option value must be an integer
18430 greater than zero. The default value is 116.
18433 Set the minimum length of a sequence in frames to recognize it as matching
18434 sequence. The option value must be a non negative integer value.
18435 The default value is 0.
18438 Set the minimum relation, that matching frames to all frames must have.
18439 The option value must be a double value between 0 and 1. The default value is 0.5.
18442 @subsection Examples
18446 To calculate the signature of an input video and store it in signature.bin:
18448 ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
18452 To detect whether two videos match and store the signatures in XML format in
18453 signature0.xml and signature1.xml:
18455 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 -
18463 Blur the input video without impacting the outlines.
18465 It accepts the following options:
18468 @item luma_radius, lr
18469 Set the luma radius. The option value must be a float number in
18470 the range [0.1,5.0] that specifies the variance of the gaussian filter
18471 used to blur the image (slower if larger). Default value is 1.0.
18473 @item luma_strength, ls
18474 Set the luma strength. The option value must be a float number
18475 in the range [-1.0,1.0] that configures the blurring. A value included
18476 in [0.0,1.0] will blur the image whereas a value included in
18477 [-1.0,0.0] will sharpen the image. Default value is 1.0.
18479 @item luma_threshold, lt
18480 Set the luma threshold used as a coefficient to determine
18481 whether a pixel should be blurred or not. The option value must be an
18482 integer in the range [-30,30]. A value of 0 will filter all the image,
18483 a value included in [0,30] will filter flat areas and a value included
18484 in [-30,0] will filter edges. Default value is 0.
18486 @item chroma_radius, cr
18487 Set the chroma radius. The option value must be a float number in
18488 the range [0.1,5.0] that specifies the variance of the gaussian filter
18489 used to blur the image (slower if larger). Default value is @option{luma_radius}.
18491 @item chroma_strength, cs
18492 Set the chroma strength. The option value must be a float number
18493 in the range [-1.0,1.0] that configures the blurring. A value included
18494 in [0.0,1.0] will blur the image whereas a value included in
18495 [-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}.
18497 @item chroma_threshold, ct
18498 Set the chroma threshold used as a coefficient to determine
18499 whether a pixel should be blurred or not. The option value must be an
18500 integer in the range [-30,30]. A value of 0 will filter all the image,
18501 a value included in [0,30] will filter flat areas and a value included
18502 in [-30,0] will filter edges. Default value is @option{luma_threshold}.
18505 If a chroma option is not explicitly set, the corresponding luma value
18509 Apply sobel operator to input video stream.
18511 The filter accepts the following option:
18515 Set which planes will be processed, unprocessed planes will be copied.
18516 By default value 0xf, all planes will be processed.
18519 Set value which will be multiplied with filtered result.
18522 Set value which will be added to filtered result.
18525 @subsection Commands
18527 This filter supports the all above options as @ref{commands}.
18532 Apply a simple postprocessing filter that compresses and decompresses the image
18533 at several (or - in the case of @option{quality} level @code{6} - all) shifts
18534 and average the results.
18536 The filter accepts the following options:
18540 Set quality. This option defines the number of levels for averaging. It accepts
18541 an integer in the range 0-6. If set to @code{0}, the filter will have no
18542 effect. A value of @code{6} means the higher quality. For each increment of
18543 that value the speed drops by a factor of approximately 2. Default value is
18547 Force a constant quantization parameter. If not set, the filter will use the QP
18548 from the video stream (if available).
18551 Set thresholding mode. Available modes are:
18555 Set hard thresholding (default).
18557 Set soft thresholding (better de-ringing effect, but likely blurrier).
18560 @item use_bframe_qp
18561 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
18562 option may cause flicker since the B-Frames have often larger QP. Default is
18563 @code{0} (not enabled).
18566 @subsection Commands
18568 This filter supports the following commands:
18570 @item quality, level
18571 Set quality level. The value @code{max} can be used to set the maximum level,
18572 currently @code{6}.
18578 Scale the input by applying one of the super-resolution methods based on
18579 convolutional neural networks. Supported models:
18583 Super-Resolution Convolutional Neural Network model (SRCNN).
18584 See @url{https://arxiv.org/abs/1501.00092}.
18587 Efficient Sub-Pixel Convolutional Neural Network model (ESPCN).
18588 See @url{https://arxiv.org/abs/1609.05158}.
18591 Training scripts as well as scripts for model file (.pb) saving can be found at
18592 @url{https://github.com/XueweiMeng/sr/tree/sr_dnn_native}. Original repository
18593 is at @url{https://github.com/HighVoltageRocknRoll/sr.git}.
18595 Native model files (.model) can be generated from TensorFlow model
18596 files (.pb) by using tools/python/convert.py
18598 The filter accepts the following options:
18602 Specify which DNN backend to use for model loading and execution. This option accepts
18603 the following values:
18607 Native implementation of DNN loading and execution.
18610 TensorFlow backend. To enable this backend you
18611 need to install the TensorFlow for C library (see
18612 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
18613 @code{--enable-libtensorflow}
18616 Default value is @samp{native}.
18619 Set path to model file specifying network architecture and its parameters.
18620 Note that different backends use different file formats. TensorFlow backend
18621 can load files for both formats, while native backend can load files for only
18625 Set scale factor for SRCNN model. Allowed values are @code{2}, @code{3} and @code{4}.
18626 Default value is @code{2}. Scale factor is necessary for SRCNN model, because it accepts
18627 input upscaled using bicubic upscaling with proper scale factor.
18630 This feature can also be finished with @ref{dnn_processing} filter.
18634 Obtain the SSIM (Structural SImilarity Metric) between two input videos.
18636 This filter takes in input two input videos, the first input is
18637 considered the "main" source and is passed unchanged to the
18638 output. The second input is used as a "reference" video for computing
18641 Both video inputs must have the same resolution and pixel format for
18642 this filter to work correctly. Also it assumes that both inputs
18643 have the same number of frames, which are compared one by one.
18645 The filter stores the calculated SSIM of each frame.
18647 The description of the accepted parameters follows.
18650 @item stats_file, f
18651 If specified the filter will use the named file to save the SSIM of
18652 each individual frame. When filename equals "-" the data is sent to
18656 The file printed if @var{stats_file} is selected, contains a sequence of
18657 key/value pairs of the form @var{key}:@var{value} for each compared
18660 A description of each shown parameter follows:
18664 sequential number of the input frame, starting from 1
18666 @item Y, U, V, R, G, B
18667 SSIM of the compared frames for the component specified by the suffix.
18670 SSIM of the compared frames for the whole frame.
18673 Same as above but in dB representation.
18676 This filter also supports the @ref{framesync} options.
18678 @subsection Examples
18683 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
18684 [main][ref] ssim="stats_file=stats.log" [out]
18687 On this example the input file being processed is compared with the
18688 reference file @file{ref_movie.mpg}. The SSIM of each individual frame
18689 is stored in @file{stats.log}.
18692 Another example with both psnr and ssim at same time:
18694 ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
18698 Another example with different containers:
18700 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 -
18706 Convert between different stereoscopic image formats.
18708 The filters accept the following options:
18712 Set stereoscopic image format of input.
18714 Available values for input image formats are:
18717 side by side parallel (left eye left, right eye right)
18720 side by side crosseye (right eye left, left eye right)
18723 side by side parallel with half width resolution
18724 (left eye left, right eye right)
18727 side by side crosseye with half width resolution
18728 (right eye left, left eye right)
18732 above-below (left eye above, right eye below)
18736 above-below (right eye above, left eye below)
18740 above-below with half height resolution
18741 (left eye above, right eye below)
18745 above-below with half height resolution
18746 (right eye above, left eye below)
18749 alternating frames (left eye first, right eye second)
18752 alternating frames (right eye first, left eye second)
18755 interleaved rows (left eye has top row, right eye starts on next row)
18758 interleaved rows (right eye has top row, left eye starts on next row)
18761 interleaved columns, left eye first
18764 interleaved columns, right eye first
18766 Default value is @samp{sbsl}.
18770 Set stereoscopic image format of output.
18774 side by side parallel (left eye left, right eye right)
18777 side by side crosseye (right eye left, left eye right)
18780 side by side parallel with half width resolution
18781 (left eye left, right eye right)
18784 side by side crosseye with half width resolution
18785 (right eye left, left eye right)
18789 above-below (left eye above, right eye below)
18793 above-below (right eye above, left eye below)
18797 above-below with half height resolution
18798 (left eye above, right eye below)
18802 above-below with half height resolution
18803 (right eye above, left eye below)
18806 alternating frames (left eye first, right eye second)
18809 alternating frames (right eye first, left eye second)
18812 interleaved rows (left eye has top row, right eye starts on next row)
18815 interleaved rows (right eye has top row, left eye starts on next row)
18818 anaglyph red/blue gray
18819 (red filter on left eye, blue filter on right eye)
18822 anaglyph red/green gray
18823 (red filter on left eye, green filter on right eye)
18826 anaglyph red/cyan gray
18827 (red filter on left eye, cyan filter on right eye)
18830 anaglyph red/cyan half colored
18831 (red filter on left eye, cyan filter on right eye)
18834 anaglyph red/cyan color
18835 (red filter on left eye, cyan filter on right eye)
18838 anaglyph red/cyan color optimized with the least squares projection of dubois
18839 (red filter on left eye, cyan filter on right eye)
18842 anaglyph green/magenta gray
18843 (green filter on left eye, magenta filter on right eye)
18846 anaglyph green/magenta half colored
18847 (green filter on left eye, magenta filter on right eye)
18850 anaglyph green/magenta colored
18851 (green filter on left eye, magenta filter on right eye)
18854 anaglyph green/magenta color optimized with the least squares projection of dubois
18855 (green filter on left eye, magenta filter on right eye)
18858 anaglyph yellow/blue gray
18859 (yellow filter on left eye, blue filter on right eye)
18862 anaglyph yellow/blue half colored
18863 (yellow filter on left eye, blue filter on right eye)
18866 anaglyph yellow/blue colored
18867 (yellow filter on left eye, blue filter on right eye)
18870 anaglyph yellow/blue color optimized with the least squares projection of dubois
18871 (yellow filter on left eye, blue filter on right eye)
18874 mono output (left eye only)
18877 mono output (right eye only)
18880 checkerboard, left eye first
18883 checkerboard, right eye first
18886 interleaved columns, left eye first
18889 interleaved columns, right eye first
18895 Default value is @samp{arcd}.
18898 @subsection Examples
18902 Convert input video from side by side parallel to anaglyph yellow/blue dubois:
18908 Convert input video from above below (left eye above, right eye below) to side by side crosseye.
18914 @section streamselect, astreamselect
18915 Select video or audio streams.
18917 The filter accepts the following options:
18921 Set number of inputs. Default is 2.
18924 Set input indexes to remap to outputs.
18927 @subsection Commands
18929 The @code{streamselect} and @code{astreamselect} filter supports the following
18934 Set input indexes to remap to outputs.
18937 @subsection Examples
18941 Select first 5 seconds 1st stream and rest of time 2nd stream:
18943 sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
18947 Same as above, but for audio:
18949 asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
18956 Draw subtitles on top of input video using the libass library.
18958 To enable compilation of this filter you need to configure FFmpeg with
18959 @code{--enable-libass}. This filter also requires a build with libavcodec and
18960 libavformat to convert the passed subtitles file to ASS (Advanced Substation
18961 Alpha) subtitles format.
18963 The filter accepts the following options:
18967 Set the filename of the subtitle file to read. It must be specified.
18969 @item original_size
18970 Specify the size of the original video, the video for which the ASS file
18971 was composed. For the syntax of this option, check the
18972 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18973 Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
18974 correctly scale the fonts if the aspect ratio has been changed.
18977 Set a directory path containing fonts that can be used by the filter.
18978 These fonts will be used in addition to whatever the font provider uses.
18981 Process alpha channel, by default alpha channel is untouched.
18984 Set subtitles input character encoding. @code{subtitles} filter only. Only
18985 useful if not UTF-8.
18987 @item stream_index, si
18988 Set subtitles stream index. @code{subtitles} filter only.
18991 Override default style or script info parameters of the subtitles. It accepts a
18992 string containing ASS style format @code{KEY=VALUE} couples separated by ",".
18995 If the first key is not specified, it is assumed that the first value
18996 specifies the @option{filename}.
18998 For example, to render the file @file{sub.srt} on top of the input
18999 video, use the command:
19004 which is equivalent to:
19006 subtitles=filename=sub.srt
19009 To render the default subtitles stream from file @file{video.mkv}, use:
19011 subtitles=video.mkv
19014 To render the second subtitles stream from that file, use:
19016 subtitles=video.mkv:si=1
19019 To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue
19020 @code{DejaVu Serif}, use:
19022 subtitles=sub.srt:force_style='Fontname=DejaVu Serif,PrimaryColour=&HCCFF0000'
19025 @section super2xsai
19027 Scale the input by 2x and smooth using the Super2xSaI (Scale and
19028 Interpolate) pixel art scaling algorithm.
19030 Useful for enlarging pixel art images without reducing sharpness.
19034 Swap two rectangular objects in video.
19036 This filter accepts the following options:
19046 Set 1st rect x coordinate.
19049 Set 1st rect y coordinate.
19052 Set 2nd rect x coordinate.
19055 Set 2nd rect y coordinate.
19057 All expressions are evaluated once for each frame.
19060 The all options are expressions containing the following constants:
19065 The input width and height.
19068 same as @var{w} / @var{h}
19071 input sample aspect ratio
19074 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
19077 The number of the input frame, starting from 0.
19080 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
19083 the position in the file of the input frame, NAN if unknown
19090 Blend successive video frames.
19096 Apply telecine process to the video.
19098 This filter accepts the following options:
19107 The default value is @code{top}.
19111 A string of numbers representing the pulldown pattern you wish to apply.
19112 The default value is @code{23}.
19116 Some typical patterns:
19121 24p: 2332 (preferred)
19128 24p: 222222222223 ("Euro pulldown")
19133 @section thistogram
19135 Compute and draw a color distribution histogram for the input video across time.
19137 Unlike @ref{histogram} video filter which only shows histogram of single input frame
19138 at certain time, this filter shows also past histograms of number of frames defined
19139 by @code{width} option.
19141 The computed histogram is a representation of the color component
19142 distribution in an image.
19144 The filter accepts the following options:
19148 Set width of single color component output. Default value is @code{0}.
19149 Value of @code{0} means width will be picked from input video.
19150 This also set number of passed histograms to keep.
19151 Allowed range is [0, 8192].
19153 @item display_mode, d
19155 It accepts the following values:
19158 Per color component graphs are placed below each other.
19161 Per color component graphs are placed side by side.
19164 Presents information identical to that in the @code{parade}, except
19165 that the graphs representing color components are superimposed directly
19168 Default is @code{stack}.
19170 @item levels_mode, m
19171 Set mode. Can be either @code{linear}, or @code{logarithmic}.
19172 Default is @code{linear}.
19174 @item components, c
19175 Set what color components to display.
19176 Default is @code{7}.
19179 Set background opacity. Default is @code{0.9}.
19182 Show envelope. Default is disabled.
19185 Set envelope color. Default is @code{gold}.
19190 Available values for slide is:
19193 Draw new frame when right border is reached.
19196 Replace old columns with new ones.
19199 Scroll from right to left.
19202 Scroll from left to right.
19205 Draw single picture.
19208 Default is @code{replace}.
19213 Apply threshold effect to video stream.
19215 This filter needs four video streams to perform thresholding.
19216 First stream is stream we are filtering.
19217 Second stream is holding threshold values, third stream is holding min values,
19218 and last, fourth stream is holding max values.
19220 The filter accepts the following option:
19224 Set which planes will be processed, unprocessed planes will be copied.
19225 By default value 0xf, all planes will be processed.
19228 For example if first stream pixel's component value is less then threshold value
19229 of pixel component from 2nd threshold stream, third stream value will picked,
19230 otherwise fourth stream pixel component value will be picked.
19232 Using color source filter one can perform various types of thresholding:
19234 @subsection Examples
19238 Binary threshold, using gray color as threshold:
19240 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
19244 Inverted binary threshold, using gray color as threshold:
19246 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
19250 Truncate binary threshold, using gray color as threshold:
19252 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
19256 Threshold to zero, using gray color as threshold:
19258 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
19262 Inverted threshold to zero, using gray color as threshold:
19264 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
19269 Select the most representative frame in a given sequence of consecutive frames.
19271 The filter accepts the following options:
19275 Set the frames batch size to analyze; in a set of @var{n} frames, the filter
19276 will pick one of them, and then handle the next batch of @var{n} frames until
19277 the end. Default is @code{100}.
19280 Since the filter keeps track of the whole frames sequence, a bigger @var{n}
19281 value will result in a higher memory usage, so a high value is not recommended.
19283 @subsection Examples
19287 Extract one picture each 50 frames:
19293 Complete example of a thumbnail creation with @command{ffmpeg}:
19295 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
19302 Tile several successive frames together.
19304 The @ref{untile} filter can do the reverse.
19306 The filter accepts the following options:
19311 Set the grid size (i.e. the number of lines and columns). For the syntax of
19312 this option, check the
19313 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19316 Set the maximum number of frames to render in the given area. It must be less
19317 than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
19318 the area will be used.
19321 Set the outer border margin in pixels.
19324 Set the inner border thickness (i.e. the number of pixels between frames). For
19325 more advanced padding options (such as having different values for the edges),
19326 refer to the pad video filter.
19329 Specify the color of the unused area. For the syntax of this option, check the
19330 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
19331 The default value of @var{color} is "black".
19334 Set the number of frames to overlap when tiling several successive frames together.
19335 The value must be between @code{0} and @var{nb_frames - 1}.
19338 Set the number of frames to initially be empty before displaying first output frame.
19339 This controls how soon will one get first output frame.
19340 The value must be between @code{0} and @var{nb_frames - 1}.
19343 @subsection Examples
19347 Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
19349 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
19351 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
19352 duplicating each output frame to accommodate the originally detected frame
19356 Display @code{5} pictures in an area of @code{3x2} frames,
19357 with @code{7} pixels between them, and @code{2} pixels of initial margin, using
19358 mixed flat and named options:
19360 tile=3x2:nb_frames=5:padding=7:margin=2
19364 @section tinterlace
19366 Perform various types of temporal field interlacing.
19368 Frames are counted starting from 1, so the first input frame is
19371 The filter accepts the following options:
19376 Specify the mode of the interlacing. This option can also be specified
19377 as a value alone. See below for a list of values for this option.
19379 Available values are:
19383 Move odd frames into the upper field, even into the lower field,
19384 generating a double height frame at half frame rate.
19388 Frame 1 Frame 2 Frame 3 Frame 4
19390 11111 22222 33333 44444
19391 11111 22222 33333 44444
19392 11111 22222 33333 44444
19393 11111 22222 33333 44444
19407 Only output odd frames, even frames are dropped, generating a frame with
19408 unchanged height at half frame rate.
19413 Frame 1 Frame 2 Frame 3 Frame 4
19415 11111 22222 33333 44444
19416 11111 22222 33333 44444
19417 11111 22222 33333 44444
19418 11111 22222 33333 44444
19428 Only output even frames, odd frames are dropped, generating a frame with
19429 unchanged height at half frame rate.
19434 Frame 1 Frame 2 Frame 3 Frame 4
19436 11111 22222 33333 44444
19437 11111 22222 33333 44444
19438 11111 22222 33333 44444
19439 11111 22222 33333 44444
19449 Expand each frame to full height, but pad alternate lines with black,
19450 generating a frame with double height at the same input frame rate.
19455 Frame 1 Frame 2 Frame 3 Frame 4
19457 11111 22222 33333 44444
19458 11111 22222 33333 44444
19459 11111 22222 33333 44444
19460 11111 22222 33333 44444
19463 11111 ..... 33333 .....
19464 ..... 22222 ..... 44444
19465 11111 ..... 33333 .....
19466 ..... 22222 ..... 44444
19467 11111 ..... 33333 .....
19468 ..... 22222 ..... 44444
19469 11111 ..... 33333 .....
19470 ..... 22222 ..... 44444
19474 @item interleave_top, 4
19475 Interleave the upper field from odd frames with the lower field from
19476 even frames, generating a frame with unchanged height at half frame rate.
19481 Frame 1 Frame 2 Frame 3 Frame 4
19483 11111<- 22222 33333<- 44444
19484 11111 22222<- 33333 44444<-
19485 11111<- 22222 33333<- 44444
19486 11111 22222<- 33333 44444<-
19496 @item interleave_bottom, 5
19497 Interleave the lower field from odd frames with the upper field from
19498 even frames, generating a frame with unchanged height at half frame rate.
19503 Frame 1 Frame 2 Frame 3 Frame 4
19505 11111 22222<- 33333 44444<-
19506 11111<- 22222 33333<- 44444
19507 11111 22222<- 33333 44444<-
19508 11111<- 22222 33333<- 44444
19518 @item interlacex2, 6
19519 Double frame rate with unchanged height. Frames are inserted each
19520 containing the second temporal field from the previous input frame and
19521 the first temporal field from the next input frame. This mode relies on
19522 the top_field_first flag. Useful for interlaced video displays with no
19523 field synchronisation.
19528 Frame 1 Frame 2 Frame 3 Frame 4
19530 11111 22222 33333 44444
19531 11111 22222 33333 44444
19532 11111 22222 33333 44444
19533 11111 22222 33333 44444
19536 11111 22222 22222 33333 33333 44444 44444
19537 11111 11111 22222 22222 33333 33333 44444
19538 11111 22222 22222 33333 33333 44444 44444
19539 11111 11111 22222 22222 33333 33333 44444
19544 Move odd frames into the upper field, even into the lower field,
19545 generating a double height frame at same frame rate.
19550 Frame 1 Frame 2 Frame 3 Frame 4
19552 11111 22222 33333 44444
19553 11111 22222 33333 44444
19554 11111 22222 33333 44444
19555 11111 22222 33333 44444
19558 11111 33333 33333 55555
19559 22222 22222 44444 44444
19560 11111 33333 33333 55555
19561 22222 22222 44444 44444
19562 11111 33333 33333 55555
19563 22222 22222 44444 44444
19564 11111 33333 33333 55555
19565 22222 22222 44444 44444
19570 Numeric values are deprecated but are accepted for backward
19571 compatibility reasons.
19573 Default mode is @code{merge}.
19576 Specify flags influencing the filter process.
19578 Available value for @var{flags} is:
19581 @item low_pass_filter, vlpf
19582 Enable linear vertical low-pass filtering in the filter.
19583 Vertical low-pass filtering is required when creating an interlaced
19584 destination from a progressive source which contains high-frequency
19585 vertical detail. Filtering will reduce interlace 'twitter' and Moire
19588 @item complex_filter, cvlpf
19589 Enable complex vertical low-pass filtering.
19590 This will slightly less reduce interlace 'twitter' and Moire
19591 patterning but better retain detail and subjective sharpness impression.
19594 Bypass already interlaced frames, only adjust the frame rate.
19597 Vertical low-pass filtering and bypassing already interlaced frames can only be
19598 enabled for @option{mode} @var{interleave_top} and @var{interleave_bottom}.
19603 Pick median pixels from several successive input video frames.
19605 The filter accepts the following options:
19609 Set radius of median filter.
19610 Default is 1. Allowed range is from 1 to 127.
19613 Set which planes to filter. Default value is @code{15}, by which all planes are processed.
19616 Set median percentile. Default value is @code{0.5}.
19617 Default value of @code{0.5} will pick always median values, while @code{0} will pick
19618 minimum values, and @code{1} maximum values.
19621 @subsection Commands
19623 This filter supports all above options as @ref{commands}, excluding option @code{radius}.
19625 @section tmidequalizer
19627 Apply Temporal Midway Video Equalization effect.
19629 Midway Video Equalization adjusts a sequence of video frames to have the same
19630 histograms, while maintaining their dynamics as much as possible. It's
19631 useful for e.g. matching exposures from a video frames sequence.
19633 This filter accepts the following option:
19637 Set filtering radius. Default is @code{5}. Allowed range is from 1 to 127.
19640 Set filtering sigma. Default is @code{0.5}. This controls strength of filtering.
19641 Setting this option to 0 effectively does nothing.
19644 Set which planes to process. Default is @code{15}, which is all available planes.
19649 Mix successive video frames.
19651 A description of the accepted options follows.
19655 The number of successive frames to mix. If unspecified, it defaults to 3.
19658 Specify weight of each input video frame.
19659 Each weight is separated by space. If number of weights is smaller than
19660 number of @var{frames} last specified weight will be used for all remaining
19664 Specify scale, if it is set it will be multiplied with sum
19665 of each weight multiplied with pixel values to give final destination
19666 pixel value. By default @var{scale} is auto scaled to sum of weights.
19669 @subsection Examples
19673 Average 7 successive frames:
19675 tmix=frames=7:weights="1 1 1 1 1 1 1"
19679 Apply simple temporal convolution:
19681 tmix=frames=3:weights="-1 3 -1"
19685 Similar as above but only showing temporal differences:
19687 tmix=frames=3:weights="-1 2 -1":scale=1
19693 Tone map colors from different dynamic ranges.
19695 This filter expects data in single precision floating point, as it needs to
19696 operate on (and can output) out-of-range values. Another filter, such as
19697 @ref{zscale}, is needed to convert the resulting frame to a usable format.
19699 The tonemapping algorithms implemented only work on linear light, so input
19700 data should be linearized beforehand (and possibly correctly tagged).
19703 ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
19706 @subsection Options
19707 The filter accepts the following options.
19711 Set the tone map algorithm to use.
19713 Possible values are:
19716 Do not apply any tone map, only desaturate overbright pixels.
19719 Hard-clip any out-of-range values. Use it for perfect color accuracy for
19720 in-range values, while distorting out-of-range values.
19723 Stretch the entire reference gamut to a linear multiple of the display.
19726 Fit a logarithmic transfer between the tone curves.
19729 Preserve overall image brightness with a simple curve, using nonlinear
19730 contrast, which results in flattening details and degrading color accuracy.
19733 Preserve both dark and bright details better than @var{reinhard}, at the cost
19734 of slightly darkening everything. Use it when detail preservation is more
19735 important than color and brightness accuracy.
19738 Smoothly map out-of-range values, while retaining contrast and colors for
19739 in-range material as much as possible. Use it when color accuracy is more
19740 important than detail preservation.
19746 Tune the tone mapping algorithm.
19748 This affects the following algorithms:
19754 Specifies the scale factor to use while stretching.
19758 Specifies the exponent of the function.
19762 Specify an extra linear coefficient to multiply into the signal before clipping.
19766 Specify the local contrast coefficient at the display peak.
19767 Default to 0.5, which means that in-gamut values will be about half as bright
19774 Specify the transition point from linear to mobius transform. Every value
19775 below this point is guaranteed to be mapped 1:1. The higher the value, the
19776 more accurate the result will be, at the cost of losing bright details.
19777 Default to 0.3, which due to the steep initial slope still preserves in-range
19778 colors fairly accurately.
19782 Apply desaturation for highlights that exceed this level of brightness. The
19783 higher the parameter, the more color information will be preserved. This
19784 setting helps prevent unnaturally blown-out colors for super-highlights, by
19785 (smoothly) turning into white instead. This makes images feel more natural,
19786 at the cost of reducing information about out-of-range colors.
19788 The default of 2.0 is somewhat conservative and will mostly just apply to
19789 skies or directly sunlit surfaces. A setting of 0.0 disables this option.
19791 This option works only if the input frame has a supported color tag.
19794 Override signal/nominal/reference peak with this value. Useful when the
19795 embedded peak information in display metadata is not reliable or when tone
19796 mapping from a lower range to a higher range.
19801 Temporarily pad video frames.
19803 The filter accepts the following options:
19807 Specify number of delay frames before input video stream. Default is 0.
19810 Specify number of padding frames after input video stream.
19811 Set to -1 to pad indefinitely. Default is 0.
19814 Set kind of frames added to beginning of stream.
19815 Can be either @var{add} or @var{clone}.
19816 With @var{add} frames of solid-color are added.
19817 With @var{clone} frames are clones of first frame.
19818 Default is @var{add}.
19821 Set kind of frames added to end of stream.
19822 Can be either @var{add} or @var{clone}.
19823 With @var{add} frames of solid-color are added.
19824 With @var{clone} frames are clones of last frame.
19825 Default is @var{add}.
19827 @item start_duration, stop_duration
19828 Specify the duration of the start/stop delay. See
19829 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
19830 for the accepted syntax.
19831 These options override @var{start} and @var{stop}. Default is 0.
19834 Specify the color of the padded area. For the syntax of this option,
19835 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
19836 manual,ffmpeg-utils}.
19838 The default value of @var{color} is "black".
19844 Transpose rows with columns in the input video and optionally flip it.
19846 It accepts the following parameters:
19851 Specify the transposition direction.
19853 Can assume the following values:
19855 @item 0, 4, cclock_flip
19856 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
19864 Rotate by 90 degrees clockwise, that is:
19872 Rotate by 90 degrees counterclockwise, that is:
19879 @item 3, 7, clock_flip
19880 Rotate by 90 degrees clockwise and vertically flip, that is:
19888 For values between 4-7, the transposition is only done if the input
19889 video geometry is portrait and not landscape. These values are
19890 deprecated, the @code{passthrough} option should be used instead.
19892 Numerical values are deprecated, and should be dropped in favor of
19893 symbolic constants.
19896 Do not apply the transposition if the input geometry matches the one
19897 specified by the specified value. It accepts the following values:
19900 Always apply transposition.
19902 Preserve portrait geometry (when @var{height} >= @var{width}).
19904 Preserve landscape geometry (when @var{width} >= @var{height}).
19907 Default value is @code{none}.
19910 For example to rotate by 90 degrees clockwise and preserve portrait
19913 transpose=dir=1:passthrough=portrait
19916 The command above can also be specified as:
19918 transpose=1:portrait
19921 @section transpose_npp
19923 Transpose rows with columns in the input video and optionally flip it.
19924 For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options.
19926 It accepts the following parameters:
19931 Specify the transposition direction.
19933 Can assume the following values:
19936 Rotate by 90 degrees counterclockwise and vertically flip. (default)
19939 Rotate by 90 degrees clockwise.
19942 Rotate by 90 degrees counterclockwise.
19945 Rotate by 90 degrees clockwise and vertically flip.
19949 Do not apply the transposition if the input geometry matches the one
19950 specified by the specified value. It accepts the following values:
19953 Always apply transposition. (default)
19955 Preserve portrait geometry (when @var{height} >= @var{width}).
19957 Preserve landscape geometry (when @var{width} >= @var{height}).
19963 Trim the input so that the output contains one continuous subpart of the input.
19965 It accepts the following parameters:
19968 Specify the time of the start of the kept section, i.e. the frame with the
19969 timestamp @var{start} will be the first frame in the output.
19972 Specify the time of the first frame that will be dropped, i.e. the frame
19973 immediately preceding the one with the timestamp @var{end} will be the last
19974 frame in the output.
19977 This is the same as @var{start}, except this option sets the start timestamp
19978 in timebase units instead of seconds.
19981 This is the same as @var{end}, except this option sets the end timestamp
19982 in timebase units instead of seconds.
19985 The maximum duration of the output in seconds.
19988 The number of the first frame that should be passed to the output.
19991 The number of the first frame that should be dropped.
19994 @option{start}, @option{end}, and @option{duration} are expressed as time
19995 duration specifications; see
19996 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
19997 for the accepted syntax.
19999 Note that the first two sets of the start/end options and the @option{duration}
20000 option look at the frame timestamp, while the _frame variants simply count the
20001 frames that pass through the filter. Also note that this filter does not modify
20002 the timestamps. If you wish for the output timestamps to start at zero, insert a
20003 setpts filter after the trim filter.
20005 If multiple start or end options are set, this filter tries to be greedy and
20006 keep all the frames that match at least one of the specified constraints. To keep
20007 only the part that matches all the constraints at once, chain multiple trim
20010 The defaults are such that all the input is kept. So it is possible to set e.g.
20011 just the end values to keep everything before the specified time.
20016 Drop everything except the second minute of input:
20018 ffmpeg -i INPUT -vf trim=60:120
20022 Keep only the first second:
20024 ffmpeg -i INPUT -vf trim=duration=1
20029 @section unpremultiply
20030 Apply alpha unpremultiply effect to input video stream using first plane
20031 of second stream as alpha.
20033 Both streams must have same dimensions and same pixel format.
20035 The filter accepts the following option:
20039 Set which planes will be processed, unprocessed planes will be copied.
20040 By default value 0xf, all planes will be processed.
20042 If the format has 1 or 2 components, then luma is bit 0.
20043 If the format has 3 or 4 components:
20044 for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red;
20045 for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V.
20046 If present, the alpha channel is always the last bit.
20049 Do not require 2nd input for processing, instead use alpha plane from input stream.
20055 Sharpen or blur the input video.
20057 It accepts the following parameters:
20060 @item luma_msize_x, lx
20061 Set the luma matrix horizontal size. It must be an odd integer between
20062 3 and 23. The default value is 5.
20064 @item luma_msize_y, ly
20065 Set the luma matrix vertical size. It must be an odd integer between 3
20066 and 23. The default value is 5.
20068 @item luma_amount, la
20069 Set the luma effect strength. It must be a floating point number, reasonable
20070 values lay between -1.5 and 1.5.
20072 Negative values will blur the input video, while positive values will
20073 sharpen it, a value of zero will disable the effect.
20075 Default value is 1.0.
20077 @item chroma_msize_x, cx
20078 Set the chroma matrix horizontal size. It must be an odd integer
20079 between 3 and 23. The default value is 5.
20081 @item chroma_msize_y, cy
20082 Set the chroma matrix vertical size. It must be an odd integer
20083 between 3 and 23. The default value is 5.
20085 @item chroma_amount, ca
20086 Set the chroma effect strength. It must be a floating point number, reasonable
20087 values lay between -1.5 and 1.5.
20089 Negative values will blur the input video, while positive values will
20090 sharpen it, a value of zero will disable the effect.
20092 Default value is 0.0.
20096 All parameters are optional and default to the equivalent of the
20097 string '5:5:1.0:5:5:0.0'.
20099 @subsection Examples
20103 Apply strong luma sharpen effect:
20105 unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
20109 Apply a strong blur of both luma and chroma parameters:
20111 unsharp=7:7:-2:7:7:-2
20118 Decompose a video made of tiled images into the individual images.
20120 The frame rate of the output video is the frame rate of the input video
20121 multiplied by the number of tiles.
20123 This filter does the reverse of @ref{tile}.
20125 The filter accepts the following options:
20130 Set the grid size (i.e. the number of lines and columns). For the syntax of
20131 this option, check the
20132 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20135 @subsection Examples
20139 Produce a 1-second video from a still image file made of 25 frames stacked
20140 vertically, like an analogic film reel:
20142 ffmpeg -r 1 -i image.jpg -vf untile=1x25 movie.mkv
20148 Apply ultra slow/simple postprocessing filter that compresses and decompresses
20149 the image at several (or - in the case of @option{quality} level @code{8} - all)
20150 shifts and average the results.
20152 The way this differs from the behavior of spp is that uspp actually encodes &
20153 decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
20154 DCT similar to MJPEG.
20156 The filter accepts the following options:
20160 Set quality. This option defines the number of levels for averaging. It accepts
20161 an integer in the range 0-8. If set to @code{0}, the filter will have no
20162 effect. A value of @code{8} means the higher quality. For each increment of
20163 that value the speed drops by a factor of approximately 2. Default value is
20167 Force a constant quantization parameter. If not set, the filter will use the QP
20168 from the video stream (if available).
20173 Convert 360 videos between various formats.
20175 The filter accepts the following options:
20181 Set format of the input/output video.
20189 Equirectangular projection.
20194 Cubemap with 3x2/6x1/1x6 layout.
20196 Format specific options:
20201 Set padding proportion for the input/output cubemap. Values in decimals.
20208 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)
20211 Default value is @b{@samp{0}}.
20212 Maximum value is @b{@samp{0.1}}.
20216 Set fixed padding for the input/output cubemap. Values in pixels.
20218 Default value is @b{@samp{0}}. If greater than zero it overrides other padding options.
20222 Set order of faces for the input/output cubemap. Choose one direction for each position.
20224 Designation of directions:
20240 Default value is @b{@samp{rludfb}}.
20244 Set rotation of faces for the input/output cubemap. Choose one angle for each position.
20246 Designation of angles:
20249 0 degrees clockwise
20251 90 degrees clockwise
20253 180 degrees clockwise
20255 270 degrees clockwise
20258 Default value is @b{@samp{000000}}.
20262 Equi-Angular Cubemap.
20269 Format specific options:
20274 Set output horizontal/vertical/diagonal field of view. Values in degrees.
20276 If diagonal field of view is set it overrides horizontal and vertical field of view.
20281 Set input horizontal/vertical/diagonal field of view. Values in degrees.
20283 If diagonal field of view is set it overrides horizontal and vertical field of view.
20289 Format specific options:
20294 Set output horizontal/vertical/diagonal field of view. Values in degrees.
20296 If diagonal field of view is set it overrides horizontal and vertical field of view.
20301 Set input horizontal/vertical/diagonal field of view. Values in degrees.
20303 If diagonal field of view is set it overrides horizontal and vertical field of view.
20309 Facebook's 360 formats.
20312 Stereographic format.
20314 Format specific options:
20319 Set output horizontal/vertical/diagonal field of view. Values in degrees.
20321 If diagonal field of view is set it overrides horizontal and vertical field of view.
20326 Set input horizontal/vertical/diagonal field of view. Values in degrees.
20328 If diagonal field of view is set it overrides horizontal and vertical field of view.
20335 Ball format, gives significant distortion toward the back.
20338 Hammer-Aitoff map projection format.
20341 Sinusoidal map projection format.
20344 Fisheye projection.
20346 Format specific options:
20351 Set output horizontal/vertical/diagonal field of view. Values in degrees.
20353 If diagonal field of view is set it overrides horizontal and vertical field of view.
20358 Set input horizontal/vertical/diagonal field of view. Values in degrees.
20360 If diagonal field of view is set it overrides horizontal and vertical field of view.
20364 Pannini projection.
20366 Format specific options:
20369 Set output pannini parameter.
20372 Set input pannini parameter.
20376 Cylindrical projection.
20378 Format specific options:
20383 Set output horizontal/vertical/diagonal field of view. Values in degrees.
20385 If diagonal field of view is set it overrides horizontal and vertical field of view.
20390 Set input horizontal/vertical/diagonal field of view. Values in degrees.
20392 If diagonal field of view is set it overrides horizontal and vertical field of view.
20396 Perspective projection. @i{(output only)}
20398 Format specific options:
20401 Set perspective parameter.
20405 Tetrahedron projection.
20408 Truncated square pyramid projection.
20412 Half equirectangular projection.
20417 Format specific options:
20422 Set output horizontal/vertical/diagonal field of view. Values in degrees.
20424 If diagonal field of view is set it overrides horizontal and vertical field of view.
20429 Set input horizontal/vertical/diagonal field of view. Values in degrees.
20431 If diagonal field of view is set it overrides horizontal and vertical field of view.
20435 Orthographic format.
20437 Format specific options:
20442 Set output horizontal/vertical/diagonal field of view. Values in degrees.
20444 If diagonal field of view is set it overrides horizontal and vertical field of view.
20449 Set input horizontal/vertical/diagonal field of view. Values in degrees.
20451 If diagonal field of view is set it overrides horizontal and vertical field of view.
20455 Octahedron projection.
20459 Set interpolation method.@*
20460 @i{Note: more complex interpolation methods require much more memory to run.}
20470 Bilinear interpolation.
20472 Lagrange9 interpolation.
20475 Bicubic interpolation.
20478 Lanczos interpolation.
20481 Spline16 interpolation.
20484 Gaussian interpolation.
20486 Mitchell interpolation.
20489 Default value is @b{@samp{line}}.
20493 Set the output video resolution.
20495 Default resolution depends on formats.
20499 Set the input/output stereo format.
20510 Default value is @b{@samp{2d}} for input and output format.
20515 Set rotation for the output video. Values in degrees.
20518 Set rotation order for the output video. Choose one item for each position.
20529 Default value is @b{@samp{ypr}}.
20534 Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values.
20538 Set if input video is flipped horizontally/vertically. Boolean values.
20541 Set if input video is transposed. Boolean value, by default disabled.
20544 Set if output video needs to be transposed. Boolean value, by default disabled.
20547 Build mask in alpha plane for all unmapped pixels by marking them fully transparent. Boolean value, by default disabled.
20550 @subsection Examples
20554 Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation:
20556 ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv
20559 Extract back view of Equi-Angular Cubemap:
20561 ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv
20564 Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format:
20566 v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb
20570 @subsection Commands
20572 This filter supports subset of above options as @ref{commands}.
20574 @section vaguedenoiser
20576 Apply a wavelet based denoiser.
20578 It transforms each frame from the video input into the wavelet domain,
20579 using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
20580 the obtained coefficients. It does an inverse wavelet transform after.
20581 Due to wavelet properties, it should give a nice smoothed result, and
20582 reduced noise, without blurring picture features.
20584 This filter accepts the following options:
20588 The filtering strength. The higher, the more filtered the video will be.
20589 Hard thresholding can use a higher threshold than soft thresholding
20590 before the video looks overfiltered. Default value is 2.
20593 The filtering method the filter will use.
20595 It accepts the following values:
20598 All values under the threshold will be zeroed.
20601 All values under the threshold will be zeroed. All values above will be
20602 reduced by the threshold.
20605 Scales or nullifies coefficients - intermediary between (more) soft and
20606 (less) hard thresholding.
20609 Default is garrote.
20612 Number of times, the wavelet will decompose the picture. Picture can't
20613 be decomposed beyond a particular point (typically, 8 for a 640x480
20614 frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6.
20617 Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85.
20620 A list of the planes to process. By default all planes are processed.
20623 The threshold type the filter will use.
20625 It accepts the following values:
20628 Threshold used is same for all decompositions.
20631 Threshold used depends also on each decomposition coefficients.
20634 Default is universal.
20637 @section vectorscope
20639 Display 2 color component values in the two dimensional graph (which is called
20642 This filter accepts the following options:
20646 Set vectorscope mode.
20648 It accepts the following values:
20652 Gray values are displayed on graph, higher brightness means more pixels have
20653 same component color value on location in graph. This is the default mode.
20656 Gray values are displayed on graph. Surrounding pixels values which are not
20657 present in video frame are drawn in gradient of 2 color components which are
20658 set by option @code{x} and @code{y}. The 3rd color component is static.
20661 Actual color components values present in video frame are displayed on graph.
20664 Similar as color2 but higher frequency of same values @code{x} and @code{y}
20665 on graph increases value of another color component, which is luminance by
20666 default values of @code{x} and @code{y}.
20669 Actual colors present in video frame are displayed on graph. If two different
20670 colors map to same position on graph then color with higher value of component
20671 not present in graph is picked.
20674 Gray values are displayed on graph. Similar to @code{color} but with 3rd color
20675 component picked from radial gradient.
20679 Set which color component will be represented on X-axis. Default is @code{1}.
20682 Set which color component will be represented on Y-axis. Default is @code{2}.
20685 Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
20686 of color component which represents frequency of (X, Y) location in graph.
20691 No envelope, this is default.
20694 Instant envelope, even darkest single pixel will be clearly highlighted.
20697 Hold maximum and minimum values presented in graph over time. This way you
20698 can still spot out of range values without constantly looking at vectorscope.
20701 Peak and instant envelope combined together.
20705 Set what kind of graticule to draw.
20714 Set graticule opacity.
20717 Set graticule flags.
20721 Draw graticule for white point.
20724 Draw graticule for black point.
20727 Draw color points short names.
20731 Set background opacity.
20733 @item lthreshold, l
20734 Set low threshold for color component not represented on X or Y axis.
20735 Values lower than this value will be ignored. Default is 0.
20736 Note this value is multiplied with actual max possible value one pixel component
20737 can have. So for 8-bit input and low threshold value of 0.1 actual threshold
20740 @item hthreshold, h
20741 Set high threshold for color component not represented on X or Y axis.
20742 Values higher than this value will be ignored. Default is 1.
20743 Note this value is multiplied with actual max possible value one pixel component
20744 can have. So for 8-bit input and high threshold value of 0.9 actual threshold
20745 is 0.9 * 255 = 230.
20747 @item colorspace, c
20748 Set what kind of colorspace to use when drawing graticule.
20758 Set color tint for gray/tint vectorscope mode. By default both options are zero.
20759 This means no tint, and output will remain gray.
20762 @anchor{vidstabdetect}
20763 @section vidstabdetect
20765 Analyze video stabilization/deshaking. Perform pass 1 of 2, see
20766 @ref{vidstabtransform} for pass 2.
20768 This filter generates a file with relative translation and rotation
20769 transform information about subsequent frames, which is then used by
20770 the @ref{vidstabtransform} filter.
20772 To enable compilation of this filter you need to configure FFmpeg with
20773 @code{--enable-libvidstab}.
20775 This filter accepts the following options:
20779 Set the path to the file used to write the transforms information.
20780 Default value is @file{transforms.trf}.
20783 Set how shaky the video is and how quick the camera is. It accepts an
20784 integer in the range 1-10, a value of 1 means little shakiness, a
20785 value of 10 means strong shakiness. Default value is 5.
20788 Set the accuracy of the detection process. It must be a value in the
20789 range 1-15. A value of 1 means low accuracy, a value of 15 means high
20790 accuracy. Default value is 15.
20793 Set stepsize of the search process. The region around minimum is
20794 scanned with 1 pixel resolution. Default value is 6.
20797 Set minimum contrast. Below this value a local measurement field is
20798 discarded. Must be a floating point value in the range 0-1. Default
20802 Set reference frame number for tripod mode.
20804 If enabled, the motion of the frames is compared to a reference frame
20805 in the filtered stream, identified by the specified number. The idea
20806 is to compensate all movements in a more-or-less static scene and keep
20807 the camera view absolutely still.
20809 If set to 0, it is disabled. The frames are counted starting from 1.
20812 Show fields and transforms in the resulting frames. It accepts an
20813 integer in the range 0-2. Default value is 0, which disables any
20817 @subsection Examples
20821 Use default values:
20827 Analyze strongly shaky movie and put the results in file
20828 @file{mytransforms.trf}:
20830 vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
20834 Visualize the result of internal transformations in the resulting
20837 vidstabdetect=show=1
20841 Analyze a video with medium shakiness using @command{ffmpeg}:
20843 ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
20847 @anchor{vidstabtransform}
20848 @section vidstabtransform
20850 Video stabilization/deshaking: pass 2 of 2,
20851 see @ref{vidstabdetect} for pass 1.
20853 Read a file with transform information for each frame and
20854 apply/compensate them. Together with the @ref{vidstabdetect}
20855 filter this can be used to deshake videos. See also
20856 @url{http://public.hronopik.de/vid.stab}. It is important to also use
20857 the @ref{unsharp} filter, see below.
20859 To enable compilation of this filter you need to configure FFmpeg with
20860 @code{--enable-libvidstab}.
20862 @subsection Options
20866 Set path to the file used to read the transforms. Default value is
20867 @file{transforms.trf}.
20870 Set the number of frames (value*2 + 1) used for lowpass filtering the
20871 camera movements. Default value is 10.
20873 For example a number of 10 means that 21 frames are used (10 in the
20874 past and 10 in the future) to smoothen the motion in the video. A
20875 larger value leads to a smoother video, but limits the acceleration of
20876 the camera (pan/tilt movements). 0 is a special case where a static
20877 camera is simulated.
20880 Set the camera path optimization algorithm.
20882 Accepted values are:
20885 gaussian kernel low-pass filter on camera motion (default)
20887 averaging on transformations
20891 Set maximal number of pixels to translate frames. Default value is -1,
20895 Set maximal angle in radians (degree*PI/180) to rotate frames. Default
20896 value is -1, meaning no limit.
20899 Specify how to deal with borders that may be visible due to movement
20902 Available values are:
20905 keep image information from previous frame (default)
20907 fill the border black
20911 Invert transforms if set to 1. Default value is 0.
20914 Consider transforms as relative to previous frame if set to 1,
20915 absolute if set to 0. Default value is 0.
20918 Set percentage to zoom. A positive value will result in a zoom-in
20919 effect, a negative value in a zoom-out effect. Default value is 0 (no
20923 Set optimal zooming to avoid borders.
20925 Accepted values are:
20930 optimal static zoom value is determined (only very strong movements
20931 will lead to visible borders) (default)
20933 optimal adaptive zoom value is determined (no borders will be
20934 visible), see @option{zoomspeed}
20937 Note that the value given at zoom is added to the one calculated here.
20940 Set percent to zoom maximally each frame (enabled when
20941 @option{optzoom} is set to 2). Range is from 0 to 5, default value is
20945 Specify type of interpolation.
20947 Available values are:
20952 linear only horizontal
20954 linear in both directions (default)
20956 cubic in both directions (slow)
20960 Enable virtual tripod mode if set to 1, which is equivalent to
20961 @code{relative=0:smoothing=0}. Default value is 0.
20963 Use also @code{tripod} option of @ref{vidstabdetect}.
20966 Increase log verbosity if set to 1. Also the detected global motions
20967 are written to the temporary file @file{global_motions.trf}. Default
20971 @subsection Examples
20975 Use @command{ffmpeg} for a typical stabilization with default values:
20977 ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
20980 Note the use of the @ref{unsharp} filter which is always recommended.
20983 Zoom in a bit more and load transform data from a given file:
20985 vidstabtransform=zoom=5:input="mytransforms.trf"
20989 Smoothen the video even more:
20991 vidstabtransform=smoothing=30
20997 Flip the input video vertically.
20999 For example, to vertically flip a video with @command{ffmpeg}:
21001 ffmpeg -i in.avi -vf "vflip" out.avi
21006 Detect variable frame rate video.
21008 This filter tries to detect if the input is variable or constant frame rate.
21010 At end it will output number of frames detected as having variable delta pts,
21011 and ones with constant delta pts.
21012 If there was frames with variable delta, than it will also show min, max and
21013 average delta encountered.
21017 Boost or alter saturation.
21019 The filter accepts the following options:
21022 Set strength of boost if positive value or strength of alter if negative value.
21023 Default is 0. Allowed range is from -2 to 2.
21026 Set the red balance. Default is 1. Allowed range is from -10 to 10.
21029 Set the green balance. Default is 1. Allowed range is from -10 to 10.
21032 Set the blue balance. Default is 1. Allowed range is from -10 to 10.
21035 Set the red luma coefficient.
21038 Set the green luma coefficient.
21041 Set the blue luma coefficient.
21044 If @code{intensity} is negative and this is set to 1, colors will change,
21045 otherwise colors will be less saturated, more towards gray.
21048 @subsection Commands
21050 This filter supports the all above options as @ref{commands}.
21055 Make or reverse a natural vignetting effect.
21057 The filter accepts the following options:
21061 Set lens angle expression as a number of radians.
21063 The value is clipped in the @code{[0,PI/2]} range.
21065 Default value: @code{"PI/5"}
21069 Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
21073 Set forward/backward mode.
21075 Available modes are:
21078 The larger the distance from the central point, the darker the image becomes.
21081 The larger the distance from the central point, the brighter the image becomes.
21082 This can be used to reverse a vignette effect, though there is no automatic
21083 detection to extract the lens @option{angle} and other settings (yet). It can
21084 also be used to create a burning effect.
21087 Default value is @samp{forward}.
21090 Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
21092 It accepts the following values:
21095 Evaluate expressions only once during the filter initialization.
21098 Evaluate expressions for each incoming frame. This is way slower than the
21099 @samp{init} mode since it requires all the scalers to be re-computed, but it
21100 allows advanced dynamic expressions.
21103 Default value is @samp{init}.
21106 Set dithering to reduce the circular banding effects. Default is @code{1}
21110 Set vignette aspect. This setting allows one to adjust the shape of the vignette.
21111 Setting this value to the SAR of the input will make a rectangular vignetting
21112 following the dimensions of the video.
21114 Default is @code{1/1}.
21117 @subsection Expressions
21119 The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
21120 following parameters.
21125 input width and height
21128 the number of input frame, starting from 0
21131 the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
21132 @var{TB} units, NAN if undefined
21135 frame rate of the input video, NAN if the input frame rate is unknown
21138 the PTS (Presentation TimeStamp) of the filtered video frame,
21139 expressed in seconds, NAN if undefined
21142 time base of the input video
21146 @subsection Examples
21150 Apply simple strong vignetting effect:
21156 Make a flickering vignetting:
21158 vignette='PI/4+random(1)*PI/50':eval=frame
21163 @section vmafmotion
21165 Obtain the average VMAF motion score of a video.
21166 It is one of the component metrics of VMAF.
21168 The obtained average motion score is printed through the logging system.
21170 The filter accepts the following options:
21174 If specified, the filter will use the named file to save the motion score of
21175 each frame with respect to the previous frame.
21176 When filename equals "-" the data is sent to standard output.
21181 ffmpeg -i ref.mpg -vf vmafmotion -f null -
21185 Stack input videos vertically.
21187 All streams must be of same pixel format and of same width.
21189 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
21190 to create same output.
21192 The filter accepts the following options:
21196 Set number of input streams. Default is 2.
21199 If set to 1, force the output to terminate when the shortest input
21200 terminates. Default value is 0.
21205 Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
21206 Deinterlacing Filter").
21208 Based on the process described by Martin Weston for BBC R&D, and
21209 implemented based on the de-interlace algorithm written by Jim
21210 Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
21211 uses filter coefficients calculated by BBC R&D.
21213 This filter uses field-dominance information in frame to decide which
21214 of each pair of fields to place first in the output.
21215 If it gets it wrong use @ref{setfield} filter before @code{w3fdif} filter.
21217 There are two sets of filter coefficients, so called "simple"
21218 and "complex". Which set of filter coefficients is used can
21219 be set by passing an optional parameter:
21223 Set the interlacing filter coefficients. Accepts one of the following values:
21227 Simple filter coefficient set.
21229 More-complex filter coefficient set.
21231 Default value is @samp{complex}.
21234 The interlacing mode to adopt. It accepts one of the following values:
21238 Output one frame for each frame.
21240 Output one frame for each field.
21243 The default value is @code{field}.
21246 The picture field parity assumed for the input interlaced video. It accepts one
21247 of the following values:
21251 Assume the top field is first.
21253 Assume the bottom field is first.
21255 Enable automatic detection of field parity.
21258 The default value is @code{auto}.
21259 If the interlacing is unknown or the decoder does not export this information,
21260 top field first will be assumed.
21263 Specify which frames to deinterlace. Accepts one of the following values:
21267 Deinterlace all frames,
21269 Only deinterlace frames marked as interlaced.
21272 Default value is @samp{all}.
21275 @subsection Commands
21276 This filter supports same @ref{commands} as options.
21279 Video waveform monitor.
21281 The waveform monitor plots color component intensity. By default luminance
21282 only. Each column of the waveform corresponds to a column of pixels in the
21285 It accepts the following options:
21289 Can be either @code{row}, or @code{column}. Default is @code{column}.
21290 In row mode, the graph on the left side represents color component value 0 and
21291 the right side represents value = 255. In column mode, the top side represents
21292 color component value = 0 and bottom side represents value = 255.
21295 Set intensity. Smaller values are useful to find out how many values of the same
21296 luminance are distributed across input rows/columns.
21297 Default value is @code{0.04}. Allowed range is [0, 1].
21300 Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
21301 In mirrored mode, higher values will be represented on the left
21302 side for @code{row} mode and at the top for @code{column} mode. Default is
21303 @code{1} (mirrored).
21307 It accepts the following values:
21310 Presents information identical to that in the @code{parade}, except
21311 that the graphs representing color components are superimposed directly
21314 This display mode makes it easier to spot relative differences or similarities
21315 in overlapping areas of the color components that are supposed to be identical,
21316 such as neutral whites, grays, or blacks.
21319 Display separate graph for the color components side by side in
21320 @code{row} mode or one below the other in @code{column} mode.
21323 Display separate graph for the color components side by side in
21324 @code{column} mode or one below the other in @code{row} mode.
21326 Using this display mode makes it easy to spot color casts in the highlights
21327 and shadows of an image, by comparing the contours of the top and the bottom
21328 graphs of each waveform. Since whites, grays, and blacks are characterized
21329 by exactly equal amounts of red, green, and blue, neutral areas of the picture
21330 should display three waveforms of roughly equal width/height. If not, the
21331 correction is easy to perform by making level adjustments the three waveforms.
21333 Default is @code{stack}.
21335 @item components, c
21336 Set which color components to display. Default is 1, which means only luminance
21337 or red color component if input is in RGB colorspace. If is set for example to
21338 7 it will display all 3 (if) available color components.
21343 No envelope, this is default.
21346 Instant envelope, minimum and maximum values presented in graph will be easily
21347 visible even with small @code{step} value.
21350 Hold minimum and maximum values presented in graph across time. This way you
21351 can still spot out of range values without constantly looking at waveforms.
21354 Peak and instant envelope combined together.
21360 No filtering, this is default.
21363 Luma and chroma combined together.
21366 Similar as above, but shows difference between blue and red chroma.
21369 Similar as above, but use different colors.
21372 Similar as above, but again with different colors.
21375 Displays only chroma.
21378 Displays actual color value on waveform.
21381 Similar as above, but with luma showing frequency of chroma values.
21385 Set which graticule to display.
21389 Do not display graticule.
21392 Display green graticule showing legal broadcast ranges.
21395 Display orange graticule showing legal broadcast ranges.
21398 Display invert graticule showing legal broadcast ranges.
21402 Set graticule opacity.
21405 Set graticule flags.
21409 Draw numbers above lines. By default enabled.
21412 Draw dots instead of lines.
21416 Set scale used for displaying graticule.
21423 Default is digital.
21426 Set background opacity.
21430 Set tint for output.
21431 Only used with lowpass filter and when display is not overlay and input
21432 pixel formats are not RGB.
21435 @section weave, doubleweave
21437 The @code{weave} takes a field-based video input and join
21438 each two sequential fields into single frame, producing a new double
21439 height clip with half the frame rate and half the frame count.
21441 The @code{doubleweave} works same as @code{weave} but without
21442 halving frame rate and frame count.
21444 It accepts the following option:
21448 Set first field. Available values are:
21452 Set the frame as top-field-first.
21455 Set the frame as bottom-field-first.
21459 @subsection Examples
21463 Interlace video using @ref{select} and @ref{separatefields} filter:
21465 separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
21470 Apply the xBR high-quality magnification filter which is designed for pixel
21471 art. It follows a set of edge-detection rules, see
21472 @url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}.
21474 It accepts the following option:
21478 Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
21479 @code{3xBR} and @code{4} for @code{4xBR}.
21480 Default is @code{3}.
21485 Apply cross fade from one input video stream to another input video stream.
21486 The cross fade is applied for specified duration.
21488 The filter accepts the following options:
21492 Set one of available transition effects:
21540 Default transition effect is fade.
21543 Set cross fade duration in seconds.
21544 Default duration is 1 second.
21547 Set cross fade start relative to first input stream in seconds.
21548 Default offset is 0.
21551 Set expression for custom transition effect.
21553 The expressions can use the following variables and functions:
21558 The coordinates of the current sample.
21562 The width and height of the image.
21565 Progress of transition effect.
21568 Currently processed plane.
21571 Return value of first input at current location and plane.
21574 Return value of second input at current location and plane.
21580 Return the value of the pixel at location (@var{x},@var{y}) of the
21581 first/second/third/fourth component of first input.
21587 Return the value of the pixel at location (@var{x},@var{y}) of the
21588 first/second/third/fourth component of second input.
21592 @subsection Examples
21596 Cross fade from one input video to another input video, with fade transition and duration of transition
21597 of 2 seconds starting at offset of 5 seconds:
21599 ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4
21604 Pick median pixels from several input videos.
21606 The filter accepts the following options:
21610 Set number of inputs.
21611 Default is 3. Allowed range is from 3 to 255.
21612 If number of inputs is even number, than result will be mean value between two median values.
21615 Set which planes to filter. Default value is @code{15}, by which all planes are processed.
21618 Set median percentile. Default value is @code{0.5}.
21619 Default value of @code{0.5} will pick always median values, while @code{0} will pick
21620 minimum values, and @code{1} maximum values.
21623 @subsection Commands
21625 This filter supports all above options as @ref{commands}, excluding option @code{inputs}.
21628 Stack video inputs into custom layout.
21630 All streams must be of same pixel format.
21632 The filter accepts the following options:
21636 Set number of input streams. Default is 2.
21639 Specify layout of inputs.
21640 This option requires the desired layout configuration to be explicitly set by the user.
21641 This sets position of each video input in output. Each input
21642 is separated by '|'.
21643 The first number represents the column, and the second number represents the row.
21644 Numbers start at 0 and are separated by '_'. Optionally one can use wX and hX,
21645 where X is video input from which to take width or height.
21646 Multiple values can be used when separated by '+'. In such
21647 case values are summed together.
21649 Note that if inputs are of different sizes gaps may appear, as not all of
21650 the output video frame will be filled. Similarly, videos can overlap each
21651 other if their position doesn't leave enough space for the full frame of
21654 For 2 inputs, a default layout of @code{0_0|w0_0} is set. In all other cases,
21655 a layout must be set by the user.
21658 If set to 1, force the output to terminate when the shortest input
21659 terminates. Default value is 0.
21662 If set to valid color, all unused pixels will be filled with that color.
21663 By default fill is set to none, so it is disabled.
21666 @subsection Examples
21670 Display 4 inputs into 2x2 grid.
21674 input1(0, 0) | input3(w0, 0)
21675 input2(0, h0) | input4(w0, h0)
21679 xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
21682 Note that if inputs are of different sizes, gaps or overlaps may occur.
21685 Display 4 inputs into 1x4 grid.
21692 input4(0, h0+h1+h2)
21696 xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
21699 Note that if inputs are of different widths, unused space will appear.
21702 Display 9 inputs into 3x3 grid.
21706 input1(0, 0) | input4(w0, 0) | input7(w0+w3, 0)
21707 input2(0, h0) | input5(w0, h0) | input8(w0+w3, h0)
21708 input3(0, h0+h1) | input6(w0, h0+h1) | input9(w0+w3, h0+h1)
21712 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
21715 Note that if inputs are of different sizes, gaps or overlaps may occur.
21718 Display 16 inputs into 4x4 grid.
21722 input1(0, 0) | input5(w0, 0) | input9 (w0+w4, 0) | input13(w0+w4+w8, 0)
21723 input2(0, h0) | input6(w0, h0) | input10(w0+w4, h0) | input14(w0+w4+w8, h0)
21724 input3(0, h0+h1) | input7(w0, h0+h1) | input11(w0+w4, h0+h1) | input15(w0+w4+w8, h0+h1)
21725 input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2)
21729 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|
21730 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
21733 Note that if inputs are of different sizes, gaps or overlaps may occur.
21740 Deinterlace the input video ("yadif" means "yet another deinterlacing
21743 It accepts the following parameters:
21749 The interlacing mode to adopt. It accepts one of the following values:
21752 @item 0, send_frame
21753 Output one frame for each frame.
21754 @item 1, send_field
21755 Output one frame for each field.
21756 @item 2, send_frame_nospatial
21757 Like @code{send_frame}, but it skips the spatial interlacing check.
21758 @item 3, send_field_nospatial
21759 Like @code{send_field}, but it skips the spatial interlacing check.
21762 The default value is @code{send_frame}.
21765 The picture field parity assumed for the input interlaced video. It accepts one
21766 of the following values:
21770 Assume the top field is first.
21772 Assume the bottom field is first.
21774 Enable automatic detection of field parity.
21777 The default value is @code{auto}.
21778 If the interlacing is unknown or the decoder does not export this information,
21779 top field first will be assumed.
21782 Specify which frames to deinterlace. Accepts one of the following
21787 Deinterlace all frames.
21788 @item 1, interlaced
21789 Only deinterlace frames marked as interlaced.
21792 The default value is @code{all}.
21795 @section yadif_cuda
21797 Deinterlace the input video using the @ref{yadif} algorithm, but implemented
21798 in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec
21801 It accepts the following parameters:
21807 The interlacing mode to adopt. It accepts one of the following values:
21810 @item 0, send_frame
21811 Output one frame for each frame.
21812 @item 1, send_field
21813 Output one frame for each field.
21814 @item 2, send_frame_nospatial
21815 Like @code{send_frame}, but it skips the spatial interlacing check.
21816 @item 3, send_field_nospatial
21817 Like @code{send_field}, but it skips the spatial interlacing check.
21820 The default value is @code{send_frame}.
21823 The picture field parity assumed for the input interlaced video. It accepts one
21824 of the following values:
21828 Assume the top field is first.
21830 Assume the bottom field is first.
21832 Enable automatic detection of field parity.
21835 The default value is @code{auto}.
21836 If the interlacing is unknown or the decoder does not export this information,
21837 top field first will be assumed.
21840 Specify which frames to deinterlace. Accepts one of the following
21845 Deinterlace all frames.
21846 @item 1, interlaced
21847 Only deinterlace frames marked as interlaced.
21850 The default value is @code{all}.
21855 Apply blur filter while preserving edges ("yaepblur" means "yet another edge preserving blur filter").
21856 The algorithm is described in
21857 "J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980."
21859 It accepts the following parameters:
21863 Set the window radius. Default value is 3.
21866 Set which planes to filter. Default is only the first plane.
21869 Set blur strength. Default value is 128.
21872 @subsection Commands
21873 This filter supports same @ref{commands} as options.
21877 Apply Zoom & Pan effect.
21879 This filter accepts the following options:
21883 Set the zoom expression. Range is 1-10. Default is 1.
21887 Set the x and y expression. Default is 0.
21890 Set the duration expression in number of frames.
21891 This sets for how many number of frames effect will last for
21892 single input image.
21895 Set the output image size, default is 'hd720'.
21898 Set the output frame rate, default is '25'.
21901 Each expression can contain the following constants:
21920 Output frame count.
21923 The input timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
21925 @item out_time, time, ot
21926 The output timestamp expressed in seconds.
21930 Last calculated 'x' and 'y' position from 'x' and 'y' expression
21931 for current input frame.
21935 'x' and 'y' of last output frame of previous input frame or 0 when there was
21936 not yet such frame (first input frame).
21939 Last calculated zoom from 'z' expression for current input frame.
21942 Last calculated zoom of last output frame of previous input frame.
21945 Number of output frames for current input frame. Calculated from 'd' expression
21946 for each input frame.
21949 number of output frames created for previous input frame
21952 Rational number: input width / input height
21955 sample aspect ratio
21958 display aspect ratio
21962 @subsection Examples
21966 Zoom in up to 1.5x and pan at same time to some spot near center of picture:
21968 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
21972 Zoom in up to 1.5x and pan always at center of picture:
21974 zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
21978 Same as above but without pausing:
21980 zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
21984 Zoom in 2x into center of picture only for the first second of the input video:
21986 zoompan=z='if(between(in_time,0,1),2,1)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
21993 Scale (resize) the input video, using the z.lib library:
21994 @url{https://github.com/sekrit-twc/zimg}. To enable compilation of this
21995 filter, you need to configure FFmpeg with @code{--enable-libzimg}.
21997 The zscale filter forces the output display aspect ratio to be the same
21998 as the input, by changing the output sample aspect ratio.
22000 If the input image format is different from the format requested by
22001 the next filter, the zscale filter will convert the input to the
22004 @subsection Options
22005 The filter accepts the following options.
22010 Set the output video dimension expression. Default value is the input
22013 If the @var{width} or @var{w} value is 0, the input width is used for
22014 the output. If the @var{height} or @var{h} value is 0, the input height
22015 is used for the output.
22017 If one and only one of the values is -n with n >= 1, the zscale filter
22018 will use a value that maintains the aspect ratio of the input image,
22019 calculated from the other specified dimension. After that it will,
22020 however, make sure that the calculated dimension is divisible by n and
22021 adjust the value if necessary.
22023 If both values are -n with n >= 1, the behavior will be identical to
22024 both values being set to 0 as previously detailed.
22026 See below for the list of accepted constants for use in the dimension
22030 Set the video size. For the syntax of this option, check the
22031 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22034 Set the dither type.
22036 Possible values are:
22041 @item error_diffusion
22047 Set the resize filter type.
22049 Possible values are:
22059 Default is bilinear.
22062 Set the color range.
22064 Possible values are:
22071 Default is same as input.
22074 Set the color primaries.
22076 Possible values are:
22086 Default is same as input.
22089 Set the transfer characteristics.
22091 Possible values are:
22105 Default is same as input.
22108 Set the colorspace matrix.
22110 Possible value are:
22121 Default is same as input.
22124 Set the input color range.
22126 Possible values are:
22133 Default is same as input.
22135 @item primariesin, pin
22136 Set the input color primaries.
22138 Possible values are:
22148 Default is same as input.
22150 @item transferin, tin
22151 Set the input transfer characteristics.
22153 Possible values are:
22164 Default is same as input.
22166 @item matrixin, min
22167 Set the input colorspace matrix.
22169 Possible value are:
22181 Set the output chroma location.
22183 Possible values are:
22194 @item chromalin, cin
22195 Set the input chroma location.
22197 Possible values are:
22209 Set the nominal peak luminance.
22212 The values of the @option{w} and @option{h} options are expressions
22213 containing the following constants:
22218 The input width and height
22222 These are the same as @var{in_w} and @var{in_h}.
22226 The output (scaled) width and height
22230 These are the same as @var{out_w} and @var{out_h}
22233 The same as @var{iw} / @var{ih}
22236 input sample aspect ratio
22239 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
22243 horizontal and vertical input chroma subsample values. For example for the
22244 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
22248 horizontal and vertical output chroma subsample values. For example for the
22249 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
22252 @subsection Commands
22254 This filter supports the following commands:
22258 Set the output video dimension expression.
22259 The command accepts the same syntax of the corresponding option.
22261 If the specified expression is not valid, it is kept at its current
22265 @c man end VIDEO FILTERS
22267 @chapter OpenCL Video Filters
22268 @c man begin OPENCL VIDEO FILTERS
22270 Below is a description of the currently available OpenCL video filters.
22272 To enable compilation of these filters you need to configure FFmpeg with
22273 @code{--enable-opencl}.
22275 Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph.
22278 @item -init_hw_device opencl[=@var{name}][:@var{device}[,@var{key=value}...]]
22279 Initialise a new hardware device of type @var{opencl} called @var{name}, using the
22280 given device parameters.
22282 @item -filter_hw_device @var{name}
22283 Pass the hardware device called @var{name} to all filters in any filter graph.
22287 For more detailed information see @url{https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options}
22291 Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it.
22293 -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
22297 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.
22299 @section avgblur_opencl
22301 Apply average blur filter.
22303 The filter accepts the following options:
22307 Set horizontal radius size.
22308 Range is @code{[1, 1024]} and default value is @code{1}.
22311 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
22314 Set vertical radius size. Range is @code{[1, 1024]} and default value is @code{0}. If zero, @code{sizeX} value will be used.
22317 @subsection Example
22321 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.
22323 -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
22327 @section boxblur_opencl
22329 Apply a boxblur algorithm to the input video.
22331 It accepts the following parameters:
22335 @item luma_radius, lr
22336 @item luma_power, lp
22337 @item chroma_radius, cr
22338 @item chroma_power, cp
22339 @item alpha_radius, ar
22340 @item alpha_power, ap
22344 A description of the accepted options follows.
22347 @item luma_radius, lr
22348 @item chroma_radius, cr
22349 @item alpha_radius, ar
22350 Set an expression for the box radius in pixels used for blurring the
22351 corresponding input plane.
22353 The radius value must be a non-negative number, and must not be
22354 greater than the value of the expression @code{min(w,h)/2} for the
22355 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
22358 Default value for @option{luma_radius} is "2". If not specified,
22359 @option{chroma_radius} and @option{alpha_radius} default to the
22360 corresponding value set for @option{luma_radius}.
22362 The expressions can contain the following constants:
22366 The input width and height in pixels.
22370 The input chroma image width and height in pixels.
22374 The horizontal and vertical chroma subsample values. For example, for the
22375 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
22378 @item luma_power, lp
22379 @item chroma_power, cp
22380 @item alpha_power, ap
22381 Specify how many times the boxblur filter is applied to the
22382 corresponding plane.
22384 Default value for @option{luma_power} is 2. If not specified,
22385 @option{chroma_power} and @option{alpha_power} default to the
22386 corresponding value set for @option{luma_power}.
22388 A value of 0 will disable the effect.
22391 @subsection Examples
22393 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.
22397 Apply a boxblur filter with the luma, chroma, and alpha radius
22398 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.
22400 -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
22401 -i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
22405 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.
22407 For the luma plane, a 2x2 box radius will be run once.
22409 For the chroma plane, a 4x4 box radius will be run 5 times.
22411 For the alpha plane, a 3x3 box radius will be run 7 times.
22413 -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
22417 @section colorkey_opencl
22418 RGB colorspace color keying.
22420 The filter accepts the following options:
22424 The color which will be replaced with transparency.
22427 Similarity percentage with the key color.
22429 0.01 matches only the exact key color, while 1.0 matches everything.
22434 0.0 makes pixels either fully transparent, or not transparent at all.
22436 Higher values result in semi-transparent pixels, with a higher transparency
22437 the more similar the pixels color is to the key color.
22440 @subsection Examples
22444 Make every semi-green pixel in the input transparent with some slight blending:
22446 -i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
22450 @section convolution_opencl
22452 Apply convolution of 3x3, 5x5, 7x7 matrix.
22454 The filter accepts the following options:
22461 Set matrix for each plane.
22462 Matrix is sequence of 9, 25 or 49 signed numbers.
22463 Default value for each plane is @code{0 0 0 0 1 0 0 0 0}.
22469 Set multiplier for calculated value for each plane.
22470 If unset or 0, it will be sum of all matrix elements.
22471 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{1.0}.
22477 Set bias for each plane. This value is added to the result of the multiplication.
22478 Useful for making the overall image brighter or darker.
22479 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{0.0}.
22483 @subsection Examples
22489 -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
22495 -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
22499 Apply edge enhance:
22501 -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
22507 -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
22511 Apply laplacian edge detector which includes diagonals:
22513 -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
22519 -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
22523 @section erosion_opencl
22525 Apply erosion effect to the video.
22527 This filter replaces the pixel by the local(3x3) minimum.
22529 It accepts the following options:
22536 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
22537 If @code{0}, plane will remain unchanged.
22540 Flag which specifies the pixel to refer to.
22541 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
22543 Flags to local 3x3 coordinates region centered on @code{x}:
22552 @subsection Example
22556 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.
22558 -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
22562 @section deshake_opencl
22563 Feature-point based video stabilization filter.
22565 The filter accepts the following options:
22569 Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to @code{0}.
22572 Whether or not additional debug info should be displayed, both in the processed output and in the console.
22574 Note that in order to see console debug output you will also need to pass @code{-v verbose} to ffmpeg.
22576 Viewing point matches in the output video is only supported for RGB input.
22578 Defaults to @code{0}.
22580 @item adaptive_crop
22581 Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels.
22583 Defaults to @code{1}.
22585 @item refine_features
22586 Whether or not feature points should be refined at a sub-pixel level.
22588 This can be turned off for a slight performance gain at the cost of precision.
22590 Defaults to @code{1}.
22592 @item smooth_strength
22593 The strength of the smoothing applied to the camera path from @code{0.0} to @code{1.0}.
22595 @code{1.0} is the maximum smoothing strength while values less than that result in less smoothing.
22597 @code{0.0} causes the filter to adaptively choose a smoothing strength on a per-frame basis.
22599 Defaults to @code{0.0}.
22601 @item smooth_window_multiplier
22602 Controls the size of the smoothing window (the number of frames buffered to determine motion information from).
22604 The size of the smoothing window is determined by multiplying the framerate of the video by this number.
22606 Acceptable values range from @code{0.1} to @code{10.0}.
22608 Larger values increase the amount of motion data available for determining how to smooth the camera path,
22609 potentially improving smoothness, but also increase latency and memory usage.
22611 Defaults to @code{2.0}.
22615 @subsection Examples
22619 Stabilize a video with a fixed, medium smoothing strength:
22621 -i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT
22625 Stabilize a video with debugging (both in console and in rendered video):
22627 -i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT
22631 @section dilation_opencl
22633 Apply dilation effect to the video.
22635 This filter replaces the pixel by the local(3x3) maximum.
22637 It accepts the following options:
22644 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
22645 If @code{0}, plane will remain unchanged.
22648 Flag which specifies the pixel to refer to.
22649 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
22651 Flags to local 3x3 coordinates region centered on @code{x}:
22660 @subsection Example
22664 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.
22666 -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
22670 @section nlmeans_opencl
22672 Non-local Means denoise filter through OpenCL, this filter accepts same options as @ref{nlmeans}.
22674 @section overlay_opencl
22676 Overlay one video on top of another.
22678 It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid.
22679 This filter requires same memory layout for all the inputs. So, format conversion may be needed.
22681 The filter accepts the following options:
22686 Set the x coordinate of the overlaid video on the main video.
22687 Default value is @code{0}.
22690 Set the y coordinate of the overlaid video on the main video.
22691 Default value is @code{0}.
22695 @subsection Examples
22699 Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format.
22701 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
22704 The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p.
22706 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
22711 @section pad_opencl
22713 Add paddings to the input image, and place the original input at the
22714 provided @var{x}, @var{y} coordinates.
22716 It accepts the following options:
22721 Specify an expression for the size of the output image with the
22722 paddings added. If the value for @var{width} or @var{height} is 0, the
22723 corresponding input size is used for the output.
22725 The @var{width} expression can reference the value set by the
22726 @var{height} expression, and vice versa.
22728 The default value of @var{width} and @var{height} is 0.
22732 Specify the offsets to place the input image at within the padded area,
22733 with respect to the top/left border of the output image.
22735 The @var{x} expression can reference the value set by the @var{y}
22736 expression, and vice versa.
22738 The default value of @var{x} and @var{y} is 0.
22740 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
22741 so the input image is centered on the padded area.
22744 Specify the color of the padded area. For the syntax of this option,
22745 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
22746 manual,ffmpeg-utils}.
22749 Pad to an aspect instead to a resolution.
22752 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
22753 options are expressions containing the following constants:
22758 The input video width and height.
22762 These are the same as @var{in_w} and @var{in_h}.
22766 The output width and height (the size of the padded area), as
22767 specified by the @var{width} and @var{height} expressions.
22771 These are the same as @var{out_w} and @var{out_h}.
22775 The x and y offsets as specified by the @var{x} and @var{y}
22776 expressions, or NAN if not yet specified.
22779 same as @var{iw} / @var{ih}
22782 input sample aspect ratio
22785 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
22788 @section prewitt_opencl
22790 Apply the Prewitt operator (@url{https://en.wikipedia.org/wiki/Prewitt_operator}) to input video stream.
22792 The filter accepts the following option:
22796 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
22799 Set value which will be multiplied with filtered result.
22800 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
22803 Set value which will be added to filtered result.
22804 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
22807 @subsection Example
22811 Apply the Prewitt operator with scale set to 2 and delta set to 10.
22813 -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
22817 @anchor{program_opencl}
22818 @section program_opencl
22820 Filter video using an OpenCL program.
22825 OpenCL program source file.
22828 Kernel name in program.
22831 Number of inputs to the filter. Defaults to 1.
22834 Size of output frames. Defaults to the same as the first input.
22838 The @code{program_opencl} filter also supports the @ref{framesync} options.
22840 The program source file must contain a kernel function with the given name,
22841 which will be run once for each plane of the output. Each run on a plane
22842 gets enqueued as a separate 2D global NDRange with one work-item for each
22843 pixel to be generated. The global ID offset for each work-item is therefore
22844 the coordinates of a pixel in the destination image.
22846 The kernel function needs to take the following arguments:
22849 Destination image, @var{__write_only image2d_t}.
22851 This image will become the output; the kernel should write all of it.
22853 Frame index, @var{unsigned int}.
22855 This is a counter starting from zero and increasing by one for each frame.
22857 Source images, @var{__read_only image2d_t}.
22859 These are the most recent images on each input. The kernel may read from
22860 them to generate the output, but they can't be written to.
22867 Copy the input to the output (output must be the same size as the input).
22869 __kernel void copy(__write_only image2d_t destination,
22870 unsigned int index,
22871 __read_only image2d_t source)
22873 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
22875 int2 location = (int2)(get_global_id(0), get_global_id(1));
22877 float4 value = read_imagef(source, sampler, location);
22879 write_imagef(destination, location, value);
22884 Apply a simple transformation, rotating the input by an amount increasing
22885 with the index counter. Pixel values are linearly interpolated by the
22886 sampler, and the output need not have the same dimensions as the input.
22888 __kernel void rotate_image(__write_only image2d_t dst,
22889 unsigned int index,
22890 __read_only image2d_t src)
22892 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
22893 CLK_FILTER_LINEAR);
22895 float angle = (float)index / 100.0f;
22897 float2 dst_dim = convert_float2(get_image_dim(dst));
22898 float2 src_dim = convert_float2(get_image_dim(src));
22900 float2 dst_cen = dst_dim / 2.0f;
22901 float2 src_cen = src_dim / 2.0f;
22903 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
22905 float2 dst_pos = convert_float2(dst_loc) - dst_cen;
22907 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
22908 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
22910 src_pos = src_pos * src_dim / dst_dim;
22912 float2 src_loc = src_pos + src_cen;
22914 if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
22915 src_loc.x > src_dim.x || src_loc.y > src_dim.y)
22916 write_imagef(dst, dst_loc, 0.5f);
22918 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
22923 Blend two inputs together, with the amount of each input used varying
22924 with the index counter.
22926 __kernel void blend_images(__write_only image2d_t dst,
22927 unsigned int index,
22928 __read_only image2d_t src1,
22929 __read_only image2d_t src2)
22931 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
22932 CLK_FILTER_LINEAR);
22934 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
22936 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
22937 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
22938 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
22940 float4 val1 = read_imagef(src1, sampler, src1_loc);
22941 float4 val2 = read_imagef(src2, sampler, src2_loc);
22943 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
22949 @section roberts_opencl
22950 Apply the Roberts cross operator (@url{https://en.wikipedia.org/wiki/Roberts_cross}) to input video stream.
22952 The filter accepts the following option:
22956 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
22959 Set value which will be multiplied with filtered result.
22960 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
22963 Set value which will be added to filtered result.
22964 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
22967 @subsection Example
22971 Apply the Roberts cross operator with scale set to 2 and delta set to 10
22973 -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
22977 @section sobel_opencl
22979 Apply the Sobel operator (@url{https://en.wikipedia.org/wiki/Sobel_operator}) to input video stream.
22981 The filter accepts the following option:
22985 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
22988 Set value which will be multiplied with filtered result.
22989 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
22992 Set value which will be added to filtered result.
22993 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
22996 @subsection Example
23000 Apply sobel operator with scale set to 2 and delta set to 10
23002 -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
23006 @section tonemap_opencl
23008 Perform HDR(PQ/HLG) to SDR conversion with tone-mapping.
23010 It accepts the following parameters:
23014 Specify the tone-mapping operator to be used. Same as tonemap option in @ref{tonemap}.
23017 Tune the tone mapping algorithm. same as param option in @ref{tonemap}.
23020 Apply desaturation for highlights that exceed this level of brightness. The
23021 higher the parameter, the more color information will be preserved. This
23022 setting helps prevent unnaturally blown-out colors for super-highlights, by
23023 (smoothly) turning into white instead. This makes images feel more natural,
23024 at the cost of reducing information about out-of-range colors.
23026 The default value is 0.5, and the algorithm here is a little different from
23027 the cpu version tonemap currently. A setting of 0.0 disables this option.
23030 The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold
23031 is used to detect whether the scene has changed or not. If the distance between
23032 the current frame average brightness and the current running average exceeds
23033 a threshold value, we would re-calculate scene average and peak brightness.
23034 The default value is 0.2.
23037 Specify the output pixel format.
23039 Currently supported formats are:
23046 Set the output color range.
23048 Possible values are:
23054 Default is same as input.
23057 Set the output color primaries.
23059 Possible values are:
23065 Default is same as input.
23068 Set the output transfer characteristics.
23070 Possible values are:
23079 Set the output colorspace matrix.
23081 Possible value are:
23087 Default is same as input.
23091 @subsection Example
23095 Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator.
23097 -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
23101 @section unsharp_opencl
23103 Sharpen or blur the input video.
23105 It accepts the following parameters:
23108 @item luma_msize_x, lx
23109 Set the luma matrix horizontal size.
23110 Range is @code{[1, 23]} and default value is @code{5}.
23112 @item luma_msize_y, ly
23113 Set the luma matrix vertical size.
23114 Range is @code{[1, 23]} and default value is @code{5}.
23116 @item luma_amount, la
23117 Set the luma effect strength.
23118 Range is @code{[-10, 10]} and default value is @code{1.0}.
23120 Negative values will blur the input video, while positive values will
23121 sharpen it, a value of zero will disable the effect.
23123 @item chroma_msize_x, cx
23124 Set the chroma matrix horizontal size.
23125 Range is @code{[1, 23]} and default value is @code{5}.
23127 @item chroma_msize_y, cy
23128 Set the chroma matrix vertical size.
23129 Range is @code{[1, 23]} and default value is @code{5}.
23131 @item chroma_amount, ca
23132 Set the chroma effect strength.
23133 Range is @code{[-10, 10]} and default value is @code{0.0}.
23135 Negative values will blur the input video, while positive values will
23136 sharpen it, a value of zero will disable the effect.
23140 All parameters are optional and default to the equivalent of the
23141 string '5:5:1.0:5:5:0.0'.
23143 @subsection Examples
23147 Apply strong luma sharpen effect:
23149 -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
23153 Apply a strong blur of both luma and chroma parameters:
23155 -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
23159 @section xfade_opencl
23161 Cross fade two videos with custom transition effect by using OpenCL.
23163 It accepts the following options:
23167 Set one of possible transition effects.
23171 Select custom transition effect, the actual transition description
23172 will be picked from source and kernel options.
23184 Default transition is fade.
23188 OpenCL program source file for custom transition.
23191 Set name of kernel to use for custom transition from program source file.
23194 Set duration of video transition.
23197 Set time of start of transition relative to first video.
23200 The program source file must contain a kernel function with the given name,
23201 which will be run once for each plane of the output. Each run on a plane
23202 gets enqueued as a separate 2D global NDRange with one work-item for each
23203 pixel to be generated. The global ID offset for each work-item is therefore
23204 the coordinates of a pixel in the destination image.
23206 The kernel function needs to take the following arguments:
23209 Destination image, @var{__write_only image2d_t}.
23211 This image will become the output; the kernel should write all of it.
23214 First Source image, @var{__read_only image2d_t}.
23215 Second Source image, @var{__read_only image2d_t}.
23217 These are the most recent images on each input. The kernel may read from
23218 them to generate the output, but they can't be written to.
23221 Transition progress, @var{float}. This value is always between 0 and 1 inclusive.
23228 Apply dots curtain transition effect:
23230 __kernel void blend_images(__write_only image2d_t dst,
23231 __read_only image2d_t src1,
23232 __read_only image2d_t src2,
23235 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
23236 CLK_FILTER_LINEAR);
23237 int2 p = (int2)(get_global_id(0), get_global_id(1));
23238 float2 rp = (float2)(get_global_id(0), get_global_id(1));
23239 float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y);
23242 float2 dots = (float2)(20.0, 20.0);
23243 float2 center = (float2)(0,0);
23246 float4 val1 = read_imagef(src1, sampler, p);
23247 float4 val2 = read_imagef(src2, sampler, p);
23248 bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center));
23250 write_imagef(dst, p, next ? val1 : val2);
23256 @c man end OPENCL VIDEO FILTERS
23258 @chapter VAAPI Video Filters
23259 @c man begin VAAPI VIDEO FILTERS
23261 VAAPI Video filters are usually used with VAAPI decoder and VAAPI encoder. Below is a description of VAAPI video filters.
23263 To enable compilation of these filters you need to configure FFmpeg with
23264 @code{--enable-vaapi}.
23266 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}
23268 @section tonemap_vaapi
23270 Perform HDR(High Dynamic Range) to SDR(Standard Dynamic Range) conversion with tone-mapping.
23271 It maps the dynamic range of HDR10 content to the SDR content.
23272 It currently only accepts HDR10 as input.
23274 It accepts the following parameters:
23278 Specify the output pixel format.
23280 Currently supported formats are:
23289 Set the output color primaries.
23291 Default is same as input.
23294 Set the output transfer characteristics.
23299 Set the output colorspace matrix.
23301 Default is same as input.
23305 @subsection Example
23309 Convert HDR(HDR10) video to bt2020-transfer-characteristic p010 format
23311 tonemap_vaapi=format=p010:t=bt2020-10
23315 @c man end VAAPI VIDEO FILTERS
23317 @chapter Video Sources
23318 @c man begin VIDEO SOURCES
23320 Below is a description of the currently available video sources.
23324 Buffer video frames, and make them available to the filter chain.
23326 This source is mainly intended for a programmatic use, in particular
23327 through the interface defined in @file{libavfilter/buffersrc.h}.
23329 It accepts the following parameters:
23334 Specify the size (width and height) of the buffered video frames. For the
23335 syntax of this option, check the
23336 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23339 The input video width.
23342 The input video height.
23345 A string representing the pixel format of the buffered video frames.
23346 It may be a number corresponding to a pixel format, or a pixel format
23350 Specify the timebase assumed by the timestamps of the buffered frames.
23353 Specify the frame rate expected for the video stream.
23355 @item pixel_aspect, sar
23356 The sample (pixel) aspect ratio of the input video.
23359 This option is deprecated and ignored. Prepend @code{sws_flags=@var{flags};}
23360 to the filtergraph description to specify swscale flags for automatically
23361 inserted scalers. See @ref{Filtergraph syntax}.
23363 @item hw_frames_ctx
23364 When using a hardware pixel format, this should be a reference to an
23365 AVHWFramesContext describing input frames.
23370 buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
23373 will instruct the source to accept video frames with size 320x240 and
23374 with format "yuv410p", assuming 1/24 as the timestamps timebase and
23375 square pixels (1:1 sample aspect ratio).
23376 Since the pixel format with name "yuv410p" corresponds to the number 6
23377 (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
23378 this example corresponds to:
23380 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
23383 Alternatively, the options can be specified as a flat string, but this
23384 syntax is deprecated:
23386 @var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den}
23390 Create a pattern generated by an elementary cellular automaton.
23392 The initial state of the cellular automaton can be defined through the
23393 @option{filename} and @option{pattern} options. If such options are
23394 not specified an initial state is created randomly.
23396 At each new frame a new row in the video is filled with the result of
23397 the cellular automaton next generation. The behavior when the whole
23398 frame is filled is defined by the @option{scroll} option.
23400 This source accepts the following options:
23404 Read the initial cellular automaton state, i.e. the starting row, from
23405 the specified file.
23406 In the file, each non-whitespace character is considered an alive
23407 cell, a newline will terminate the row, and further characters in the
23408 file will be ignored.
23411 Read the initial cellular automaton state, i.e. the starting row, from
23412 the specified string.
23414 Each non-whitespace character in the string is considered an alive
23415 cell, a newline will terminate the row, and further characters in the
23416 string will be ignored.
23419 Set the video rate, that is the number of frames generated per second.
23422 @item random_fill_ratio, ratio
23423 Set the random fill ratio for the initial cellular automaton row. It
23424 is a floating point number value ranging from 0 to 1, defaults to
23427 This option is ignored when a file or a pattern is specified.
23429 @item random_seed, seed
23430 Set the seed for filling randomly the initial row, must be an integer
23431 included between 0 and UINT32_MAX. If not specified, or if explicitly
23432 set to -1, the filter will try to use a good random seed on a best
23436 Set the cellular automaton rule, it is a number ranging from 0 to 255.
23437 Default value is 110.
23440 Set the size of the output video. For the syntax of this option, check the
23441 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23443 If @option{filename} or @option{pattern} is specified, the size is set
23444 by default to the width of the specified initial state row, and the
23445 height is set to @var{width} * PHI.
23447 If @option{size} is set, it must contain the width of the specified
23448 pattern string, and the specified pattern will be centered in the
23451 If a filename or a pattern string is not specified, the size value
23452 defaults to "320x518" (used for a randomly generated initial state).
23455 If set to 1, scroll the output upward when all the rows in the output
23456 have been already filled. If set to 0, the new generated row will be
23457 written over the top row just after the bottom row is filled.
23460 @item start_full, full
23461 If set to 1, completely fill the output with generated rows before
23462 outputting the first frame.
23463 This is the default behavior, for disabling set the value to 0.
23466 If set to 1, stitch the left and right row edges together.
23467 This is the default behavior, for disabling set the value to 0.
23470 @subsection Examples
23474 Read the initial state from @file{pattern}, and specify an output of
23477 cellauto=f=pattern:s=200x400
23481 Generate a random initial row with a width of 200 cells, with a fill
23484 cellauto=ratio=2/3:s=200x200
23488 Create a pattern generated by rule 18 starting by a single alive cell
23489 centered on an initial row with width 100:
23491 cellauto=p=@@:s=100x400:full=0:rule=18
23495 Specify a more elaborated initial pattern:
23497 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
23502 @anchor{coreimagesrc}
23503 @section coreimagesrc
23504 Video source generated on GPU using Apple's CoreImage API on OSX.
23506 This video source is a specialized version of the @ref{coreimage} video filter.
23507 Use a core image generator at the beginning of the applied filterchain to
23508 generate the content.
23510 The coreimagesrc video source accepts the following options:
23512 @item list_generators
23513 List all available generators along with all their respective options as well as
23514 possible minimum and maximum values along with the default values.
23516 list_generators=true
23520 Specify the size of the sourced video. For the syntax of this option, check the
23521 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23522 The default value is @code{320x240}.
23525 Specify the frame rate of the sourced video, as the number of frames
23526 generated per second. It has to be a string in the format
23527 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
23528 number or a valid video frame rate abbreviation. The default value is
23532 Set the sample aspect ratio of the sourced video.
23535 Set the duration of the sourced video. See
23536 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
23537 for the accepted syntax.
23539 If not specified, or the expressed duration is negative, the video is
23540 supposed to be generated forever.
23543 Additionally, all options of the @ref{coreimage} video filter are accepted.
23544 A complete filterchain can be used for further processing of the
23545 generated input without CPU-HOST transfer. See @ref{coreimage} documentation
23546 and examples for details.
23548 @subsection Examples
23553 Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
23554 given as complete and escaped command-line for Apple's standard bash shell:
23556 ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
23558 This example is equivalent to the QRCode example of @ref{coreimage} without the
23559 need for a nullsrc video source.
23564 Generate several gradients.
23568 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
23569 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
23572 Set frame rate, expressed as number of frames per second. Default
23575 @item c0, c1, c2, c3, c4, c5, c6, c7
23576 Set 8 colors. Default values for colors is to pick random one.
23578 @item x0, y0, y0, y1
23579 Set gradient line source and destination points. If negative or out of range, random ones
23583 Set number of colors to use at once. Allowed range is from 2 to 8. Default value is 2.
23586 Set seed for picking gradient line points.
23589 Set the duration of the sourced video. See
23590 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
23591 for the accepted syntax.
23593 If not specified, or the expressed duration is negative, the video is
23594 supposed to be generated forever.
23597 Set speed of gradients rotation.
23601 @section mandelbrot
23603 Generate a Mandelbrot set fractal, and progressively zoom towards the
23604 point specified with @var{start_x} and @var{start_y}.
23606 This source accepts the following options:
23611 Set the terminal pts value. Default value is 400.
23614 Set the terminal scale value.
23615 Must be a floating point value. Default value is 0.3.
23618 Set the inner coloring mode, that is the algorithm used to draw the
23619 Mandelbrot fractal internal region.
23621 It shall assume one of the following values:
23626 Show time until convergence.
23628 Set color based on point closest to the origin of the iterations.
23633 Default value is @var{mincol}.
23636 Set the bailout value. Default value is 10.0.
23639 Set the maximum of iterations performed by the rendering
23640 algorithm. Default value is 7189.
23643 Set outer coloring mode.
23644 It shall assume one of following values:
23646 @item iteration_count
23647 Set iteration count mode.
23648 @item normalized_iteration_count
23649 set normalized iteration count mode.
23651 Default value is @var{normalized_iteration_count}.
23654 Set frame rate, expressed as number of frames per second. Default
23658 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
23659 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
23662 Set the initial scale value. Default value is 3.0.
23665 Set the initial x position. Must be a floating point value between
23666 -100 and 100. Default value is -0.743643887037158704752191506114774.
23669 Set the initial y position. Must be a floating point value between
23670 -100 and 100. Default value is -0.131825904205311970493132056385139.
23675 Generate various test patterns, as generated by the MPlayer test filter.
23677 The size of the generated video is fixed, and is 256x256.
23678 This source is useful in particular for testing encoding features.
23680 This source accepts the following options:
23685 Specify the frame rate of the sourced video, as the number of frames
23686 generated per second. It has to be a string in the format
23687 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
23688 number or a valid video frame rate abbreviation. The default value is
23692 Set the duration of the sourced video. See
23693 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
23694 for the accepted syntax.
23696 If not specified, or the expressed duration is negative, the video is
23697 supposed to be generated forever.
23701 Set the number or the name of the test to perform. Supported tests are:
23715 @item max_frames, m
23716 Set the maximum number of frames generated for each test, default value is 30.
23720 Default value is "all", which will cycle through the list of all tests.
23725 mptestsrc=t=dc_luma
23728 will generate a "dc_luma" test pattern.
23730 @section frei0r_src
23732 Provide a frei0r source.
23734 To enable compilation of this filter you need to install the frei0r
23735 header and configure FFmpeg with @code{--enable-frei0r}.
23737 This source accepts the following parameters:
23742 The size of the video to generate. For the syntax of this option, check the
23743 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23746 The framerate of the generated video. It may be a string of the form
23747 @var{num}/@var{den} or a frame rate abbreviation.
23750 The name to the frei0r source to load. For more information regarding frei0r and
23751 how to set the parameters, read the @ref{frei0r} section in the video filters
23754 @item filter_params
23755 A '|'-separated list of parameters to pass to the frei0r source.
23759 For example, to generate a frei0r partik0l source with size 200x200
23760 and frame rate 10 which is overlaid on the overlay filter main input:
23762 frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
23767 Generate a life pattern.
23769 This source is based on a generalization of John Conway's life game.
23771 The sourced input represents a life grid, each pixel represents a cell
23772 which can be in one of two possible states, alive or dead. Every cell
23773 interacts with its eight neighbours, which are the cells that are
23774 horizontally, vertically, or diagonally adjacent.
23776 At each interaction the grid evolves according to the adopted rule,
23777 which specifies the number of neighbor alive cells which will make a
23778 cell stay alive or born. The @option{rule} option allows one to specify
23781 This source accepts the following options:
23785 Set the file from which to read the initial grid state. In the file,
23786 each non-whitespace character is considered an alive cell, and newline
23787 is used to delimit the end of each row.
23789 If this option is not specified, the initial grid is generated
23793 Set the video rate, that is the number of frames generated per second.
23796 @item random_fill_ratio, ratio
23797 Set the random fill ratio for the initial random grid. It is a
23798 floating point number value ranging from 0 to 1, defaults to 1/PHI.
23799 It is ignored when a file is specified.
23801 @item random_seed, seed
23802 Set the seed for filling the initial random grid, must be an integer
23803 included between 0 and UINT32_MAX. If not specified, or if explicitly
23804 set to -1, the filter will try to use a good random seed on a best
23810 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
23811 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
23812 @var{NS} specifies the number of alive neighbor cells which make a
23813 live cell stay alive, and @var{NB} the number of alive neighbor cells
23814 which make a dead cell to become alive (i.e. to "born").
23815 "s" and "b" can be used in place of "S" and "B", respectively.
23817 Alternatively a rule can be specified by an 18-bits integer. The 9
23818 high order bits are used to encode the next cell state if it is alive
23819 for each number of neighbor alive cells, the low order bits specify
23820 the rule for "borning" new cells. Higher order bits encode for an
23821 higher number of neighbor cells.
23822 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
23823 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
23825 Default value is "S23/B3", which is the original Conway's game of life
23826 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
23827 cells, and will born a new cell if there are three alive cells around
23831 Set the size of the output video. For the syntax of this option, check the
23832 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23834 If @option{filename} is specified, the size is set by default to the
23835 same size of the input file. If @option{size} is set, it must contain
23836 the size specified in the input file, and the initial grid defined in
23837 that file is centered in the larger resulting area.
23839 If a filename is not specified, the size value defaults to "320x240"
23840 (used for a randomly generated initial grid).
23843 If set to 1, stitch the left and right grid edges together, and the
23844 top and bottom edges also. Defaults to 1.
23847 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
23848 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
23849 value from 0 to 255.
23852 Set the color of living (or new born) cells.
23855 Set the color of dead cells. If @option{mold} is set, this is the first color
23856 used to represent a dead cell.
23859 Set mold color, for definitely dead and moldy cells.
23861 For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the
23862 ffmpeg-utils manual,ffmpeg-utils}.
23865 @subsection Examples
23869 Read a grid from @file{pattern}, and center it on a grid of size
23872 life=f=pattern:s=300x300
23876 Generate a random grid of size 200x200, with a fill ratio of 2/3:
23878 life=ratio=2/3:s=200x200
23882 Specify a custom rule for evolving a randomly generated grid:
23888 Full example with slow death effect (mold) using @command{ffplay}:
23890 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
23897 @anchor{haldclutsrc}
23900 @anchor{pal100bars}
23901 @anchor{rgbtestsrc}
23903 @anchor{smptehdbars}
23906 @anchor{yuvtestsrc}
23907 @section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
23909 The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
23911 The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
23913 The @code{color} source provides an uniformly colored input.
23915 The @code{haldclutsrc} source provides an identity Hald CLUT. See also
23916 @ref{haldclut} filter.
23918 The @code{nullsrc} source returns unprocessed video frames. It is
23919 mainly useful to be employed in analysis / debugging tools, or as the
23920 source for filters which ignore the input data.
23922 The @code{pal75bars} source generates a color bars pattern, based on
23923 EBU PAL recommendations with 75% color levels.
23925 The @code{pal100bars} source generates a color bars pattern, based on
23926 EBU PAL recommendations with 100% color levels.
23928 The @code{rgbtestsrc} source generates an RGB test pattern useful for
23929 detecting RGB vs BGR issues. You should see a red, green and blue
23930 stripe from top to bottom.
23932 The @code{smptebars} source generates a color bars pattern, based on
23933 the SMPTE Engineering Guideline EG 1-1990.
23935 The @code{smptehdbars} source generates a color bars pattern, based on
23936 the SMPTE RP 219-2002.
23938 The @code{testsrc} source generates a test video pattern, showing a
23939 color pattern, a scrolling gradient and a timestamp. This is mainly
23940 intended for testing purposes.
23942 The @code{testsrc2} source is similar to testsrc, but supports more
23943 pixel formats instead of just @code{rgb24}. This allows using it as an
23944 input for other tests without requiring a format conversion.
23946 The @code{yuvtestsrc} source generates an YUV test pattern. You should
23947 see a y, cb and cr stripe from top to bottom.
23949 The sources accept the following parameters:
23954 Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
23955 source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
23956 pixels to be used as identity matrix for 3D lookup tables. Each component is
23957 coded on a @code{1/(N*N)} scale.
23960 Specify the color of the source, only available in the @code{color}
23961 source. For the syntax of this option, check the
23962 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
23965 Specify the size of the sourced video. For the syntax of this option, check the
23966 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23967 The default value is @code{320x240}.
23969 This option is not available with the @code{allrgb}, @code{allyuv}, and
23970 @code{haldclutsrc} filters.
23973 Specify the frame rate of the sourced video, as the number of frames
23974 generated per second. It has to be a string in the format
23975 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
23976 number or a valid video frame rate abbreviation. The default value is
23980 Set the duration of the sourced video. See
23981 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
23982 for the accepted syntax.
23984 If not specified, or the expressed duration is negative, the video is
23985 supposed to be generated forever.
23987 Since the frame rate is used as time base, all frames including the last one
23988 will have their full duration. If the specified duration is not a multiple
23989 of the frame duration, it will be rounded up.
23992 Set the sample aspect ratio of the sourced video.
23995 Specify the alpha (opacity) of the background, only available in the
23996 @code{testsrc2} source. The value must be between 0 (fully transparent) and
23997 255 (fully opaque, the default).
24000 Set the number of decimals to show in the timestamp, only available in the
24001 @code{testsrc} source.
24003 The displayed timestamp value will correspond to the original
24004 timestamp value multiplied by the power of 10 of the specified
24005 value. Default value is 0.
24008 @subsection Examples
24012 Generate a video with a duration of 5.3 seconds, with size
24013 176x144 and a frame rate of 10 frames per second:
24015 testsrc=duration=5.3:size=qcif:rate=10
24019 The following graph description will generate a red source
24020 with an opacity of 0.2, with size "qcif" and a frame rate of 10
24023 color=c=red@@0.2:s=qcif:r=10
24027 If the input content is to be ignored, @code{nullsrc} can be used. The
24028 following command generates noise in the luminance plane by employing
24029 the @code{geq} filter:
24031 nullsrc=s=256x256, geq=random(1)*255:128:128
24035 @subsection Commands
24037 The @code{color} source supports the following commands:
24041 Set the color of the created image. Accepts the same syntax of the
24042 corresponding @option{color} option.
24047 Generate video using an OpenCL program.
24052 OpenCL program source file.
24055 Kernel name in program.
24058 Size of frames to generate. This must be set.
24061 Pixel format to use for the generated frames. This must be set.
24064 Number of frames generated every second. Default value is '25'.
24068 For details of how the program loading works, see the @ref{program_opencl}
24075 Generate a colour ramp by setting pixel values from the position of the pixel
24076 in the output image. (Note that this will work with all pixel formats, but
24077 the generated output will not be the same.)
24079 __kernel void ramp(__write_only image2d_t dst,
24080 unsigned int index)
24082 int2 loc = (int2)(get_global_id(0), get_global_id(1));
24085 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
24087 write_imagef(dst, loc, val);
24092 Generate a Sierpinski carpet pattern, panning by a single pixel each frame.
24094 __kernel void sierpinski_carpet(__write_only image2d_t dst,
24095 unsigned int index)
24097 int2 loc = (int2)(get_global_id(0), get_global_id(1));
24099 float4 value = 0.0f;
24100 int x = loc.x + index;
24101 int y = loc.y + index;
24102 while (x > 0 || y > 0) {
24103 if (x % 3 == 1 && y % 3 == 1) {
24111 write_imagef(dst, loc, value);
24117 @section sierpinski
24119 Generate a Sierpinski carpet/triangle fractal, and randomly pan around.
24121 This source accepts the following options:
24125 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
24126 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
24129 Set frame rate, expressed as number of frames per second. Default
24133 Set seed which is used for random panning.
24136 Set max jump for single pan destination. Allowed range is from 1 to 10000.
24139 Set fractal type, can be default @code{carpet} or @code{triangle}.
24142 @c man end VIDEO SOURCES
24144 @chapter Video Sinks
24145 @c man begin VIDEO SINKS
24147 Below is a description of the currently available video sinks.
24149 @section buffersink
24151 Buffer video frames, and make them available to the end of the filter
24154 This sink is mainly intended for programmatic use, in particular
24155 through the interface defined in @file{libavfilter/buffersink.h}
24156 or the options system.
24158 It accepts a pointer to an AVBufferSinkContext structure, which
24159 defines the incoming buffers' formats, to be passed as the opaque
24160 parameter to @code{avfilter_init_filter} for initialization.
24164 Null video sink: do absolutely nothing with the input video. It is
24165 mainly useful as a template and for use in analysis / debugging
24168 @c man end VIDEO SINKS
24170 @chapter Multimedia Filters
24171 @c man begin MULTIMEDIA FILTERS
24173 Below is a description of the currently available multimedia filters.
24177 Convert input audio to a video output, displaying the audio bit scope.
24179 The filter accepts the following options:
24183 Set frame rate, expressed as number of frames per second. Default
24187 Specify the video size for the output. For the syntax of this option, check the
24188 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24189 Default value is @code{1024x256}.
24192 Specify list of colors separated by space or by '|' which will be used to
24193 draw channels. Unrecognized or missing colors will be replaced
24197 @section adrawgraph
24198 Draw a graph using input audio metadata.
24200 See @ref{drawgraph}
24202 @section agraphmonitor
24204 See @ref{graphmonitor}.
24206 @section ahistogram
24208 Convert input audio to a video output, displaying the volume histogram.
24210 The filter accepts the following options:
24214 Specify how histogram is calculated.
24216 It accepts the following values:
24219 Use single histogram for all channels.
24221 Use separate histogram for each channel.
24223 Default is @code{single}.
24226 Set frame rate, expressed as number of frames per second. Default
24230 Specify the video size for the output. For the syntax of this option, check the
24231 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24232 Default value is @code{hd720}.
24237 It accepts the following values:
24248 reverse logarithmic
24250 Default is @code{log}.
24253 Set amplitude scale.
24255 It accepts the following values:
24262 Default is @code{log}.
24265 Set how much frames to accumulate in histogram.
24266 Default is 1. Setting this to -1 accumulates all frames.
24269 Set histogram ratio of window height.
24272 Set sonogram sliding.
24274 It accepts the following values:
24277 replace old rows with new ones.
24279 scroll from top to bottom.
24281 Default is @code{replace}.
24284 @section aphasemeter
24286 Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase},
24287 representing mean phase of current audio frame. A video output can also be produced and is
24288 enabled by default. The audio is passed through as first output.
24290 Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in
24291 range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase
24292 and @code{1} means channels are in phase.
24294 The filter accepts the following options, all related to its video output:
24298 Set the output frame rate. Default value is @code{25}.
24301 Set the video size for the output. For the syntax of this option, check the
24302 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24303 Default value is @code{800x400}.
24308 Specify the red, green, blue contrast. Default values are @code{2},
24309 @code{7} and @code{1}.
24310 Allowed range is @code{[0, 255]}.
24313 Set color which will be used for drawing median phase. If color is
24314 @code{none} which is default, no median phase value will be drawn.
24317 Enable video output. Default is enabled.
24320 @subsection phasing detection
24322 The filter also detects out of phase and mono sequences in stereo streams.
24323 It logs the sequence start, end and duration when it lasts longer or as long as the minimum set.
24325 The filter accepts the following options for this detection:
24329 Enable mono and out of phase detection. Default is disabled.
24332 Set phase tolerance for mono detection, in amplitude ratio. Default is @code{0}.
24333 Allowed range is @code{[0, 1]}.
24336 Set angle threshold for out of phase detection, in degree. Default is @code{170}.
24337 Allowed range is @code{[90, 180]}.
24340 Set mono or out of phase duration until notification, expressed in seconds. Default is @code{2}.
24343 @subsection Examples
24347 Complete example with @command{ffmpeg} to detect 1 second of mono with 0.001 phase tolerance:
24349 ffmpeg -i stereo.wav -af aphasemeter=video=0:phasing=1:duration=1:tolerance=0.001 -f null -
24353 @section avectorscope
24355 Convert input audio to a video output, representing the audio vector
24358 The filter is used to measure the difference between channels of stereo
24359 audio stream. A monaural signal, consisting of identical left and right
24360 signal, results in straight vertical line. Any stereo separation is visible
24361 as a deviation from this line, creating a Lissajous figure.
24362 If the straight (or deviation from it) but horizontal line appears this
24363 indicates that the left and right channels are out of phase.
24365 The filter accepts the following options:
24369 Set the vectorscope mode.
24371 Available values are:
24374 Lissajous rotated by 45 degrees.
24377 Same as above but not rotated.
24380 Shape resembling half of circle.
24383 Default value is @samp{lissajous}.
24386 Set the video size for the output. For the syntax of this option, check the
24387 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24388 Default value is @code{400x400}.
24391 Set the output frame rate. Default value is @code{25}.
24397 Specify the red, green, blue and alpha contrast. Default values are @code{40},
24398 @code{160}, @code{80} and @code{255}.
24399 Allowed range is @code{[0, 255]}.
24405 Specify the red, green, blue and alpha fade. Default values are @code{15},
24406 @code{10}, @code{5} and @code{5}.
24407 Allowed range is @code{[0, 255]}.
24410 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}.
24411 Values lower than @var{1} will auto adjust zoom factor to maximal possible value.
24414 Set the vectorscope drawing mode.
24416 Available values are:
24419 Draw dot for each sample.
24422 Draw line between previous and current sample.
24425 Default value is @samp{dot}.
24428 Specify amplitude scale of audio samples.
24430 Available values are:
24446 Swap left channel axis with right channel axis.
24456 Mirror only x axis.
24459 Mirror only y axis.
24467 @subsection Examples
24471 Complete example using @command{ffplay}:
24473 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
24474 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
24478 @section bench, abench
24480 Benchmark part of a filtergraph.
24482 The filter accepts the following options:
24486 Start or stop a timer.
24488 Available values are:
24491 Get the current time, set it as frame metadata (using the key
24492 @code{lavfi.bench.start_time}), and forward the frame to the next filter.
24495 Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
24496 the input frame metadata to get the time difference. Time difference, average,
24497 maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
24498 @code{min}) are then printed. The timestamps are expressed in seconds.
24502 @subsection Examples
24506 Benchmark @ref{selectivecolor} filter:
24508 bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
24514 Concatenate audio and video streams, joining them together one after the
24517 The filter works on segments of synchronized video and audio streams. All
24518 segments must have the same number of streams of each type, and that will
24519 also be the number of streams at output.
24521 The filter accepts the following options:
24526 Set the number of segments. Default is 2.
24529 Set the number of output video streams, that is also the number of video
24530 streams in each segment. Default is 1.
24533 Set the number of output audio streams, that is also the number of audio
24534 streams in each segment. Default is 0.
24537 Activate unsafe mode: do not fail if segments have a different format.
24541 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
24542 @var{a} audio outputs.
24544 There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
24545 segment, in the same order as the outputs, then the inputs for the second
24548 Related streams do not always have exactly the same duration, for various
24549 reasons including codec frame size or sloppy authoring. For that reason,
24550 related synchronized streams (e.g. a video and its audio track) should be
24551 concatenated at once. The concat filter will use the duration of the longest
24552 stream in each segment (except the last one), and if necessary pad shorter
24553 audio streams with silence.
24555 For this filter to work correctly, all segments must start at timestamp 0.
24557 All corresponding streams must have the same parameters in all segments; the
24558 filtering system will automatically select a common pixel format for video
24559 streams, and a common sample format, sample rate and channel layout for
24560 audio streams, but other settings, such as resolution, must be converted
24561 explicitly by the user.
24563 Different frame rates are acceptable but will result in variable frame rate
24564 at output; be sure to configure the output file to handle it.
24566 @subsection Examples
24570 Concatenate an opening, an episode and an ending, all in bilingual version
24571 (video in stream 0, audio in streams 1 and 2):
24573 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
24574 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
24575 concat=n=3:v=1:a=2 [v] [a1] [a2]' \
24576 -map '[v]' -map '[a1]' -map '[a2]' output.mkv
24580 Concatenate two parts, handling audio and video separately, using the
24581 (a)movie sources, and adjusting the resolution:
24583 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
24584 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
24585 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
24587 Note that a desync will happen at the stitch if the audio and video streams
24588 do not have exactly the same duration in the first file.
24592 @subsection Commands
24594 This filter supports the following commands:
24597 Close the current segment and step to the next one
24603 EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness
24604 level. By default, it logs a message at a frequency of 10Hz with the
24605 Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
24606 Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
24608 The filter can only analyze streams which have a sampling rate of 48000 Hz and whose
24609 sample format is double-precision floating point. The input stream will be converted to
24610 this specification, if needed. Users may need to insert aformat and/or aresample filters
24611 after this filter to obtain the original parameters.
24613 The filter also has a video output (see the @var{video} option) with a real
24614 time graph to observe the loudness evolution. The graphic contains the logged
24615 message mentioned above, so it is not printed anymore when this option is set,
24616 unless the verbose logging is set. The main graphing area contains the
24617 short-term loudness (3 seconds of analysis), and the gauge on the right is for
24618 the momentary loudness (400 milliseconds), but can optionally be configured
24619 to instead display short-term loudness (see @var{gauge}).
24621 The green area marks a +/- 1LU target range around the target loudness
24622 (-23LUFS by default, unless modified through @var{target}).
24624 More information about the Loudness Recommendation EBU R128 on
24625 @url{http://tech.ebu.ch/loudness}.
24627 The filter accepts the following options:
24632 Activate the video output. The audio stream is passed unchanged whether this
24633 option is set or no. The video stream will be the first output stream if
24634 activated. Default is @code{0}.
24637 Set the video size. This option is for video only. For the syntax of this
24639 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24640 Default and minimum resolution is @code{640x480}.
24643 Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
24644 @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
24645 other integer value between this range is allowed.
24648 Set metadata injection. If set to @code{1}, the audio input will be segmented
24649 into 100ms output frames, each of them containing various loudness information
24650 in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
24652 Default is @code{0}.
24655 Force the frame logging level.
24657 Available values are:
24660 information logging level
24662 verbose logging level
24665 By default, the logging level is set to @var{info}. If the @option{video} or
24666 the @option{metadata} options are set, it switches to @var{verbose}.
24671 Available modes can be cumulated (the option is a @code{flag} type). Possible
24675 Disable any peak mode (default).
24677 Enable sample-peak mode.
24679 Simple peak mode looking for the higher sample value. It logs a message
24680 for sample-peak (identified by @code{SPK}).
24682 Enable true-peak mode.
24684 If enabled, the peak lookup is done on an over-sampled version of the input
24685 stream for better peak accuracy. It logs a message for true-peak.
24686 (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
24687 This mode requires a build with @code{libswresample}.
24691 Treat mono input files as "dual mono". If a mono file is intended for playback
24692 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
24693 If set to @code{true}, this option will compensate for this effect.
24694 Multi-channel input files are not affected by this option.
24697 Set a specific pan law to be used for the measurement of dual mono files.
24698 This parameter is optional, and has a default value of -3.01dB.
24701 Set a specific target level (in LUFS) used as relative zero in the visualization.
24702 This parameter is optional and has a default value of -23LUFS as specified
24703 by EBU R128. However, material published online may prefer a level of -16LUFS
24704 (e.g. for use with podcasts or video platforms).
24707 Set the value displayed by the gauge. Valid values are @code{momentary} and s
24708 @code{shortterm}. By default the momentary value will be used, but in certain
24709 scenarios it may be more useful to observe the short term value instead (e.g.
24713 Sets the display scale for the loudness. Valid parameters are @code{absolute}
24714 (in LUFS) or @code{relative} (LU) relative to the target. This only affects the
24715 video output, not the summary or continuous log output.
24718 @subsection Examples
24722 Real-time graph using @command{ffplay}, with a EBU scale meter +18:
24724 ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
24728 Run an analysis with @command{ffmpeg}:
24730 ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
24734 @section interleave, ainterleave
24736 Temporally interleave frames from several inputs.
24738 @code{interleave} works with video inputs, @code{ainterleave} with audio.
24740 These filters read frames from several inputs and send the oldest
24741 queued frame to the output.
24743 Input streams must have well defined, monotonically increasing frame
24746 In order to submit one frame to output, these filters need to enqueue
24747 at least one frame for each input, so they cannot work in case one
24748 input is not yet terminated and will not receive incoming frames.
24750 For example consider the case when one input is a @code{select} filter
24751 which always drops input frames. The @code{interleave} filter will keep
24752 reading from that input, but it will never be able to send new frames
24753 to output until the input sends an end-of-stream signal.
24755 Also, depending on inputs synchronization, the filters will drop
24756 frames in case one input receives more frames than the other ones, and
24757 the queue is already filled.
24759 These filters accept the following options:
24763 Set the number of different inputs, it is 2 by default.
24766 How to determine the end-of-stream.
24770 The duration of the longest input. (default)
24773 The duration of the shortest input.
24776 The duration of the first input.
24781 @subsection Examples
24785 Interleave frames belonging to different streams using @command{ffmpeg}:
24787 ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
24791 Add flickering blur effect:
24793 select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
24797 @section metadata, ametadata
24799 Manipulate frame metadata.
24801 This filter accepts the following options:
24805 Set mode of operation of the filter.
24807 Can be one of the following:
24811 If both @code{value} and @code{key} is set, select frames
24812 which have such metadata. If only @code{key} is set, select
24813 every frame that has such key in metadata.
24816 Add new metadata @code{key} and @code{value}. If key is already available
24820 Modify value of already present key.
24823 If @code{value} is set, delete only keys that have such value.
24824 Otherwise, delete key. If @code{key} is not set, delete all metadata values in
24828 Print key and its value if metadata was found. If @code{key} is not set print all
24829 metadata values available in frame.
24833 Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}.
24836 Set metadata value which will be used. This option is mandatory for
24837 @code{modify} and @code{add} mode.
24840 Which function to use when comparing metadata value and @code{value}.
24842 Can be one of following:
24846 Values are interpreted as strings, returns true if metadata value is same as @code{value}.
24849 Values are interpreted as strings, returns true if metadata value starts with
24850 the @code{value} option string.
24853 Values are interpreted as floats, returns true if metadata value is less than @code{value}.
24856 Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
24859 Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
24862 Values are interpreted as floats, returns true if expression from option @code{expr}
24866 Values are interpreted as strings, returns true if metadata value ends with
24867 the @code{value} option string.
24871 Set expression which is used when @code{function} is set to @code{expr}.
24872 The expression is evaluated through the eval API and can contain the following
24877 Float representation of @code{value} from metadata key.
24880 Float representation of @code{value} as supplied by user in @code{value} option.
24884 If specified in @code{print} mode, output is written to the named file. Instead of
24885 plain filename any writable url can be specified. Filename ``-'' is a shorthand
24886 for standard output. If @code{file} option is not set, output is written to the log
24887 with AV_LOG_INFO loglevel.
24890 Reduces buffering in print mode when output is written to a URL set using @var{file}.
24894 @subsection Examples
24898 Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values
24901 signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
24904 Print silencedetect output to file @file{metadata.txt}.
24906 silencedetect,ametadata=mode=print:file=metadata.txt
24909 Direct all metadata to a pipe with file descriptor 4.
24911 metadata=mode=print:file='pipe\:4'
24915 @section perms, aperms
24917 Set read/write permissions for the output frames.
24919 These filters are mainly aimed at developers to test direct path in the
24920 following filter in the filtergraph.
24922 The filters accept the following options:
24926 Select the permissions mode.
24928 It accepts the following values:
24931 Do nothing. This is the default.
24933 Set all the output frames read-only.
24935 Set all the output frames directly writable.
24937 Make the frame read-only if writable, and writable if read-only.
24939 Set each output frame read-only or writable randomly.
24943 Set the seed for the @var{random} mode, must be an integer included between
24944 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
24945 @code{-1}, the filter will try to use a good random seed on a best effort
24949 Note: in case of auto-inserted filter between the permission filter and the
24950 following one, the permission might not be received as expected in that
24951 following filter. Inserting a @ref{format} or @ref{aformat} filter before the
24952 perms/aperms filter can avoid this problem.
24954 @section realtime, arealtime
24956 Slow down filtering to match real time approximately.
24958 These filters will pause the filtering for a variable amount of time to
24959 match the output rate with the input timestamps.
24960 They are similar to the @option{re} option to @code{ffmpeg}.
24962 They accept the following options:
24966 Time limit for the pauses. Any pause longer than that will be considered
24967 a timestamp discontinuity and reset the timer. Default is 2 seconds.
24969 Speed factor for processing. The value must be a float larger than zero.
24970 Values larger than 1.0 will result in faster than realtime processing,
24971 smaller will slow processing down. The @var{limit} is automatically adapted
24972 accordingly. Default is 1.0.
24974 A processing speed faster than what is possible without these filters cannot
24979 @section select, aselect
24981 Select frames to pass in output.
24983 This filter accepts the following options:
24988 Set expression, which is evaluated for each input frame.
24990 If the expression is evaluated to zero, the frame is discarded.
24992 If the evaluation result is negative or NaN, the frame is sent to the
24993 first output; otherwise it is sent to the output with index
24994 @code{ceil(val)-1}, assuming that the input index starts from 0.
24996 For example a value of @code{1.2} corresponds to the output with index
24997 @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
25000 Set the number of outputs. The output to which to send the selected
25001 frame is based on the result of the evaluation. Default value is 1.
25004 The expression can contain the following constants:
25008 The (sequential) number of the filtered frame, starting from 0.
25011 The (sequential) number of the selected frame, starting from 0.
25013 @item prev_selected_n
25014 The sequential number of the last selected frame. It's NAN if undefined.
25017 The timebase of the input timestamps.
25020 The PTS (Presentation TimeStamp) of the filtered video frame,
25021 expressed in @var{TB} units. It's NAN if undefined.
25024 The PTS of the filtered video frame,
25025 expressed in seconds. It's NAN if undefined.
25028 The PTS of the previously filtered video frame. It's NAN if undefined.
25030 @item prev_selected_pts
25031 The PTS of the last previously filtered video frame. It's NAN if undefined.
25033 @item prev_selected_t
25034 The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined.
25037 The PTS of the first video frame in the video. It's NAN if undefined.
25040 The time of the first video frame in the video. It's NAN if undefined.
25042 @item pict_type @emph{(video only)}
25043 The type of the filtered frame. It can assume one of the following
25055 @item interlace_type @emph{(video only)}
25056 The frame interlace type. It can assume one of the following values:
25059 The frame is progressive (not interlaced).
25061 The frame is top-field-first.
25063 The frame is bottom-field-first.
25066 @item consumed_sample_n @emph{(audio only)}
25067 the number of selected samples before the current frame
25069 @item samples_n @emph{(audio only)}
25070 the number of samples in the current frame
25072 @item sample_rate @emph{(audio only)}
25073 the input sample rate
25076 This is 1 if the filtered frame is a key-frame, 0 otherwise.
25079 the position in the file of the filtered frame, -1 if the information
25080 is not available (e.g. for synthetic video)
25082 @item scene @emph{(video only)}
25083 value between 0 and 1 to indicate a new scene; a low value reflects a low
25084 probability for the current frame to introduce a new scene, while a higher
25085 value means the current frame is more likely to be one (see the example below)
25087 @item concatdec_select
25088 The concat demuxer can select only part of a concat input file by setting an
25089 inpoint and an outpoint, but the output packets may not be entirely contained
25090 in the selected interval. By using this variable, it is possible to skip frames
25091 generated by the concat demuxer which are not exactly contained in the selected
25094 This works by comparing the frame pts against the @var{lavf.concat.start_time}
25095 and the @var{lavf.concat.duration} packet metadata values which are also
25096 present in the decoded frames.
25098 The @var{concatdec_select} variable is -1 if the frame pts is at least
25099 start_time and either the duration metadata is missing or the frame pts is less
25100 than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
25103 That basically means that an input frame is selected if its pts is within the
25104 interval set by the concat demuxer.
25108 The default value of the select expression is "1".
25110 @subsection Examples
25114 Select all frames in input:
25119 The example above is the same as:
25131 Select only I-frames:
25133 select='eq(pict_type\,I)'
25137 Select one frame every 100:
25139 select='not(mod(n\,100))'
25143 Select only frames contained in the 10-20 time interval:
25145 select=between(t\,10\,20)
25149 Select only I-frames contained in the 10-20 time interval:
25151 select=between(t\,10\,20)*eq(pict_type\,I)
25155 Select frames with a minimum distance of 10 seconds:
25157 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
25161 Use aselect to select only audio frames with samples number > 100:
25163 aselect='gt(samples_n\,100)'
25167 Create a mosaic of the first scenes:
25169 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
25172 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
25176 Send even and odd frames to separate outputs, and compose them:
25178 select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
25182 Select useful frames from an ffconcat file which is using inpoints and
25183 outpoints but where the source files are not intra frame only.
25185 ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
25189 @section sendcmd, asendcmd
25191 Send commands to filters in the filtergraph.
25193 These filters read commands to be sent to other filters in the
25196 @code{sendcmd} must be inserted between two video filters,
25197 @code{asendcmd} must be inserted between two audio filters, but apart
25198 from that they act the same way.
25200 The specification of commands can be provided in the filter arguments
25201 with the @var{commands} option, or in a file specified by the
25202 @var{filename} option.
25204 These filters accept the following options:
25207 Set the commands to be read and sent to the other filters.
25209 Set the filename of the commands to be read and sent to the other
25213 @subsection Commands syntax
25215 A commands description consists of a sequence of interval
25216 specifications, comprising a list of commands to be executed when a
25217 particular event related to that interval occurs. The occurring event
25218 is typically the current frame time entering or leaving a given time
25221 An interval is specified by the following syntax:
25223 @var{START}[-@var{END}] @var{COMMANDS};
25226 The time interval is specified by the @var{START} and @var{END} times.
25227 @var{END} is optional and defaults to the maximum time.
25229 The current frame time is considered within the specified interval if
25230 it is included in the interval [@var{START}, @var{END}), that is when
25231 the time is greater or equal to @var{START} and is lesser than
25234 @var{COMMANDS} consists of a sequence of one or more command
25235 specifications, separated by ",", relating to that interval. The
25236 syntax of a command specification is given by:
25238 [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
25241 @var{FLAGS} is optional and specifies the type of events relating to
25242 the time interval which enable sending the specified command, and must
25243 be a non-null sequence of identifier flags separated by "+" or "|" and
25244 enclosed between "[" and "]".
25246 The following flags are recognized:
25249 The command is sent when the current frame timestamp enters the
25250 specified interval. In other words, the command is sent when the
25251 previous frame timestamp was not in the given interval, and the
25255 The command is sent when the current frame timestamp leaves the
25256 specified interval. In other words, the command is sent when the
25257 previous frame timestamp was in the given interval, and the
25261 The command @var{ARG} is interpreted as expression and result of
25262 expression is passed as @var{ARG}.
25264 The expression is evaluated through the eval API and can contain the following
25269 Original position in the file of the frame, or undefined if undefined
25270 for the current frame.
25273 The presentation timestamp in input.
25276 The count of the input frame for video or audio, starting from 0.
25279 The time in seconds of the current frame.
25282 The start time in seconds of the current command interval.
25285 The end time in seconds of the current command interval.
25288 The interpolated time of the current command interval, TI = (T - TS) / (TE - TS).
25293 If @var{FLAGS} is not specified, a default value of @code{[enter]} is
25296 @var{TARGET} specifies the target of the command, usually the name of
25297 the filter class or a specific filter instance name.
25299 @var{COMMAND} specifies the name of the command for the target filter.
25301 @var{ARG} is optional and specifies the optional list of argument for
25302 the given @var{COMMAND}.
25304 Between one interval specification and another, whitespaces, or
25305 sequences of characters starting with @code{#} until the end of line,
25306 are ignored and can be used to annotate comments.
25308 A simplified BNF description of the commands specification syntax
25311 @var{COMMAND_FLAG} ::= "enter" | "leave"
25312 @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
25313 @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
25314 @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
25315 @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
25316 @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
25319 @subsection Examples
25323 Specify audio tempo change at second 4:
25325 asendcmd=c='4.0 atempo tempo 1.5',atempo
25329 Target a specific filter instance:
25331 asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my
25335 Specify a list of drawtext and hue commands in a file.
25337 # show text in the interval 5-10
25338 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
25339 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
25341 # desaturate the image in the interval 15-20
25342 15.0-20.0 [enter] hue s 0,
25343 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
25345 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
25347 # apply an exponential saturation fade-out effect, starting from time 25
25348 25 [enter] hue s exp(25-t)
25351 A filtergraph allowing to read and process the above command list
25352 stored in a file @file{test.cmd}, can be specified with:
25354 sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
25359 @section setpts, asetpts
25361 Change the PTS (presentation timestamp) of the input frames.
25363 @code{setpts} works on video frames, @code{asetpts} on audio frames.
25365 This filter accepts the following options:
25370 The expression which is evaluated for each frame to construct its timestamp.
25374 The expression is evaluated through the eval API and can contain the following
25378 @item FRAME_RATE, FR
25379 frame rate, only defined for constant frame-rate video
25382 The presentation timestamp in input
25385 The count of the input frame for video or the number of consumed samples,
25386 not including the current frame for audio, starting from 0.
25388 @item NB_CONSUMED_SAMPLES
25389 The number of consumed samples, not including the current frame (only
25392 @item NB_SAMPLES, S
25393 The number of samples in the current frame (only audio)
25395 @item SAMPLE_RATE, SR
25396 The audio sample rate.
25399 The PTS of the first frame.
25402 the time in seconds of the first frame
25405 State whether the current frame is interlaced.
25408 the time in seconds of the current frame
25411 original position in the file of the frame, or undefined if undefined
25412 for the current frame
25415 The previous input PTS.
25418 previous input time in seconds
25421 The previous output PTS.
25424 previous output time in seconds
25427 The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
25431 The wallclock (RTC) time at the start of the movie in microseconds.
25434 The timebase of the input timestamps.
25438 @subsection Examples
25442 Start counting PTS from zero
25444 setpts=PTS-STARTPTS
25448 Apply fast motion effect:
25454 Apply slow motion effect:
25460 Set fixed rate of 25 frames per second:
25466 Set fixed rate 25 fps with some jitter:
25468 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
25472 Apply an offset of 10 seconds to the input PTS:
25478 Generate timestamps from a "live source" and rebase onto the current timebase:
25480 setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
25484 Generate timestamps by counting samples:
25493 Force color range for the output video frame.
25495 The @code{setrange} filter marks the color range property for the
25496 output frames. It does not change the input frame, but only sets the
25497 corresponding property, which affects how the frame is treated by
25500 The filter accepts the following options:
25505 Available values are:
25509 Keep the same color range property.
25511 @item unspecified, unknown
25512 Set the color range as unspecified.
25514 @item limited, tv, mpeg
25515 Set the color range as limited.
25517 @item full, pc, jpeg
25518 Set the color range as full.
25522 @section settb, asettb
25524 Set the timebase to use for the output frames timestamps.
25525 It is mainly useful for testing timebase configuration.
25527 It accepts the following parameters:
25532 The expression which is evaluated into the output timebase.
25536 The value for @option{tb} is an arithmetic expression representing a
25537 rational. The expression can contain the constants "AVTB" (the default
25538 timebase), "intb" (the input timebase) and "sr" (the sample rate,
25539 audio only). Default value is "intb".
25541 @subsection Examples
25545 Set the timebase to 1/25:
25551 Set the timebase to 1/10:
25557 Set the timebase to 1001/1000:
25563 Set the timebase to 2*intb:
25569 Set the default timebase value:
25576 Convert input audio to a video output representing frequency spectrum
25577 logarithmically using Brown-Puckette constant Q transform algorithm with
25578 direct frequency domain coefficient calculation (but the transform itself
25579 is not really constant Q, instead the Q factor is actually variable/clamped),
25580 with musical tone scale, from E0 to D#10.
25582 The filter accepts the following options:
25586 Specify the video size for the output. It must be even. For the syntax of this option,
25587 check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25588 Default value is @code{1920x1080}.
25591 Set the output frame rate. Default value is @code{25}.
25594 Set the bargraph height. It must be even. Default value is @code{-1} which
25595 computes the bargraph height automatically.
25598 Set the axis height. It must be even. Default value is @code{-1} which computes
25599 the axis height automatically.
25602 Set the sonogram height. It must be even. Default value is @code{-1} which
25603 computes the sonogram height automatically.
25606 Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
25607 instead. Default value is @code{1}.
25609 @item sono_v, volume
25610 Specify the sonogram volume expression. It can contain variables:
25613 the @var{bar_v} evaluated expression
25614 @item frequency, freq, f
25615 the frequency where it is evaluated
25616 @item timeclamp, tc
25617 the value of @var{timeclamp} option
25621 @item a_weighting(f)
25622 A-weighting of equal loudness
25623 @item b_weighting(f)
25624 B-weighting of equal loudness
25625 @item c_weighting(f)
25626 C-weighting of equal loudness.
25628 Default value is @code{16}.
25630 @item bar_v, volume2
25631 Specify the bargraph volume expression. It can contain variables:
25634 the @var{sono_v} evaluated expression
25635 @item frequency, freq, f
25636 the frequency where it is evaluated
25637 @item timeclamp, tc
25638 the value of @var{timeclamp} option
25642 @item a_weighting(f)
25643 A-weighting of equal loudness
25644 @item b_weighting(f)
25645 B-weighting of equal loudness
25646 @item c_weighting(f)
25647 C-weighting of equal loudness.
25649 Default value is @code{sono_v}.
25651 @item sono_g, gamma
25652 Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
25653 higher gamma makes the spectrum having more range. Default value is @code{3}.
25654 Acceptable range is @code{[1, 7]}.
25656 @item bar_g, gamma2
25657 Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
25661 Specify the bargraph transparency level. Lower value makes the bargraph sharper.
25662 Default value is @code{1}. Acceptable range is @code{[0, 1]}.
25664 @item timeclamp, tc
25665 Specify the transform timeclamp. At low frequency, there is trade-off between
25666 accuracy in time domain and frequency domain. If timeclamp is lower,
25667 event in time domain is represented more accurately (such as fast bass drum),
25668 otherwise event in frequency domain is represented more accurately
25669 (such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}.
25672 Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it
25673 limits future samples by applying asymmetric windowing in time domain, useful
25674 when low latency is required. Accepted range is @code{[0, 1]}.
25677 Specify the transform base frequency. Default value is @code{20.01523126408007475},
25678 which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
25681 Specify the transform end frequency. Default value is @code{20495.59681441799654},
25682 which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
25685 This option is deprecated and ignored.
25688 Specify the transform length in time domain. Use this option to control accuracy
25689 trade-off between time domain and frequency domain at every frequency sample.
25690 It can contain variables:
25692 @item frequency, freq, f
25693 the frequency where it is evaluated
25694 @item timeclamp, tc
25695 the value of @var{timeclamp} option.
25697 Default value is @code{384*tc/(384+tc*f)}.
25700 Specify the transform count for every video frame. Default value is @code{6}.
25701 Acceptable range is @code{[1, 30]}.
25704 Specify the transform count for every single pixel. Default value is @code{0},
25705 which makes it computed automatically. Acceptable range is @code{[0, 10]}.
25708 Specify font file for use with freetype to draw the axis. If not specified,
25709 use embedded font. Note that drawing with font file or embedded font is not
25710 implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
25714 Specify fontconfig pattern. This has lower priority than @var{fontfile}. The
25715 @code{:} in the pattern may be replaced by @code{|} to avoid unnecessary
25719 Specify font color expression. This is arithmetic expression that should return
25720 integer value 0xRRGGBB. It can contain variables:
25722 @item frequency, freq, f
25723 the frequency where it is evaluated
25724 @item timeclamp, tc
25725 the value of @var{timeclamp} option
25730 midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
25731 @item r(x), g(x), b(x)
25732 red, green, and blue value of intensity x.
25734 Default value is @code{st(0, (midi(f)-59.5)/12);
25735 st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
25736 r(1-ld(1)) + b(ld(1))}.
25739 Specify image file to draw the axis. This option override @var{fontfile} and
25740 @var{fontcolor} option.
25743 Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
25744 the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
25745 Default value is @code{1}.
25748 Set colorspace. The accepted values are:
25751 Unspecified (default)
25760 BT.470BG or BT.601-6 625
25763 SMPTE-170M or BT.601-6 525
25769 BT.2020 with non-constant luminance
25774 Set spectrogram color scheme. This is list of floating point values with format
25775 @code{left_r|left_g|left_b|right_r|right_g|right_b}.
25776 The default is @code{1|0.5|0|0|0.5|1}.
25780 @subsection Examples
25784 Playing audio while showing the spectrum:
25786 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
25790 Same as above, but with frame rate 30 fps:
25792 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
25796 Playing at 1280x720:
25798 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
25802 Disable sonogram display:
25808 A1 and its harmonics: A1, A2, (near)E3, A3:
25810 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),
25811 asplit[a][out1]; [a] showcqt [out0]'
25815 Same as above, but with more accuracy in frequency domain:
25817 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),
25818 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
25824 bar_v=10:sono_v=bar_v*a_weighting(f)
25828 Custom gamma, now spectrum is linear to the amplitude.
25834 Custom tlength equation:
25836 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)))'
25840 Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
25842 fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
25846 Custom font using fontconfig:
25848 font='Courier New,Monospace,mono|bold'
25852 Custom frequency range with custom axis using image file:
25854 axisfile=myaxis.png:basefreq=40:endfreq=10000
25860 Convert input audio to video output representing the audio power spectrum.
25861 Audio amplitude is on Y-axis while frequency is on X-axis.
25863 The filter accepts the following options:
25867 Specify size of video. For the syntax of this option, check the
25868 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25869 Default is @code{1024x512}.
25873 This set how each frequency bin will be represented.
25875 It accepts the following values:
25881 Default is @code{bar}.
25884 Set amplitude scale.
25886 It accepts the following values:
25900 Default is @code{log}.
25903 Set frequency scale.
25905 It accepts the following values:
25914 Reverse logarithmic scale.
25916 Default is @code{lin}.
25919 Set window size. Allowed range is from 16 to 65536.
25921 Default is @code{2048}
25924 Set windowing function.
25926 It accepts the following values:
25949 Default is @code{hanning}.
25952 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
25953 which means optimal overlap for selected window function will be picked.
25956 Set time averaging. Setting this to 0 will display current maximal peaks.
25957 Default is @code{1}, which means time averaging is disabled.
25960 Specify list of colors separated by space or by '|' which will be used to
25961 draw channel frequencies. Unrecognized or missing colors will be replaced
25965 Set channel display mode.
25967 It accepts the following values:
25972 Default is @code{combined}.
25975 Set minimum amplitude used in @code{log} amplitude scaler.
25978 Set data display mode.
25980 It accepts the following values:
25986 Default is @code{magnitude}.
25989 @section showspatial
25991 Convert stereo input audio to a video output, representing the spatial relationship
25992 between two channels.
25994 The filter accepts the following options:
25998 Specify the video size for the output. For the syntax of this option, check the
25999 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
26000 Default value is @code{512x512}.
26003 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
26006 Set window function.
26008 It accepts the following values:
26033 Default value is @code{hann}.
26036 Set ratio of overlap window. Default value is @code{0.5}.
26037 When value is @code{1} overlap is set to recommended size for specific
26038 window function currently used.
26041 @anchor{showspectrum}
26042 @section showspectrum
26044 Convert input audio to a video output, representing the audio frequency
26047 The filter accepts the following options:
26051 Specify the video size for the output. For the syntax of this option, check the
26052 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
26053 Default value is @code{640x512}.
26056 Specify how the spectrum should slide along the window.
26058 It accepts the following values:
26061 the samples start again on the left when they reach the right
26063 the samples scroll from right to left
26065 frames are only produced when the samples reach the right
26067 the samples scroll from left to right
26070 Default value is @code{replace}.
26073 Specify display mode.
26075 It accepts the following values:
26078 all channels are displayed in the same row
26080 all channels are displayed in separate rows
26083 Default value is @samp{combined}.
26086 Specify display color mode.
26088 It accepts the following values:
26091 each channel is displayed in a separate color
26093 each channel is displayed using the same color scheme
26095 each channel is displayed using the rainbow color scheme
26097 each channel is displayed using the moreland color scheme
26099 each channel is displayed using the nebulae color scheme
26101 each channel is displayed using the fire color scheme
26103 each channel is displayed using the fiery color scheme
26105 each channel is displayed using the fruit color scheme
26107 each channel is displayed using the cool color scheme
26109 each channel is displayed using the magma color scheme
26111 each channel is displayed using the green color scheme
26113 each channel is displayed using the viridis color scheme
26115 each channel is displayed using the plasma color scheme
26117 each channel is displayed using the cividis color scheme
26119 each channel is displayed using the terrain color scheme
26122 Default value is @samp{channel}.
26125 Specify scale used for calculating intensity color values.
26127 It accepts the following values:
26132 square root, default
26143 Default value is @samp{sqrt}.
26146 Specify frequency scale.
26148 It accepts the following values:
26156 Default value is @samp{lin}.
26159 Set saturation modifier for displayed colors. Negative values provide
26160 alternative color scheme. @code{0} is no saturation at all.
26161 Saturation must be in [-10.0, 10.0] range.
26162 Default value is @code{1}.
26165 Set window function.
26167 It accepts the following values:
26192 Default value is @code{hann}.
26195 Set orientation of time vs frequency axis. Can be @code{vertical} or
26196 @code{horizontal}. Default is @code{vertical}.
26199 Set ratio of overlap window. Default value is @code{0}.
26200 When value is @code{1} overlap is set to recommended size for specific
26201 window function currently used.
26204 Set scale gain for calculating intensity color values.
26205 Default value is @code{1}.
26208 Set which data to display. Can be @code{magnitude}, default or @code{phase}.
26211 Set color rotation, must be in [-1.0, 1.0] range.
26212 Default value is @code{0}.
26215 Set start frequency from which to display spectrogram. Default is @code{0}.
26218 Set stop frequency to which to display spectrogram. Default is @code{0}.
26221 Set upper frame rate limit. Default is @code{auto}, unlimited.
26224 Draw time and frequency axes and legends. Default is disabled.
26227 The usage is very similar to the showwaves filter; see the examples in that
26230 @subsection Examples
26234 Large window with logarithmic color scaling:
26236 showspectrum=s=1280x480:scale=log
26240 Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
26242 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
26243 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
26247 @section showspectrumpic
26249 Convert input audio to a single video frame, representing the audio frequency
26252 The filter accepts the following options:
26256 Specify the video size for the output. For the syntax of this option, check the
26257 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
26258 Default value is @code{4096x2048}.
26261 Specify display mode.
26263 It accepts the following values:
26266 all channels are displayed in the same row
26268 all channels are displayed in separate rows
26270 Default value is @samp{combined}.
26273 Specify display color mode.
26275 It accepts the following values:
26278 each channel is displayed in a separate color
26280 each channel is displayed using the same color scheme
26282 each channel is displayed using the rainbow color scheme
26284 each channel is displayed using the moreland color scheme
26286 each channel is displayed using the nebulae color scheme
26288 each channel is displayed using the fire color scheme
26290 each channel is displayed using the fiery color scheme
26292 each channel is displayed using the fruit color scheme
26294 each channel is displayed using the cool color scheme
26296 each channel is displayed using the magma color scheme
26298 each channel is displayed using the green color scheme
26300 each channel is displayed using the viridis color scheme
26302 each channel is displayed using the plasma color scheme
26304 each channel is displayed using the cividis color scheme
26306 each channel is displayed using the terrain color scheme
26308 Default value is @samp{intensity}.
26311 Specify scale used for calculating intensity color values.
26313 It accepts the following values:
26318 square root, default
26328 Default value is @samp{log}.
26331 Specify frequency scale.
26333 It accepts the following values:
26341 Default value is @samp{lin}.
26344 Set saturation modifier for displayed colors. Negative values provide
26345 alternative color scheme. @code{0} is no saturation at all.
26346 Saturation must be in [-10.0, 10.0] range.
26347 Default value is @code{1}.
26350 Set window function.
26352 It accepts the following values:
26376 Default value is @code{hann}.
26379 Set orientation of time vs frequency axis. Can be @code{vertical} or
26380 @code{horizontal}. Default is @code{vertical}.
26383 Set scale gain for calculating intensity color values.
26384 Default value is @code{1}.
26387 Draw time and frequency axes and legends. Default is enabled.
26390 Set color rotation, must be in [-1.0, 1.0] range.
26391 Default value is @code{0}.
26394 Set start frequency from which to display spectrogram. Default is @code{0}.
26397 Set stop frequency to which to display spectrogram. Default is @code{0}.
26400 @subsection Examples
26404 Extract an audio spectrogram of a whole audio track
26405 in a 1024x1024 picture using @command{ffmpeg}:
26407 ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
26411 @section showvolume
26413 Convert input audio volume to a video output.
26415 The filter accepts the following options:
26422 Set border width, allowed range is [0, 5]. Default is 1.
26425 Set channel width, allowed range is [80, 8192]. Default is 400.
26428 Set channel height, allowed range is [1, 900]. Default is 20.
26431 Set fade, allowed range is [0, 1]. Default is 0.95.
26434 Set volume color expression.
26436 The expression can use the following variables:
26440 Current max volume of channel in dB.
26446 Current channel number, starting from 0.
26450 If set, displays channel names. Default is enabled.
26453 If set, displays volume values. Default is enabled.
26456 Set orientation, can be horizontal: @code{h} or vertical: @code{v},
26457 default is @code{h}.
26460 Set step size, allowed range is [0, 5]. Default is 0, which means
26464 Set background opacity, allowed range is [0, 1]. Default is 0.
26467 Set metering mode, can be peak: @code{p} or rms: @code{r},
26468 default is @code{p}.
26471 Set display scale, can be linear: @code{lin} or log: @code{log},
26472 default is @code{lin}.
26476 If set to > 0., display a line for the max level
26477 in the previous seconds.
26478 default is disabled: @code{0.}
26481 The color of the max line. Use when @code{dm} option is set to > 0.
26482 default is: @code{orange}
26487 Convert input audio to a video output, representing the samples waves.
26489 The filter accepts the following options:
26493 Specify the video size for the output. For the syntax of this option, check the
26494 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
26495 Default value is @code{600x240}.
26500 Available values are:
26503 Draw a point for each sample.
26506 Draw a vertical line for each sample.
26509 Draw a point for each sample and a line between them.
26512 Draw a centered vertical line for each sample.
26515 Default value is @code{point}.
26518 Set the number of samples which are printed on the same column. A
26519 larger value will decrease the frame rate. Must be a positive
26520 integer. This option can be set only if the value for @var{rate}
26521 is not explicitly specified.
26524 Set the (approximate) output frame rate. This is done by setting the
26525 option @var{n}. Default value is "25".
26527 @item split_channels
26528 Set if channels should be drawn separately or overlap. Default value is 0.
26531 Set colors separated by '|' which are going to be used for drawing of each channel.
26534 Set amplitude scale.
26536 Available values are:
26554 Set the draw mode. This is mostly useful to set for high @var{n}.
26556 Available values are:
26559 Scale pixel values for each drawn sample.
26562 Draw every sample directly.
26565 Default value is @code{scale}.
26568 @subsection Examples
26572 Output the input file audio and the corresponding video representation
26575 amovie=a.mp3,asplit[out0],showwaves[out1]
26579 Create a synthetic signal and show it with showwaves, forcing a
26580 frame rate of 30 frames per second:
26582 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
26586 @section showwavespic
26588 Convert input audio to a single video frame, representing the samples waves.
26590 The filter accepts the following options:
26594 Specify the video size for the output. For the syntax of this option, check the
26595 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
26596 Default value is @code{600x240}.
26598 @item split_channels
26599 Set if channels should be drawn separately or overlap. Default value is 0.
26602 Set colors separated by '|' which are going to be used for drawing of each channel.
26605 Set amplitude scale.
26607 Available values are:
26627 Available values are:
26630 Scale pixel values for each drawn sample.
26633 Draw every sample directly.
26636 Default value is @code{scale}.
26639 Set the filter mode.
26641 Available values are:
26644 Use average samples values for each drawn sample.
26647 Use peak samples values for each drawn sample.
26650 Default value is @code{average}.
26653 @subsection Examples
26657 Extract a channel split representation of the wave form of a whole audio track
26658 in a 1024x800 picture using @command{ffmpeg}:
26660 ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
26664 @section sidedata, asidedata
26666 Delete frame side data, or select frames based on it.
26668 This filter accepts the following options:
26672 Set mode of operation of the filter.
26674 Can be one of the following:
26678 Select every frame with side data of @code{type}.
26681 Delete side data of @code{type}. If @code{type} is not set, delete all side
26687 Set side data type used with all modes. Must be set for @code{select} mode. For
26688 the list of frame side data types, refer to the @code{AVFrameSideDataType} enum
26689 in @file{libavutil/frame.h}. For example, to choose
26690 @code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}.
26694 @section spectrumsynth
26696 Synthesize audio from 2 input video spectrums, first input stream represents
26697 magnitude across time and second represents phase across time.
26698 The filter will transform from frequency domain as displayed in videos back
26699 to time domain as presented in audio output.
26701 This filter is primarily created for reversing processed @ref{showspectrum}
26702 filter outputs, but can synthesize sound from other spectrograms too.
26703 But in such case results are going to be poor if the phase data is not
26704 available, because in such cases phase data need to be recreated, usually
26705 it's just recreated from random noise.
26706 For best results use gray only output (@code{channel} color mode in
26707 @ref{showspectrum} filter) and @code{log} scale for magnitude video and
26708 @code{lin} scale for phase video. To produce phase, for 2nd video, use
26709 @code{data} option. Inputs videos should generally use @code{fullframe}
26710 slide mode as that saves resources needed for decoding video.
26712 The filter accepts the following options:
26716 Specify sample rate of output audio, the sample rate of audio from which
26717 spectrum was generated may differ.
26720 Set number of channels represented in input video spectrums.
26723 Set scale which was used when generating magnitude input spectrum.
26724 Can be @code{lin} or @code{log}. Default is @code{log}.
26727 Set slide which was used when generating inputs spectrums.
26728 Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
26729 Default is @code{fullframe}.
26732 Set window function used for resynthesis.
26735 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
26736 which means optimal overlap for selected window function will be picked.
26739 Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
26740 Default is @code{vertical}.
26743 @subsection Examples
26747 First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
26748 then resynthesize videos back to audio with spectrumsynth:
26750 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
26751 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
26752 ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
26756 @section split, asplit
26758 Split input into several identical outputs.
26760 @code{asplit} works with audio input, @code{split} with video.
26762 The filter accepts a single parameter which specifies the number of outputs. If
26763 unspecified, it defaults to 2.
26765 @subsection Examples
26769 Create two separate outputs from the same input:
26771 [in] split [out0][out1]
26775 To create 3 or more outputs, you need to specify the number of
26778 [in] asplit=3 [out0][out1][out2]
26782 Create two separate outputs from the same input, one cropped and
26785 [in] split [splitout1][splitout2];
26786 [splitout1] crop=100:100:0:0 [cropout];
26787 [splitout2] pad=200:200:100:100 [padout];
26791 Create 5 copies of the input audio with @command{ffmpeg}:
26793 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
26799 Receive commands sent through a libzmq client, and forward them to
26800 filters in the filtergraph.
26802 @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
26803 must be inserted between two video filters, @code{azmq} between two
26804 audio filters. Both are capable to send messages to any filter type.
26806 To enable these filters you need to install the libzmq library and
26807 headers and configure FFmpeg with @code{--enable-libzmq}.
26809 For more information about libzmq see:
26810 @url{http://www.zeromq.org/}
26812 The @code{zmq} and @code{azmq} filters work as a libzmq server, which
26813 receives messages sent through a network interface defined by the
26814 @option{bind_address} (or the abbreviation "@option{b}") option.
26815 Default value of this option is @file{tcp://localhost:5555}. You may
26816 want to alter this value to your needs, but do not forget to escape any
26817 ':' signs (see @ref{filtergraph escaping}).
26819 The received message must be in the form:
26821 @var{TARGET} @var{COMMAND} [@var{ARG}]
26824 @var{TARGET} specifies the target of the command, usually the name of
26825 the filter class or a specific filter instance name. The default
26826 filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>},
26827 but you can override this by using the @samp{filter_name@@id} syntax
26828 (see @ref{Filtergraph syntax}).
26830 @var{COMMAND} specifies the name of the command for the target filter.
26832 @var{ARG} is optional and specifies the optional argument list for the
26833 given @var{COMMAND}.
26835 Upon reception, the message is processed and the corresponding command
26836 is injected into the filtergraph. Depending on the result, the filter
26837 will send a reply to the client, adopting the format:
26839 @var{ERROR_CODE} @var{ERROR_REASON}
26843 @var{MESSAGE} is optional.
26845 @subsection Examples
26847 Look at @file{tools/zmqsend} for an example of a zmq client which can
26848 be used to send commands processed by these filters.
26850 Consider the following filtergraph generated by @command{ffplay}.
26851 In this example the last overlay filter has an instance name. All other
26852 filters will have default instance names.
26855 ffplay -dumpgraph 1 -f lavfi "
26856 color=s=100x100:c=red [l];
26857 color=s=100x100:c=blue [r];
26858 nullsrc=s=200x100, zmq [bg];
26859 [bg][l] overlay [bg+l];
26860 [bg+l][r] overlay@@my=x=100 "
26863 To change the color of the left side of the video, the following
26864 command can be used:
26866 echo Parsed_color_0 c yellow | tools/zmqsend
26869 To change the right side:
26871 echo Parsed_color_1 c pink | tools/zmqsend
26874 To change the position of the right side:
26876 echo overlay@@my x 150 | tools/zmqsend
26880 @c man end MULTIMEDIA FILTERS
26882 @chapter Multimedia Sources
26883 @c man begin MULTIMEDIA SOURCES
26885 Below is a description of the currently available multimedia sources.
26889 This is the same as @ref{movie} source, except it selects an audio
26895 Read audio and/or video stream(s) from a movie container.
26897 It accepts the following parameters:
26901 The name of the resource to read (not necessarily a file; it can also be a
26902 device or a stream accessed through some protocol).
26904 @item format_name, f
26905 Specifies the format assumed for the movie to read, and can be either
26906 the name of a container or an input device. If not specified, the
26907 format is guessed from @var{movie_name} or by probing.
26909 @item seek_point, sp
26910 Specifies the seek point in seconds. The frames will be output
26911 starting from this seek point. The parameter is evaluated with
26912 @code{av_strtod}, so the numerical value may be suffixed by an IS
26913 postfix. The default value is "0".
26916 Specifies the streams to read. Several streams can be specified,
26917 separated by "+". The source will then have as many outputs, in the
26918 same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers"
26919 section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify
26920 respectively the default (best suited) video and audio stream. Default
26921 is "dv", or "da" if the filter is called as "amovie".
26923 @item stream_index, si
26924 Specifies the index of the video stream to read. If the value is -1,
26925 the most suitable video stream will be automatically selected. The default
26926 value is "-1". Deprecated. If the filter is called "amovie", it will select
26927 audio instead of video.
26930 Specifies how many times to read the stream in sequence.
26931 If the value is 0, the stream will be looped infinitely.
26932 Default value is "1".
26934 Note that when the movie is looped the source timestamps are not
26935 changed, so it will generate non monotonically increasing timestamps.
26937 @item discontinuity
26938 Specifies the time difference between frames above which the point is
26939 considered a timestamp discontinuity which is removed by adjusting the later
26943 It allows overlaying a second video on top of the main input of
26944 a filtergraph, as shown in this graph:
26946 input -----------> deltapts0 --> overlay --> output
26949 movie --> scale--> deltapts1 -------+
26951 @subsection Examples
26955 Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
26956 on top of the input labelled "in":
26958 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
26959 [in] setpts=PTS-STARTPTS [main];
26960 [main][over] overlay=16:16 [out]
26964 Read from a video4linux2 device, and overlay it on top of the input
26967 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
26968 [in] setpts=PTS-STARTPTS [main];
26969 [main][over] overlay=16:16 [out]
26973 Read the first video stream and the audio stream with id 0x81 from
26974 dvd.vob; the video is connected to the pad named "video" and the audio is
26975 connected to the pad named "audio":
26977 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
26981 @subsection Commands
26983 Both movie and amovie support the following commands:
26986 Perform seek using "av_seek_frame".
26987 The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
26990 @var{stream_index}: If stream_index is -1, a default
26991 stream is selected, and @var{timestamp} is automatically converted
26992 from AV_TIME_BASE units to the stream specific time_base.
26994 @var{timestamp}: Timestamp in AVStream.time_base units
26995 or, if no stream is specified, in AV_TIME_BASE units.
26997 @var{flags}: Flags which select direction and seeking mode.
27001 Get movie duration in AV_TIME_BASE units.
27005 @c man end MULTIMEDIA SOURCES