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, can be @var{2nd}, @var{4th} or @var{8th}.
527 Default is @var{4th}.
532 Reduce audio bit resolution.
534 This filter is bit crusher with enhanced functionality. A bit crusher
535 is used to audibly reduce number of bits an audio signal is sampled
536 with. This doesn't change the bit depth at all, it just produces the
537 effect. Material reduced in bit depth sounds more harsh and "digital".
538 This filter is able to even round to continuous values instead of discrete
540 Additionally it has a D/C offset which results in different crushing of
541 the lower and the upper half of the signal.
542 An Anti-Aliasing setting is able to produce "softer" crushing sounds.
544 Another feature of this filter is the logarithmic mode.
545 This setting switches from linear distances between bits to logarithmic ones.
546 The result is a much more "natural" sounding crusher which doesn't gate low
547 signals for example. The human ear has a logarithmic perception,
548 so this kind of crushing is much more pleasant.
549 Logarithmic crushing is also able to get anti-aliased.
551 The filter accepts the following options:
567 Can be linear: @code{lin} or logarithmic: @code{log}.
576 Set sample reduction.
579 Enable LFO. By default disabled.
590 Delay audio filtering until a given wallclock timestamp. See the @ref{cue}
594 Remove impulsive noise from input audio.
596 Samples detected as impulsive noise are replaced by interpolated samples using
597 autoregressive modelling.
601 Set window size, in milliseconds. Allowed range is from @code{10} to
602 @code{100}. Default value is @code{55} milliseconds.
603 This sets size of window which will be processed at once.
606 Set window overlap, in percentage of window size. Allowed range is from
607 @code{50} to @code{95}. Default value is @code{75} percent.
608 Setting this to a very high value increases impulsive noise removal but makes
609 whole process much slower.
612 Set autoregression order, in percentage of window size. Allowed range is from
613 @code{0} to @code{25}. Default value is @code{2} percent. This option also
614 controls quality of interpolated samples using neighbour good samples.
617 Set threshold value. Allowed range is from @code{1} to @code{100}.
618 Default value is @code{2}.
619 This controls the strength of impulsive noise which is going to be removed.
620 The lower value, the more samples will be detected as impulsive noise.
623 Set burst fusion, in percentage of window size. Allowed range is @code{0} to
624 @code{10}. Default value is @code{2}.
625 If any two samples detected as noise are spaced less than this value then any
626 sample between those two samples will be also detected as noise.
631 It accepts the following values:
634 Select overlap-add method. Even not interpolated samples are slightly
635 changed with this method.
638 Select overlap-save method. Not interpolated samples remain unchanged.
641 Default value is @code{a}.
645 Remove clipped samples from input audio.
647 Samples detected as clipped are replaced by interpolated samples using
648 autoregressive modelling.
652 Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}.
653 Default value is @code{55} milliseconds.
654 This sets size of window which will be processed at once.
657 Set window overlap, in percentage of window size. Allowed range is from @code{50}
658 to @code{95}. Default value is @code{75} percent.
661 Set autoregression order, in percentage of window size. Allowed range is from
662 @code{0} to @code{25}. Default value is @code{8} percent. This option also controls
663 quality of interpolated samples using neighbour good samples.
666 Set threshold value. Allowed range is from @code{1} to @code{100}.
667 Default value is @code{10}. Higher values make clip detection less aggressive.
670 Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}.
671 Default value is @code{1000}. Higher values make clip detection less aggressive.
676 It accepts the following values:
679 Select overlap-add method. Even not interpolated samples are slightly changed
683 Select overlap-save method. Not interpolated samples remain unchanged.
686 Default value is @code{a}.
691 Delay one or more audio channels.
693 Samples in delayed channel are filled with silence.
695 The filter accepts the following option:
699 Set list of delays in milliseconds for each channel separated by '|'.
700 Unused delays will be silently ignored. If number of given delays is
701 smaller than number of channels all remaining channels will not be delayed.
702 If you want to delay exact number of samples, append 'S' to number.
703 If you want instead to delay in seconds, append 's' to number.
706 Use last set delay for all remaining channels. By default is disabled.
707 This option if enabled changes how option @code{delays} is interpreted.
714 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
715 the second channel (and any other channels that may be present) unchanged.
721 Delay second channel by 500 samples, the third channel by 700 samples and leave
722 the first channel (and any other channels that may be present) unchanged.
728 Delay all channels by same number of samples:
730 adelay=delays=64S:all=1
734 @section aderivative, aintegral
736 Compute derivative/integral of audio stream.
738 Applying both filters one after another produces original audio.
742 Apply echoing to the input audio.
744 Echoes are reflected sound and can occur naturally amongst mountains
745 (and sometimes large buildings) when talking or shouting; digital echo
746 effects emulate this behaviour and are often used to help fill out the
747 sound of a single instrument or vocal. The time difference between the
748 original signal and the reflection is the @code{delay}, and the
749 loudness of the reflected signal is the @code{decay}.
750 Multiple echoes can have different delays and decays.
752 A description of the accepted parameters follows.
756 Set input gain of reflected signal. Default is @code{0.6}.
759 Set output gain of reflected signal. Default is @code{0.3}.
762 Set list of time intervals in milliseconds between original signal and reflections
763 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
764 Default is @code{1000}.
767 Set list of loudness of reflected signals separated by '|'.
768 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
769 Default is @code{0.5}.
776 Make it sound as if there are twice as many instruments as are actually playing:
778 aecho=0.8:0.88:60:0.4
782 If delay is very short, then it sounds like a (metallic) robot playing music:
788 A longer delay will sound like an open air concert in the mountains:
790 aecho=0.8:0.9:1000:0.3
794 Same as above but with one more mountain:
796 aecho=0.8:0.9:1000|1800:0.3|0.25
801 Audio emphasis filter creates or restores material directly taken from LPs or
802 emphased CDs with different filter curves. E.g. to store music on vinyl the
803 signal has to be altered by a filter first to even out the disadvantages of
804 this recording medium.
805 Once the material is played back the inverse filter has to be applied to
806 restore the distortion of the frequency response.
808 The filter accepts the following options:
818 Set filter mode. For restoring material use @code{reproduction} mode, otherwise
819 use @code{production} mode. Default is @code{reproduction} mode.
822 Set filter type. Selects medium. Can be one of the following:
834 select Compact Disc (CD).
840 select 50µs (FM-KF).
842 select 75µs (FM-KF).
848 Modify an audio signal according to the specified expressions.
850 This filter accepts one or more expressions (one for each channel),
851 which are evaluated and used to modify a corresponding audio signal.
853 It accepts the following parameters:
857 Set the '|'-separated expressions list for each separate channel. If
858 the number of input channels is greater than the number of
859 expressions, the last specified expression is used for the remaining
862 @item channel_layout, c
863 Set output channel layout. If not specified, the channel layout is
864 specified by the number of expressions. If set to @samp{same}, it will
865 use by default the same input channel layout.
868 Each expression in @var{exprs} can contain the following constants and functions:
872 channel number of the current expression
875 number of the evaluated sample, starting from 0
881 time of the evaluated sample expressed in seconds
884 @item nb_out_channels
885 input and output number of channels
888 the value of input channel with number @var{CH}
891 Note: this filter is slow. For faster processing you should use a
900 aeval=val(ch)/2:c=same
904 Invert phase of the second channel:
913 Apply fade-in/out effect to input audio.
915 A description of the accepted parameters follows.
919 Specify the effect type, can be either @code{in} for fade-in, or
920 @code{out} for a fade-out effect. Default is @code{in}.
922 @item start_sample, ss
923 Specify the number of the start sample for starting to apply the fade
924 effect. Default is 0.
927 Specify the number of samples for which the fade effect has to last. At
928 the end of the fade-in effect the output audio will have the same
929 volume as the input audio, at the end of the fade-out transition
930 the output audio will be silence. Default is 44100.
933 Specify the start time of the fade effect. Default is 0.
934 The value must be specified as a time duration; see
935 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
936 for the accepted syntax.
937 If set this option is used instead of @var{start_sample}.
940 Specify the duration of the fade effect. See
941 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
942 for the accepted syntax.
943 At the end of the fade-in effect the output audio will have the same
944 volume as the input audio, at the end of the fade-out transition
945 the output audio will be silence.
946 By default the duration is determined by @var{nb_samples}.
947 If set this option is used instead of @var{nb_samples}.
950 Set curve for fade transition.
952 It accepts the following values:
955 select triangular, linear slope (default)
957 select quarter of sine wave
959 select half of sine wave
961 select exponential sine wave
965 select inverted parabola
979 select inverted quarter of sine wave
981 select inverted half of sine wave
983 select double-exponential seat
985 select double-exponential sigmoid
987 select logistic sigmoid
997 Fade in first 15 seconds of audio:
1003 Fade out last 25 seconds of a 900 seconds audio:
1005 afade=t=out:st=875:d=25
1010 Denoise audio samples with FFT.
1012 A description of the accepted parameters follows.
1016 Set the noise reduction in dB, allowed range is 0.01 to 97.
1017 Default value is 12 dB.
1020 Set the noise floor in dB, allowed range is -80 to -20.
1021 Default value is -50 dB.
1026 It accepts the following values:
1035 Select shellac noise.
1038 Select custom noise, defined in @code{bn} option.
1040 Default value is white noise.
1044 Set custom band noise for every one of 15 bands.
1045 Bands are separated by ' ' or '|'.
1048 Set the residual floor in dB, allowed range is -80 to -20.
1049 Default value is -38 dB.
1052 Enable noise tracking. By default is disabled.
1053 With this enabled, noise floor is automatically adjusted.
1056 Enable residual tracking. By default is disabled.
1059 Set the output mode.
1061 It accepts the following values:
1064 Pass input unchanged.
1067 Pass noise filtered out.
1072 Default value is @var{o}.
1076 @subsection Commands
1078 This filter supports the following commands:
1080 @item sample_noise, sn
1081 Start or stop measuring noise profile.
1082 Syntax for the command is : "start" or "stop" string.
1083 After measuring noise profile is stopped it will be
1084 automatically applied in filtering.
1086 @item noise_reduction, nr
1087 Change noise reduction. Argument is single float number.
1088 Syntax for the command is : "@var{noise_reduction}"
1090 @item noise_floor, nf
1091 Change noise floor. Argument is single float number.
1092 Syntax for the command is : "@var{noise_floor}"
1094 @item output_mode, om
1095 Change output mode operation.
1096 Syntax for the command is : "i", "o" or "n" string.
1100 Apply arbitrary expressions to samples in frequency domain.
1104 Set frequency domain real expression for each separate channel separated
1105 by '|'. Default is "re".
1106 If the number of input channels is greater than the number of
1107 expressions, the last specified expression is used for the remaining
1111 Set frequency domain imaginary expression for each separate channel
1112 separated by '|'. Default is "im".
1114 Each expression in @var{real} and @var{imag} can contain the following
1115 constants and functions:
1122 current frequency bin number
1125 number of available bins
1128 channel number of the current expression
1137 current real part of frequency bin of current channel
1140 current imaginary part of frequency bin of current channel
1143 Return the value of real part of frequency bin at location (@var{bin},@var{channel})
1146 Return the value of imaginary part of frequency bin at location (@var{bin},@var{channel})
1150 Set window size. Allowed range is from 16 to 131072.
1151 Default is @code{4096}
1154 Set window function. Default is @code{hann}.
1157 Set window overlap. If set to 1, the recommended overlap for selected
1158 window function will be picked. Default is @code{0.75}.
1161 @subsection Examples
1165 Leave almost only low frequencies in audio:
1167 afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"
1171 Apply robotize effect:
1173 afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75"
1177 Apply whisper effect:
1179 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"
1186 Apply an arbitrary Finite Impulse Response filter.
1188 This filter is designed for applying long FIR filters,
1189 up to 60 seconds long.
1191 It can be used as component for digital crossover filters,
1192 room equalization, cross talk cancellation, wavefield synthesis,
1193 auralization, ambiophonics, ambisonics and spatialization.
1195 This filter uses the streams higher than first one as FIR coefficients.
1196 If the non-first stream holds a single channel, it will be used
1197 for all input channels in the first stream, otherwise
1198 the number of channels in the non-first stream must be same as
1199 the number of channels in the first stream.
1201 It accepts the following parameters:
1205 Set dry gain. This sets input gain.
1208 Set wet gain. This sets final output gain.
1211 Set Impulse Response filter length. Default is 1, which means whole IR is processed.
1214 Enable applying gain measured from power of IR.
1216 Set which approach to use for auto gain measurement.
1220 Do not apply any gain.
1223 select peak gain, very conservative approach. This is default value.
1226 select DC gain, limited application.
1229 select gain to noise approach, this is most popular one.
1233 Set gain to be applied to IR coefficients before filtering.
1234 Allowed range is 0 to 1. This gain is applied after any gain applied with @var{gtype} option.
1237 Set format of IR stream. Can be @code{mono} or @code{input}.
1238 Default is @code{input}.
1241 Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds.
1242 Allowed range is 0.1 to 60 seconds.
1245 Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
1246 By default it is disabled.
1249 Set for which IR channel to display frequency response. By default is first channel
1250 displayed. This option is used only when @var{response} is enabled.
1253 Set video stream size. This option is used only when @var{response} is enabled.
1256 Set video stream frame rate. This option is used only when @var{response} is enabled.
1259 Set minimal partition size used for convolution. Default is @var{8192}.
1260 Allowed range is from @var{1} to @var{32768}.
1261 Lower values decreases latency at cost of higher CPU usage.
1264 Set maximal partition size used for convolution. Default is @var{8192}.
1265 Allowed range is from @var{8} to @var{32768}.
1266 Lower values may increase CPU usage.
1269 Set number of input impulse responses streams which will be switchable at runtime.
1270 Allowed range is from @var{1} to @var{32}. Default is @var{1}.
1273 Set IR stream which will be used for convolution, starting from @var{0}, should always be
1274 lower than supplied value by @code{nbirs} option. Default is @var{0}.
1275 This option can be changed at runtime via @ref{commands}.
1278 @subsection Examples
1282 Apply reverb to stream using mono IR file as second input, complete command using ffmpeg:
1284 ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
1291 Set output format constraints for the input audio. The framework will
1292 negotiate the most appropriate format to minimize conversions.
1294 It accepts the following parameters:
1297 @item sample_fmts, f
1298 A '|'-separated list of requested sample formats.
1300 @item sample_rates, r
1301 A '|'-separated list of requested sample rates.
1303 @item channel_layouts, cl
1304 A '|'-separated list of requested channel layouts.
1306 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1307 for the required syntax.
1310 If a parameter is omitted, all values are allowed.
1312 Force the output to either unsigned 8-bit or signed 16-bit stereo
1314 aformat=sample_fmts=u8|s16:channel_layouts=stereo
1319 A gate is mainly used to reduce lower parts of a signal. This kind of signal
1320 processing reduces disturbing noise between useful signals.
1322 Gating is done by detecting the volume below a chosen level @var{threshold}
1323 and dividing it by the factor set with @var{ratio}. The bottom of the noise
1324 floor is set via @var{range}. Because an exact manipulation of the signal
1325 would cause distortion of the waveform the reduction can be levelled over
1326 time. This is done by setting @var{attack} and @var{release}.
1328 @var{attack} determines how long the signal has to fall below the threshold
1329 before any reduction will occur and @var{release} sets the time the signal
1330 has to rise above the threshold to reduce the reduction again.
1331 Shorter signals than the chosen attack time will be left untouched.
1335 Set input level before filtering.
1336 Default is 1. Allowed range is from 0.015625 to 64.
1339 Set the mode of operation. Can be @code{upward} or @code{downward}.
1340 Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
1341 will be amplified, expanding dynamic range in upward direction.
1342 Otherwise, in case of @code{downward} lower parts of signal will be reduced.
1345 Set the level of gain reduction when the signal is below the threshold.
1346 Default is 0.06125. Allowed range is from 0 to 1.
1347 Setting this to 0 disables reduction and then filter behaves like expander.
1350 If a signal rises above this level the gain reduction is released.
1351 Default is 0.125. Allowed range is from 0 to 1.
1354 Set a ratio by which the signal is reduced.
1355 Default is 2. Allowed range is from 1 to 9000.
1358 Amount of milliseconds the signal has to rise above the threshold before gain
1360 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
1363 Amount of milliseconds the signal has to fall below the threshold before the
1364 reduction is increased again. Default is 250 milliseconds.
1365 Allowed range is from 0.01 to 9000.
1368 Set amount of amplification of signal after processing.
1369 Default is 1. Allowed range is from 1 to 64.
1372 Curve the sharp knee around the threshold to enter gain reduction more softly.
1373 Default is 2.828427125. Allowed range is from 1 to 8.
1376 Choose if exact signal should be taken for detection or an RMS like one.
1377 Default is @code{rms}. Can be @code{peak} or @code{rms}.
1380 Choose if the average level between all channels or the louder channel affects
1382 Default is @code{average}. Can be @code{average} or @code{maximum}.
1387 Apply an arbitrary Infinite Impulse Response filter.
1389 It accepts the following parameters:
1393 Set numerator/zeros coefficients.
1396 Set denominator/poles coefficients.
1408 Set coefficients format.
1414 Z-plane zeros/poles, cartesian (default)
1416 Z-plane zeros/poles, polar radians
1418 Z-plane zeros/poles, polar degrees
1422 Set kind of processing.
1423 Can be @code{d} - direct or @code{s} - serial cascading. Default is @code{s}.
1426 Set filtering precision.
1430 double-precision floating-point (default)
1432 single-precision floating-point
1440 How much to use filtered signal in output. Default is 1.
1441 Range is between 0 and 1.
1444 Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
1445 By default it is disabled.
1448 Set for which IR channel to display frequency response. By default is first channel
1449 displayed. This option is used only when @var{response} is enabled.
1452 Set video stream size. This option is used only when @var{response} is enabled.
1455 Coefficients in @code{tf} format are separated by spaces and are in ascending
1458 Coefficients in @code{zp} format are separated by spaces and order of coefficients
1459 doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i}
1462 Different coefficients and gains can be provided for every channel, in such case
1463 use '|' to separate coefficients or gains. Last provided coefficients will be
1464 used for all remaining channels.
1466 @subsection Examples
1470 Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate:
1472 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
1476 Same as above but in @code{zp} format:
1478 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
1484 The limiter prevents an input signal from rising over a desired threshold.
1485 This limiter uses lookahead technology to prevent your signal from distorting.
1486 It means that there is a small delay after the signal is processed. Keep in mind
1487 that the delay it produces is the attack time you set.
1489 The filter accepts the following options:
1493 Set input gain. Default is 1.
1496 Set output gain. Default is 1.
1499 Don't let signals above this level pass the limiter. Default is 1.
1502 The limiter will reach its attenuation level in this amount of time in
1503 milliseconds. Default is 5 milliseconds.
1506 Come back from limiting to attenuation 1.0 in this amount of milliseconds.
1507 Default is 50 milliseconds.
1510 When gain reduction is always needed ASC takes care of releasing to an
1511 average reduction level rather than reaching a reduction of 0 in the release
1515 Select how much the release time is affected by ASC, 0 means nearly no changes
1516 in release time while 1 produces higher release times.
1519 Auto level output signal. Default is enabled.
1520 This normalizes audio back to 0dB if enabled.
1523 Depending on picked setting it is recommended to upsample input 2x or 4x times
1524 with @ref{aresample} before applying this filter.
1528 Apply a two-pole all-pass filter with central frequency (in Hz)
1529 @var{frequency}, and filter-width @var{width}.
1530 An all-pass filter changes the audio's frequency to phase relationship
1531 without changing its frequency to amplitude relationship.
1533 The filter accepts the following options:
1537 Set frequency in Hz.
1540 Set method to specify band-width of filter.
1555 Specify the band-width of a filter in width_type units.
1558 How much to use filtered signal in output. Default is 1.
1559 Range is between 0 and 1.
1562 Specify which channels to filter, by default all available are filtered.
1565 Normalize biquad coefficients, by default is disabled.
1566 Enabling it will normalize magnitude response at DC to 0dB.
1569 @subsection Commands
1571 This filter supports the following commands:
1574 Change allpass frequency.
1575 Syntax for the command is : "@var{frequency}"
1578 Change allpass width_type.
1579 Syntax for the command is : "@var{width_type}"
1582 Change allpass width.
1583 Syntax for the command is : "@var{width}"
1587 Syntax for the command is : "@var{mix}"
1594 The filter accepts the following options:
1598 Set the number of loops. Setting this value to -1 will result in infinite loops.
1602 Set maximal number of samples. Default is 0.
1605 Set first sample of loop. Default is 0.
1611 Merge two or more audio streams into a single multi-channel stream.
1613 The filter accepts the following options:
1618 Set the number of inputs. Default is 2.
1622 If the channel layouts of the inputs are disjoint, and therefore compatible,
1623 the channel layout of the output will be set accordingly and the channels
1624 will be reordered as necessary. If the channel layouts of the inputs are not
1625 disjoint, the output will have all the channels of the first input then all
1626 the channels of the second input, in that order, and the channel layout of
1627 the output will be the default value corresponding to the total number of
1630 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
1631 is FC+BL+BR, then the output will be in 5.1, with the channels in the
1632 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
1633 first input, b1 is the first channel of the second input).
1635 On the other hand, if both input are in stereo, the output channels will be
1636 in the default order: a1, a2, b1, b2, and the channel layout will be
1637 arbitrarily set to 4.0, which may or may not be the expected value.
1639 All inputs must have the same sample rate, and format.
1641 If inputs do not have the same duration, the output will stop with the
1644 @subsection Examples
1648 Merge two mono files into a stereo stream:
1650 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
1654 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
1656 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
1662 Mixes multiple audio inputs into a single output.
1664 Note that this filter only supports float samples (the @var{amerge}
1665 and @var{pan} audio filters support many formats). If the @var{amix}
1666 input has integer samples then @ref{aresample} will be automatically
1667 inserted to perform the conversion to float samples.
1671 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
1673 will mix 3 input audio streams to a single output with the same duration as the
1674 first input and a dropout transition time of 3 seconds.
1676 It accepts the following parameters:
1680 The number of inputs. If unspecified, it defaults to 2.
1683 How to determine the end-of-stream.
1687 The duration of the longest input. (default)
1690 The duration of the shortest input.
1693 The duration of the first input.
1697 @item dropout_transition
1698 The transition time, in seconds, for volume renormalization when an input
1699 stream ends. The default value is 2 seconds.
1702 Specify weight of each input audio stream as sequence.
1703 Each weight is separated by space. By default all inputs have same weight.
1708 Multiply first audio stream with second audio stream and store result
1709 in output audio stream. Multiplication is done by multiplying each
1710 sample from first stream with sample at same position from second stream.
1712 With this element-wise multiplication one can create amplitude fades and
1713 amplitude modulations.
1715 @section anequalizer
1717 High-order parametric multiband equalizer for each channel.
1719 It accepts the following parameters:
1723 This option string is in format:
1724 "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
1725 Each equalizer band is separated by '|'.
1729 Set channel number to which equalization will be applied.
1730 If input doesn't have that channel the entry is ignored.
1733 Set central frequency for band.
1734 If input doesn't have that frequency the entry is ignored.
1737 Set band width in hertz.
1740 Set band gain in dB.
1743 Set filter type for band, optional, can be:
1747 Butterworth, this is default.
1758 With this option activated frequency response of anequalizer is displayed
1762 Set video stream size. Only useful if curves option is activated.
1765 Set max gain that will be displayed. Only useful if curves option is activated.
1766 Setting this to a reasonable value makes it possible to display gain which is derived from
1767 neighbour bands which are too close to each other and thus produce higher gain
1768 when both are activated.
1771 Set frequency scale used to draw frequency response in video output.
1772 Can be linear or logarithmic. Default is logarithmic.
1775 Set color for each channel curve which is going to be displayed in video stream.
1776 This is list of color names separated by space or by '|'.
1777 Unrecognised or missing colors will be replaced by white color.
1780 @subsection Examples
1784 Lower gain by 10 of central frequency 200Hz and width 100 Hz
1785 for first 2 channels using Chebyshev type 1 filter:
1787 anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
1791 @subsection Commands
1793 This filter supports the following commands:
1796 Alter existing filter parameters.
1797 Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
1799 @var{fN} is existing filter number, starting from 0, if no such filter is available
1801 @var{freq} set new frequency parameter.
1802 @var{width} set new width parameter in herz.
1803 @var{gain} set new gain parameter in dB.
1805 Full filter invocation with asendcmd may look like this:
1806 asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
1811 Reduce broadband noise in audio samples using Non-Local Means algorithm.
1813 Each sample is adjusted by looking for other samples with similar contexts. This
1814 context similarity is defined by comparing their surrounding patches of size
1815 @option{p}. Patches are searched in an area of @option{r} around the sample.
1817 The filter accepts the following options:
1821 Set denoising strength. Allowed range is from 0.00001 to 10. Default value is 0.00001.
1824 Set patch radius duration. Allowed range is from 1 to 100 milliseconds.
1825 Default value is 2 milliseconds.
1828 Set research radius duration. Allowed range is from 2 to 300 milliseconds.
1829 Default value is 6 milliseconds.
1832 Set the output mode.
1834 It accepts the following values:
1837 Pass input unchanged.
1840 Pass noise filtered out.
1845 Default value is @var{o}.
1849 Set smooth factor. Default value is @var{11}. Allowed range is from @var{1} to @var{15}.
1852 @subsection Commands
1854 This filter supports the following commands:
1857 Change denoise strength. Argument is single float number.
1858 Syntax for the command is : "@var{s}"
1862 Syntax for the command is : "i", "o" or "n" string.
1866 Apply Normalized Least-Mean-Squares algorithm to the first audio stream using the second audio stream.
1868 This adaptive filter is used to mimic a desired filter by finding the filter coefficients that
1869 relate to producing the least mean square of the error signal (difference between the desired,
1870 2nd input audio stream and the actual signal, the 1st input audio stream).
1872 A description of the accepted options follows.
1885 Set the filter leakage.
1888 It accepts the following values:
1897 Pass filtered samples.
1900 Pass difference between desired and filtered samples.
1902 Default value is @var{o}.
1906 @subsection Examples
1910 One of many usages of this filter is noise reduction, input audio is filtered
1911 with same samples that are delayed by fixed amount, one such example for stereo audio is:
1913 asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o
1917 @subsection Commands
1919 This filter supports the same commands as options, excluding option @code{order}.
1923 Pass the audio source unchanged to the output.
1927 Pad the end of an audio stream with silence.
1929 This can be used together with @command{ffmpeg} @option{-shortest} to
1930 extend audio streams to the same length as the video stream.
1932 A description of the accepted options follows.
1936 Set silence packet size. Default value is 4096.
1939 Set the number of samples of silence to add to the end. After the
1940 value is reached, the stream is terminated. This option is mutually
1941 exclusive with @option{whole_len}.
1944 Set the minimum total number of samples in the output audio stream. If
1945 the value is longer than the input audio length, silence is added to
1946 the end, until the value is reached. This option is mutually exclusive
1947 with @option{pad_len}.
1950 Specify the duration of samples of silence to add. See
1951 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1952 for the accepted syntax. Used only if set to non-zero value.
1955 Specify the minimum total duration in the output audio stream. See
1956 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1957 for the accepted syntax. Used only if set to non-zero value. If the value is longer than
1958 the input audio length, silence is added to the end, until the value is reached.
1959 This option is mutually exclusive with @option{pad_dur}
1962 If neither the @option{pad_len} nor the @option{whole_len} nor @option{pad_dur}
1963 nor @option{whole_dur} option is set, the filter will add silence to the end of
1964 the input stream indefinitely.
1966 @subsection Examples
1970 Add 1024 samples of silence to the end of the input:
1976 Make sure the audio output will contain at least 10000 samples, pad
1977 the input with silence if required:
1979 apad=whole_len=10000
1983 Use @command{ffmpeg} to pad the audio input with silence, so that the
1984 video stream will always result the shortest and will be converted
1985 until the end in the output file when using the @option{shortest}
1988 ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
1993 Add a phasing effect to the input audio.
1995 A phaser filter creates series of peaks and troughs in the frequency spectrum.
1996 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
1998 A description of the accepted parameters follows.
2002 Set input gain. Default is 0.4.
2005 Set output gain. Default is 0.74
2008 Set delay in milliseconds. Default is 3.0.
2011 Set decay. Default is 0.4.
2014 Set modulation speed in Hz. Default is 0.5.
2017 Set modulation type. Default is triangular.
2019 It accepts the following values:
2028 Audio pulsator is something between an autopanner and a tremolo.
2029 But it can produce funny stereo effects as well. Pulsator changes the volume
2030 of the left and right channel based on a LFO (low frequency oscillator) with
2031 different waveforms and shifted phases.
2032 This filter have the ability to define an offset between left and right
2033 channel. An offset of 0 means that both LFO shapes match each other.
2034 The left and right channel are altered equally - a conventional tremolo.
2035 An offset of 50% means that the shape of the right channel is exactly shifted
2036 in phase (or moved backwards about half of the frequency) - pulsator acts as
2037 an autopanner. At 1 both curves match again. Every setting in between moves the
2038 phase shift gapless between all stages and produces some "bypassing" sounds with
2039 sine and triangle waveforms. The more you set the offset near 1 (starting from
2040 the 0.5) the faster the signal passes from the left to the right speaker.
2042 The filter accepts the following options:
2046 Set input gain. By default it is 1. Range is [0.015625 - 64].
2049 Set output gain. By default it is 1. Range is [0.015625 - 64].
2052 Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
2053 sawup or sawdown. Default is sine.
2056 Set modulation. Define how much of original signal is affected by the LFO.
2059 Set left channel offset. Default is 0. Allowed range is [0 - 1].
2062 Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
2065 Set pulse width. Default is 1. Allowed range is [0 - 2].
2068 Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
2071 Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
2075 Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
2079 Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
2080 if timing is set to hz.
2086 Resample the input audio to the specified parameters, using the
2087 libswresample library. If none are specified then the filter will
2088 automatically convert between its input and output.
2090 This filter is also able to stretch/squeeze the audio data to make it match
2091 the timestamps or to inject silence / cut out audio to make it match the
2092 timestamps, do a combination of both or do neither.
2094 The filter accepts the syntax
2095 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
2096 expresses a sample rate and @var{resampler_options} is a list of
2097 @var{key}=@var{value} pairs, separated by ":". See the
2098 @ref{Resampler Options,,"Resampler Options" section in the
2099 ffmpeg-resampler(1) manual,ffmpeg-resampler}
2100 for the complete list of supported options.
2102 @subsection Examples
2106 Resample the input audio to 44100Hz:
2112 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
2113 samples per second compensation:
2115 aresample=async=1000
2121 Reverse an audio clip.
2123 Warning: This filter requires memory to buffer the entire clip, so trimming
2126 @subsection Examples
2130 Take the first 5 seconds of a clip, and reverse it.
2132 atrim=end=5,areverse
2138 Reduce noise from speech using Recurrent Neural Networks.
2140 This filter accepts the following options:
2144 Set train model file to load. This option is always required.
2147 @section asetnsamples
2149 Set the number of samples per each output audio frame.
2151 The last output packet may contain a different number of samples, as
2152 the filter will flush all the remaining samples when the input audio
2155 The filter accepts the following options:
2159 @item nb_out_samples, n
2160 Set the number of frames per each output audio frame. The number is
2161 intended as the number of samples @emph{per each channel}.
2162 Default value is 1024.
2165 If set to 1, the filter will pad the last audio frame with zeroes, so
2166 that the last frame will contain the same number of samples as the
2167 previous ones. Default value is 1.
2170 For example, to set the number of per-frame samples to 1234 and
2171 disable padding for the last frame, use:
2173 asetnsamples=n=1234:p=0
2178 Set the sample rate without altering the PCM data.
2179 This will result in a change of speed and pitch.
2181 The filter accepts the following options:
2184 @item sample_rate, r
2185 Set the output sample rate. Default is 44100 Hz.
2190 Show a line containing various information for each input audio frame.
2191 The input audio is not modified.
2193 The shown line contains a sequence of key/value pairs of the form
2194 @var{key}:@var{value}.
2196 The following values are shown in the output:
2200 The (sequential) number of the input frame, starting from 0.
2203 The presentation timestamp of the input frame, in time base units; the time base
2204 depends on the filter input pad, and is usually 1/@var{sample_rate}.
2207 The presentation timestamp of the input frame in seconds.
2210 position of the frame in the input stream, -1 if this information in
2211 unavailable and/or meaningless (for example in case of synthetic audio)
2220 The sample rate for the audio frame.
2223 The number of samples (per channel) in the frame.
2226 The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
2227 audio, the data is treated as if all the planes were concatenated.
2229 @item plane_checksums
2230 A list of Adler-32 checksums for each data plane.
2234 Apply audio soft clipping.
2236 Soft clipping is a type of distortion effect where the amplitude of a signal is saturated
2237 along a smooth curve, rather than the abrupt shape of hard-clipping.
2239 This filter accepts the following options:
2243 Set type of soft-clipping.
2245 It accepts the following values:
2257 Set additional parameter which controls sigmoid function.
2260 @subsection Commands
2262 This filter supports the all above options as @ref{commands}.
2265 Automatic Speech Recognition
2267 This filter uses PocketSphinx for speech recognition. To enable
2268 compilation of this filter, you need to configure FFmpeg with
2269 @code{--enable-pocketsphinx}.
2271 It accepts the following options:
2275 Set sampling rate of input audio. Defaults is @code{16000}.
2276 This need to match speech models, otherwise one will get poor results.
2279 Set dictionary containing acoustic model files.
2282 Set pronunciation dictionary.
2285 Set language model file.
2288 Set language model set.
2291 Set which language model to use.
2294 Set output for log messages.
2297 The filter exports recognized speech as the frame metadata @code{lavfi.asr.text}.
2302 Display time domain statistical information about the audio channels.
2303 Statistics are calculated and displayed for each audio channel and,
2304 where applicable, an overall figure is also given.
2306 It accepts the following option:
2309 Short window length in seconds, used for peak and trough RMS measurement.
2310 Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}.
2314 Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
2315 where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
2318 Available keys for each channel are:
2360 For example full key look like this @code{lavfi.astats.1.DC_offset} or
2361 this @code{lavfi.astats.Overall.Peak_count}.
2363 For description what each key means read below.
2366 Set number of frame after which stats are going to be recalculated.
2367 Default is disabled.
2369 @item measure_perchannel
2370 Select the entries which need to be measured per channel. The metadata keys can
2371 be used as flags, default is @option{all} which measures everything.
2372 @option{none} disables all per channel measurement.
2374 @item measure_overall
2375 Select the entries which need to be measured overall. The metadata keys can
2376 be used as flags, default is @option{all} which measures everything.
2377 @option{none} disables all overall measurement.
2381 A description of each shown parameter follows:
2385 Mean amplitude displacement from zero.
2388 Minimal sample level.
2391 Maximal sample level.
2393 @item Min difference
2394 Minimal difference between two consecutive samples.
2396 @item Max difference
2397 Maximal difference between two consecutive samples.
2399 @item Mean difference
2400 Mean difference between two consecutive samples.
2401 The average of each difference between two consecutive samples.
2403 @item RMS difference
2404 Root Mean Square difference between two consecutive samples.
2408 Standard peak and RMS level measured in dBFS.
2412 Peak and trough values for RMS level measured over a short window.
2415 Standard ratio of peak to RMS level (note: not in dB).
2418 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
2419 (i.e. either @var{Min level} or @var{Max level}).
2422 Number of occasions (not the number of samples) that the signal attained either
2423 @var{Min level} or @var{Max level}.
2426 Overall bit depth of audio. Number of bits used for each sample.
2429 Measured dynamic range of audio in dB.
2431 @item Zero crossings
2432 Number of points where the waveform crosses the zero level axis.
2434 @item Zero crossings rate
2435 Rate of Zero crossings and number of audio samples.
2442 The filter accepts exactly one parameter, the audio tempo. If not
2443 specified then the filter will assume nominal 1.0 tempo. Tempo must
2444 be in the [0.5, 100.0] range.
2446 Note that tempo greater than 2 will skip some samples rather than
2447 blend them in. If for any reason this is a concern it is always
2448 possible to daisy-chain several instances of atempo to achieve the
2449 desired product tempo.
2451 @subsection Examples
2455 Slow down audio to 80% tempo:
2461 To speed up audio to 300% tempo:
2467 To speed up audio to 300% tempo by daisy-chaining two atempo instances:
2469 atempo=sqrt(3),atempo=sqrt(3)
2473 @subsection Commands
2475 This filter supports the following commands:
2478 Change filter tempo scale factor.
2479 Syntax for the command is : "@var{tempo}"
2484 Trim the input so that the output contains one continuous subpart of the input.
2486 It accepts the following parameters:
2489 Timestamp (in seconds) of the start of the section to keep. I.e. the audio
2490 sample with the timestamp @var{start} will be the first sample in the output.
2493 Specify time of the first audio sample that will be dropped, i.e. the
2494 audio sample immediately preceding the one with the timestamp @var{end} will be
2495 the last sample in the output.
2498 Same as @var{start}, except this option sets the start timestamp in samples
2502 Same as @var{end}, except this option sets the end timestamp in samples instead
2506 The maximum duration of the output in seconds.
2509 The number of the first sample that should be output.
2512 The number of the first sample that should be dropped.
2515 @option{start}, @option{end}, and @option{duration} are expressed as time
2516 duration specifications; see
2517 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
2519 Note that the first two sets of the start/end options and the @option{duration}
2520 option look at the frame timestamp, while the _sample options simply count the
2521 samples that pass through the filter. So start/end_pts and start/end_sample will
2522 give different results when the timestamps are wrong, inexact or do not start at
2523 zero. Also note that this filter does not modify the timestamps. If you wish
2524 to have the output timestamps start at zero, insert the asetpts filter after the
2527 If multiple start or end options are set, this filter tries to be greedy and
2528 keep all samples that match at least one of the specified constraints. To keep
2529 only the part that matches all the constraints at once, chain multiple atrim
2532 The defaults are such that all the input is kept. So it is possible to set e.g.
2533 just the end values to keep everything before the specified time.
2538 Drop everything except the second minute of input:
2540 ffmpeg -i INPUT -af atrim=60:120
2544 Keep only the first 1000 samples:
2546 ffmpeg -i INPUT -af atrim=end_sample=1000
2551 @section axcorrelate
2552 Calculate normalized cross-correlation between two input audio streams.
2554 Resulted samples are always between -1 and 1 inclusive.
2555 If result is 1 it means two input samples are highly correlated in that selected segment.
2556 Result 0 means they are not correlated at all.
2557 If result is -1 it means two input samples are out of phase, which means they cancel each
2560 The filter accepts the following options:
2564 Set size of segment over which cross-correlation is calculated.
2565 Default is 256. Allowed range is from 2 to 131072.
2568 Set algorithm for cross-correlation. Can be @code{slow} or @code{fast}.
2569 Default is @code{slow}. Fast algorithm assumes mean values over any given segment
2570 are always zero and thus need much less calculations to make.
2571 This is generally not true, but is valid for typical audio streams.
2574 @subsection Examples
2578 Calculate correlation between channels in stereo audio stream:
2580 ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav
2586 Apply a two-pole Butterworth band-pass filter with central
2587 frequency @var{frequency}, and (3dB-point) band-width width.
2588 The @var{csg} option selects a constant skirt gain (peak gain = Q)
2589 instead of the default: constant 0dB peak gain.
2590 The filter roll off at 6dB per octave (20dB per decade).
2592 The filter accepts the following options:
2596 Set the filter's central frequency. Default is @code{3000}.
2599 Constant skirt gain if set to 1. Defaults to 0.
2602 Set method to specify band-width of filter.
2617 Specify the band-width of a filter in width_type units.
2620 How much to use filtered signal in output. Default is 1.
2621 Range is between 0 and 1.
2624 Specify which channels to filter, by default all available are filtered.
2627 Normalize biquad coefficients, by default is disabled.
2628 Enabling it will normalize magnitude response at DC to 0dB.
2631 @subsection Commands
2633 This filter supports the following commands:
2636 Change bandpass frequency.
2637 Syntax for the command is : "@var{frequency}"
2640 Change bandpass width_type.
2641 Syntax for the command is : "@var{width_type}"
2644 Change bandpass width.
2645 Syntax for the command is : "@var{width}"
2648 Change bandpass mix.
2649 Syntax for the command is : "@var{mix}"
2654 Apply a two-pole Butterworth band-reject filter with central
2655 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
2656 The filter roll off at 6dB per octave (20dB per decade).
2658 The filter accepts the following options:
2662 Set the filter's central frequency. Default is @code{3000}.
2665 Set method to specify band-width of filter.
2680 Specify the band-width of a filter in width_type units.
2683 How much to use filtered signal in output. Default is 1.
2684 Range is between 0 and 1.
2687 Specify which channels to filter, by default all available are filtered.
2690 Normalize biquad coefficients, by default is disabled.
2691 Enabling it will normalize magnitude response at DC to 0dB.
2694 @subsection Commands
2696 This filter supports the following commands:
2699 Change bandreject frequency.
2700 Syntax for the command is : "@var{frequency}"
2703 Change bandreject width_type.
2704 Syntax for the command is : "@var{width_type}"
2707 Change bandreject width.
2708 Syntax for the command is : "@var{width}"
2711 Change bandreject mix.
2712 Syntax for the command is : "@var{mix}"
2715 @section bass, lowshelf
2717 Boost or cut the bass (lower) frequencies of the audio using a two-pole
2718 shelving filter with a response similar to that of a standard
2719 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
2721 The filter accepts the following options:
2725 Give the gain at 0 Hz. Its useful range is about -20
2726 (for a large cut) to +20 (for a large boost).
2727 Beware of clipping when using a positive gain.
2730 Set the filter's central frequency and so can be used
2731 to extend or reduce the frequency range to be boosted or cut.
2732 The default value is @code{100} Hz.
2735 Set method to specify band-width of filter.
2750 Determine how steep is the filter's shelf transition.
2753 How much to use filtered signal in output. Default is 1.
2754 Range is between 0 and 1.
2757 Specify which channels to filter, by default all available are filtered.
2760 Normalize biquad coefficients, by default is disabled.
2761 Enabling it will normalize magnitude response at DC to 0dB.
2764 @subsection Commands
2766 This filter supports the following commands:
2769 Change bass frequency.
2770 Syntax for the command is : "@var{frequency}"
2773 Change bass width_type.
2774 Syntax for the command is : "@var{width_type}"
2778 Syntax for the command is : "@var{width}"
2782 Syntax for the command is : "@var{gain}"
2786 Syntax for the command is : "@var{mix}"
2791 Apply a biquad IIR filter with the given coefficients.
2792 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
2793 are the numerator and denominator coefficients respectively.
2794 and @var{channels}, @var{c} specify which channels to filter, by default all
2795 available are filtered.
2797 @subsection Commands
2799 This filter supports the following commands:
2807 Change biquad parameter.
2808 Syntax for the command is : "@var{value}"
2811 How much to use filtered signal in output. Default is 1.
2812 Range is between 0 and 1.
2815 Specify which channels to filter, by default all available are filtered.
2818 Normalize biquad coefficients, by default is disabled.
2819 Enabling it will normalize magnitude response at DC to 0dB.
2823 Bauer stereo to binaural transformation, which improves headphone listening of
2824 stereo audio records.
2826 To enable compilation of this filter you need to configure FFmpeg with
2827 @code{--enable-libbs2b}.
2829 It accepts the following parameters:
2833 Pre-defined crossfeed level.
2837 Default level (fcut=700, feed=50).
2840 Chu Moy circuit (fcut=700, feed=60).
2843 Jan Meier circuit (fcut=650, feed=95).
2848 Cut frequency (in Hz).
2857 Remap input channels to new locations.
2859 It accepts the following parameters:
2862 Map channels from input to output. The argument is a '|'-separated list of
2863 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
2864 @var{in_channel} form. @var{in_channel} can be either the name of the input
2865 channel (e.g. FL for front left) or its index in the input channel layout.
2866 @var{out_channel} is the name of the output channel or its index in the output
2867 channel layout. If @var{out_channel} is not given then it is implicitly an
2868 index, starting with zero and increasing by one for each mapping.
2870 @item channel_layout
2871 The channel layout of the output stream.
2874 If no mapping is present, the filter will implicitly map input channels to
2875 output channels, preserving indices.
2877 @subsection Examples
2881 For example, assuming a 5.1+downmix input MOV file,
2883 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
2885 will create an output WAV file tagged as stereo from the downmix channels of
2889 To fix a 5.1 WAV improperly encoded in AAC's native channel order
2891 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
2895 @section channelsplit
2897 Split each channel from an input audio stream into a separate output stream.
2899 It accepts the following parameters:
2901 @item channel_layout
2902 The channel layout of the input stream. The default is "stereo".
2904 A channel layout describing the channels to be extracted as separate output streams
2905 or "all" to extract each input channel as a separate stream. The default is "all".
2907 Choosing channels not present in channel layout in the input will result in an error.
2910 @subsection Examples
2914 For example, assuming a stereo input MP3 file,
2916 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
2918 will create an output Matroska file with two audio streams, one containing only
2919 the left channel and the other the right channel.
2922 Split a 5.1 WAV file into per-channel files:
2924 ffmpeg -i in.wav -filter_complex
2925 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
2926 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
2927 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
2932 Extract only LFE from a 5.1 WAV file:
2934 ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
2935 -map '[LFE]' lfe.wav
2940 Add a chorus effect to the audio.
2942 Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
2944 Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
2945 constant, with chorus, it is varied using using sinusoidal or triangular modulation.
2946 The modulation depth defines the range the modulated delay is played before or after
2947 the delay. Hence the delayed sound will sound slower or faster, that is the delayed
2948 sound tuned around the original one, like in a chorus where some vocals are slightly
2951 It accepts the following parameters:
2954 Set input gain. Default is 0.4.
2957 Set output gain. Default is 0.4.
2960 Set delays. A typical delay is around 40ms to 60ms.
2972 @subsection Examples
2978 chorus=0.7:0.9:55:0.4:0.25:2
2984 chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
2988 Fuller sounding chorus with three delays:
2990 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
2995 Compress or expand the audio's dynamic range.
2997 It accepts the following parameters:
3003 A list of times in seconds for each channel over which the instantaneous level
3004 of the input signal is averaged to determine its volume. @var{attacks} refers to
3005 increase of volume and @var{decays} refers to decrease of volume. For most
3006 situations, the attack time (response to the audio getting louder) should be
3007 shorter than the decay time, because the human ear is more sensitive to sudden
3008 loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
3009 a typical value for decay is 0.8 seconds.
3010 If specified number of attacks & decays is lower than number of channels, the last
3011 set attack/decay will be used for all remaining channels.
3014 A list of points for the transfer function, specified in dB relative to the
3015 maximum possible signal amplitude. Each key points list must be defined using
3016 the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
3017 @code{x0/y0 x1/y1 x2/y2 ....}
3019 The input values must be in strictly increasing order but the transfer function
3020 does not have to be monotonically rising. The point @code{0/0} is assumed but
3021 may be overridden (by @code{0/out-dBn}). Typical values for the transfer
3022 function are @code{-70/-70|-60/-20|1/0}.
3025 Set the curve radius in dB for all joints. It defaults to 0.01.
3028 Set the additional gain in dB to be applied at all points on the transfer
3029 function. This allows for easy adjustment of the overall gain.
3033 Set an initial volume, in dB, to be assumed for each channel when filtering
3034 starts. This permits the user to supply a nominal level initially, so that, for
3035 example, a very large gain is not applied to initial signal levels before the
3036 companding has begun to operate. A typical value for audio which is initially
3037 quiet is -90 dB. It defaults to 0.
3040 Set a delay, in seconds. The input audio is analyzed immediately, but audio is
3041 delayed before being fed to the volume adjuster. Specifying a delay
3042 approximately equal to the attack/decay times allows the filter to effectively
3043 operate in predictive rather than reactive mode. It defaults to 0.
3047 @subsection Examples
3051 Make music with both quiet and loud passages suitable for listening to in a
3054 compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
3057 Another example for audio with whisper and explosion parts:
3059 compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
3063 A noise gate for when the noise is at a lower level than the signal:
3065 compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
3069 Here is another noise gate, this time for when the noise is at a higher level
3070 than the signal (making it, in some ways, similar to squelch):
3072 compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
3076 2:1 compression starting at -6dB:
3078 compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
3082 2:1 compression starting at -9dB:
3084 compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
3088 2:1 compression starting at -12dB:
3090 compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
3094 2:1 compression starting at -18dB:
3096 compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
3100 3:1 compression starting at -15dB:
3102 compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
3108 compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
3114 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
3118 Hard limiter at -6dB:
3120 compand=attacks=0:points=-80/-80|-6/-6|20/-6
3124 Hard limiter at -12dB:
3126 compand=attacks=0:points=-80/-80|-12/-12|20/-12
3130 Hard noise gate at -35 dB:
3132 compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
3138 compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
3142 @section compensationdelay
3144 Compensation Delay Line is a metric based delay to compensate differing
3145 positions of microphones or speakers.
3147 For example, you have recorded guitar with two microphones placed in
3148 different locations. Because the front of sound wave has fixed speed in
3149 normal conditions, the phasing of microphones can vary and depends on
3150 their location and interposition. The best sound mix can be achieved when
3151 these microphones are in phase (synchronized). Note that a distance of
3152 ~30 cm between microphones makes one microphone capture the signal in
3153 antiphase to the other microphone. That makes the final mix sound moody.
3154 This filter helps to solve phasing problems by adding different delays
3155 to each microphone track and make them synchronized.
3157 The best result can be reached when you take one track as base and
3158 synchronize other tracks one by one with it.
3159 Remember that synchronization/delay tolerance depends on sample rate, too.
3160 Higher sample rates will give more tolerance.
3162 The filter accepts the following parameters:
3166 Set millimeters distance. This is compensation distance for fine tuning.
3170 Set cm distance. This is compensation distance for tightening distance setup.
3174 Set meters distance. This is compensation distance for hard distance setup.
3178 Set dry amount. Amount of unprocessed (dry) signal.
3182 Set wet amount. Amount of processed (wet) signal.
3186 Set temperature in degrees Celsius. This is the temperature of the environment.
3191 Apply headphone crossfeed filter.
3193 Crossfeed is the process of blending the left and right channels of stereo
3195 It is mainly used to reduce extreme stereo separation of low frequencies.
3197 The intent is to produce more speaker like sound to the listener.
3199 The filter accepts the following options:
3203 Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1.
3204 This sets gain of low shelf filter for side part of stereo image.
3205 Default is -6dB. Max allowed is -30db when strength is set to 1.
3208 Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1.
3209 This sets cut off frequency of low shelf filter. Default is cut off near
3210 1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz.
3213 Set input gain. Default is 0.9.
3216 Set output gain. Default is 1.
3219 @section crystalizer
3220 Simple algorithm to expand audio dynamic range.
3222 The filter accepts the following options:
3226 Sets the intensity of effect (default: 2.0). Must be in range between 0.0
3227 (unchanged sound) to 10.0 (maximum effect).
3230 Enable clipping. By default is enabled.
3233 @subsection Commands
3235 This filter supports the all above options as @ref{commands}.
3238 Apply a DC shift to the audio.
3240 This can be useful to remove a DC offset (caused perhaps by a hardware problem
3241 in the recording chain) from the audio. The effect of a DC offset is reduced
3242 headroom and hence volume. The @ref{astats} filter can be used to determine if
3243 a signal has a DC offset.
3247 Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
3251 Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
3252 used to prevent clipping.
3257 Apply de-essing to the audio samples.
3261 Set intensity for triggering de-essing. Allowed range is from 0 to 1.
3265 Set amount of ducking on treble part of sound. Allowed range is from 0 to 1.
3269 How much of original frequency content to keep when de-essing. Allowed range is from 0 to 1.
3273 Set the output mode.
3275 It accepts the following values:
3278 Pass input unchanged.
3281 Pass ess filtered out.
3286 Default value is @var{o}.
3292 Measure audio dynamic range.
3294 DR values of 14 and higher is found in very dynamic material. DR of 8 to 13
3295 is found in transition material. And anything less that 8 have very poor dynamics
3296 and is very compressed.
3298 The filter accepts the following options:
3302 Set window length in seconds used to split audio into segments of equal length.
3303 Default is 3 seconds.
3307 Dynamic Audio Normalizer.
3309 This filter applies a certain amount of gain to the input audio in order
3310 to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
3311 contrast to more "simple" normalization algorithms, the Dynamic Audio
3312 Normalizer *dynamically* re-adjusts the gain factor to the input audio.
3313 This allows for applying extra gain to the "quiet" sections of the audio
3314 while avoiding distortions or clipping the "loud" sections. In other words:
3315 The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
3316 sections, in the sense that the volume of each section is brought to the
3317 same target level. Note, however, that the Dynamic Audio Normalizer achieves
3318 this goal *without* applying "dynamic range compressing". It will retain 100%
3319 of the dynamic range *within* each section of the audio file.
3323 Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
3324 Default is 500 milliseconds.
3325 The Dynamic Audio Normalizer processes the input audio in small chunks,
3326 referred to as frames. This is required, because a peak magnitude has no
3327 meaning for just a single sample value. Instead, we need to determine the
3328 peak magnitude for a contiguous sequence of sample values. While a "standard"
3329 normalizer would simply use the peak magnitude of the complete file, the
3330 Dynamic Audio Normalizer determines the peak magnitude individually for each
3331 frame. The length of a frame is specified in milliseconds. By default, the
3332 Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
3333 been found to give good results with most files.
3334 Note that the exact frame length, in number of samples, will be determined
3335 automatically, based on the sampling rate of the individual input audio file.
3338 Set the Gaussian filter window size. In range from 3 to 301, must be odd
3339 number. Default is 31.
3340 Probably the most important parameter of the Dynamic Audio Normalizer is the
3341 @code{window size} of the Gaussian smoothing filter. The filter's window size
3342 is specified in frames, centered around the current frame. For the sake of
3343 simplicity, this must be an odd number. Consequently, the default value of 31
3344 takes into account the current frame, as well as the 15 preceding frames and
3345 the 15 subsequent frames. Using a larger window results in a stronger
3346 smoothing effect and thus in less gain variation, i.e. slower gain
3347 adaptation. Conversely, using a smaller window results in a weaker smoothing
3348 effect and thus in more gain variation, i.e. faster gain adaptation.
3349 In other words, the more you increase this value, the more the Dynamic Audio
3350 Normalizer will behave like a "traditional" normalization filter. On the
3351 contrary, the more you decrease this value, the more the Dynamic Audio
3352 Normalizer will behave like a dynamic range compressor.
3355 Set the target peak value. This specifies the highest permissible magnitude
3356 level for the normalized audio input. This filter will try to approach the
3357 target peak magnitude as closely as possible, but at the same time it also
3358 makes sure that the normalized signal will never exceed the peak magnitude.
3359 A frame's maximum local gain factor is imposed directly by the target peak
3360 magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
3361 It is not recommended to go above this value.
3364 Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
3365 The Dynamic Audio Normalizer determines the maximum possible (local) gain
3366 factor for each input frame, i.e. the maximum gain factor that does not
3367 result in clipping or distortion. The maximum gain factor is determined by
3368 the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
3369 additionally bounds the frame's maximum gain factor by a predetermined
3370 (global) maximum gain factor. This is done in order to avoid excessive gain
3371 factors in "silent" or almost silent frames. By default, the maximum gain
3372 factor is 10.0, For most inputs the default value should be sufficient and
3373 it usually is not recommended to increase this value. Though, for input
3374 with an extremely low overall volume level, it may be necessary to allow even
3375 higher gain factors. Note, however, that the Dynamic Audio Normalizer does
3376 not simply apply a "hard" threshold (i.e. cut off values above the threshold).
3377 Instead, a "sigmoid" threshold function will be applied. This way, the
3378 gain factors will smoothly approach the threshold value, but never exceed that
3382 Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
3383 By default, the Dynamic Audio Normalizer performs "peak" normalization.
3384 This means that the maximum local gain factor for each frame is defined
3385 (only) by the frame's highest magnitude sample. This way, the samples can
3386 be amplified as much as possible without exceeding the maximum signal
3387 level, i.e. without clipping. Optionally, however, the Dynamic Audio
3388 Normalizer can also take into account the frame's root mean square,
3389 abbreviated RMS. In electrical engineering, the RMS is commonly used to
3390 determine the power of a time-varying signal. It is therefore considered
3391 that the RMS is a better approximation of the "perceived loudness" than
3392 just looking at the signal's peak magnitude. Consequently, by adjusting all
3393 frames to a constant RMS value, a uniform "perceived loudness" can be
3394 established. If a target RMS value has been specified, a frame's local gain
3395 factor is defined as the factor that would result in exactly that RMS value.
3396 Note, however, that the maximum local gain factor is still restricted by the
3397 frame's highest magnitude sample, in order to prevent clipping.
3400 Enable channels coupling. By default is enabled.
3401 By default, the Dynamic Audio Normalizer will amplify all channels by the same
3402 amount. This means the same gain factor will be applied to all channels, i.e.
3403 the maximum possible gain factor is determined by the "loudest" channel.
3404 However, in some recordings, it may happen that the volume of the different
3405 channels is uneven, e.g. one channel may be "quieter" than the other one(s).
3406 In this case, this option can be used to disable the channel coupling. This way,
3407 the gain factor will be determined independently for each channel, depending
3408 only on the individual channel's highest magnitude sample. This allows for
3409 harmonizing the volume of the different channels.
3412 Enable DC bias correction. By default is disabled.
3413 An audio signal (in the time domain) is a sequence of sample values.
3414 In the Dynamic Audio Normalizer these sample values are represented in the
3415 -1.0 to 1.0 range, regardless of the original input format. Normally, the
3416 audio signal, or "waveform", should be centered around the zero point.
3417 That means if we calculate the mean value of all samples in a file, or in a
3418 single frame, then the result should be 0.0 or at least very close to that
3419 value. If, however, there is a significant deviation of the mean value from
3420 0.0, in either positive or negative direction, this is referred to as a
3421 DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
3422 Audio Normalizer provides optional DC bias correction.
3423 With DC bias correction enabled, the Dynamic Audio Normalizer will determine
3424 the mean value, or "DC correction" offset, of each input frame and subtract
3425 that value from all of the frame's sample values which ensures those samples
3426 are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
3427 boundaries, the DC correction offset values will be interpolated smoothly
3428 between neighbouring frames.
3430 @item altboundary, b
3431 Enable alternative boundary mode. By default is disabled.
3432 The Dynamic Audio Normalizer takes into account a certain neighbourhood
3433 around each frame. This includes the preceding frames as well as the
3434 subsequent frames. However, for the "boundary" frames, located at the very
3435 beginning and at the very end of the audio file, not all neighbouring
3436 frames are available. In particular, for the first few frames in the audio
3437 file, the preceding frames are not known. And, similarly, for the last few
3438 frames in the audio file, the subsequent frames are not known. Thus, the
3439 question arises which gain factors should be assumed for the missing frames
3440 in the "boundary" region. The Dynamic Audio Normalizer implements two modes
3441 to deal with this situation. The default boundary mode assumes a gain factor
3442 of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
3443 "fade out" at the beginning and at the end of the input, respectively.
3446 Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
3447 By default, the Dynamic Audio Normalizer does not apply "traditional"
3448 compression. This means that signal peaks will not be pruned and thus the
3449 full dynamic range will be retained within each local neighbourhood. However,
3450 in some cases it may be desirable to combine the Dynamic Audio Normalizer's
3451 normalization algorithm with a more "traditional" compression.
3452 For this purpose, the Dynamic Audio Normalizer provides an optional compression
3453 (thresholding) function. If (and only if) the compression feature is enabled,
3454 all input frames will be processed by a soft knee thresholding function prior
3455 to the actual normalization process. Put simply, the thresholding function is
3456 going to prune all samples whose magnitude exceeds a certain threshold value.
3457 However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
3458 value. Instead, the threshold value will be adjusted for each individual
3460 In general, smaller parameters result in stronger compression, and vice versa.
3461 Values below 3.0 are not recommended, because audible distortion may appear.
3464 Set the target threshold value. This specifies the lowest permissible
3465 magnitude level for the audio input which will be normalized.
3466 If input frame volume is above this value frame will be normalized.
3467 Otherwise frame may not be normalized at all. The default value is set
3468 to 0, which means all input frames will be normalized.
3469 This option is mostly useful if digital noise is not wanted to be amplified.
3472 @subsection Commands
3474 This filter supports the all above options as @ref{commands}.
3478 Make audio easier to listen to on headphones.
3480 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
3481 so that when listened to on headphones the stereo image is moved from
3482 inside your head (standard for headphones) to outside and in front of
3483 the listener (standard for speakers).
3489 Apply a two-pole peaking equalisation (EQ) filter. With this
3490 filter, the signal-level at and around a selected frequency can
3491 be increased or decreased, whilst (unlike bandpass and bandreject
3492 filters) that at all other frequencies is unchanged.
3494 In order to produce complex equalisation curves, this filter can
3495 be given several times, each with a different central frequency.
3497 The filter accepts the following options:
3501 Set the filter's central frequency in Hz.
3504 Set method to specify band-width of filter.
3519 Specify the band-width of a filter in width_type units.
3522 Set the required gain or attenuation in dB.
3523 Beware of clipping when using a positive gain.
3526 How much to use filtered signal in output. Default is 1.
3527 Range is between 0 and 1.
3530 Specify which channels to filter, by default all available are filtered.
3533 Normalize biquad coefficients, by default is disabled.
3534 Enabling it will normalize magnitude response at DC to 0dB.
3537 @subsection Examples
3540 Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
3542 equalizer=f=1000:t=h:width=200:g=-10
3546 Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
3548 equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
3552 @subsection Commands
3554 This filter supports the following commands:
3557 Change equalizer frequency.
3558 Syntax for the command is : "@var{frequency}"
3561 Change equalizer width_type.
3562 Syntax for the command is : "@var{width_type}"
3565 Change equalizer width.
3566 Syntax for the command is : "@var{width}"
3569 Change equalizer gain.
3570 Syntax for the command is : "@var{gain}"
3573 Change equalizer mix.
3574 Syntax for the command is : "@var{mix}"
3577 @section extrastereo
3579 Linearly increases the difference between left and right channels which
3580 adds some sort of "live" effect to playback.
3582 The filter accepts the following options:
3586 Sets the difference coefficient (default: 2.5). 0.0 means mono sound
3587 (average of both channels), with 1.0 sound will be unchanged, with
3588 -1.0 left and right channels will be swapped.
3591 Enable clipping. By default is enabled.
3594 @subsection Commands
3596 This filter supports the all above options as @ref{commands}.
3598 @section firequalizer
3599 Apply FIR Equalization using arbitrary frequency response.
3601 The filter accepts the following option:
3605 Set gain curve equation (in dB). The expression can contain variables:
3608 the evaluated frequency
3612 channel number, set to 0 when multichannels evaluation is disabled
3614 channel id, see libavutil/channel_layout.h, set to the first channel id when
3615 multichannels evaluation is disabled
3619 channel_layout, see libavutil/channel_layout.h
3624 @item gain_interpolate(f)
3625 interpolate gain on frequency f based on gain_entry
3626 @item cubic_interpolate(f)
3627 same as gain_interpolate, but smoother
3629 This option is also available as command. Default is @code{gain_interpolate(f)}.
3632 Set gain entry for gain_interpolate function. The expression can
3636 store gain entry at frequency f with value g
3638 This option is also available as command.
3641 Set filter delay in seconds. Higher value means more accurate.
3642 Default is @code{0.01}.
3645 Set filter accuracy in Hz. Lower value means more accurate.
3646 Default is @code{5}.
3649 Set window function. Acceptable values are:
3652 rectangular window, useful when gain curve is already smooth
3654 hann window (default)
3660 3-terms continuous 1st derivative nuttall window
3662 minimum 3-terms discontinuous nuttall window
3664 4-terms continuous 1st derivative nuttall window
3666 minimum 4-terms discontinuous nuttall (blackman-nuttall) window
3668 blackman-harris window
3674 If enabled, use fixed number of audio samples. This improves speed when
3675 filtering with large delay. Default is disabled.
3678 Enable multichannels evaluation on gain. Default is disabled.
3681 Enable zero phase mode by subtracting timestamp to compensate delay.
3682 Default is disabled.
3685 Set scale used by gain. Acceptable values are:
3688 linear frequency, linear gain
3690 linear frequency, logarithmic (in dB) gain (default)
3692 logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain
3694 logarithmic frequency, logarithmic gain
3698 Set file for dumping, suitable for gnuplot.
3701 Set scale for dumpfile. Acceptable values are same with scale option.
3705 Enable 2-channel convolution using complex FFT. This improves speed significantly.
3706 Default is disabled.
3709 Enable minimum phase impulse response. Default is disabled.
3712 @subsection Examples
3717 firequalizer=gain='if(lt(f,1000), 0, -INF)'
3720 lowpass at 1000 Hz with gain_entry:
3722 firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
3725 custom equalization:
3727 firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
3730 higher delay with zero phase to compensate delay:
3732 firequalizer=delay=0.1:fixed=on:zero_phase=on
3735 lowpass on left channel, highpass on right channel:
3737 firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
3738 :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
3743 Apply a flanging effect to the audio.
3745 The filter accepts the following options:
3749 Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
3752 Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2.
3755 Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
3759 Set percentage of delayed signal mixed with original. Range from 0 to 100.
3760 Default value is 71.
3763 Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
3766 Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
3767 Default value is @var{sinusoidal}.
3770 Set swept wave percentage-shift for multi channel. Range from 0 to 100.
3771 Default value is 25.
3774 Set delay-line interpolation, @var{linear} or @var{quadratic}.
3775 Default is @var{linear}.
3779 Apply Haas effect to audio.
3781 Note that this makes most sense to apply on mono signals.
3782 With this filter applied to mono signals it give some directionality and
3783 stretches its stereo image.
3785 The filter accepts the following options:
3789 Set input level. By default is @var{1}, or 0dB
3792 Set output level. By default is @var{1}, or 0dB.
3795 Set gain applied to side part of signal. By default is @var{1}.
3798 Set kind of middle source. Can be one of the following:
3808 Pick middle part signal of stereo image.
3811 Pick side part signal of stereo image.
3815 Change middle phase. By default is disabled.
3818 Set left channel delay. By default is @var{2.05} milliseconds.
3821 Set left channel balance. By default is @var{-1}.
3824 Set left channel gain. By default is @var{1}.
3827 Change left phase. By default is disabled.
3830 Set right channel delay. By defaults is @var{2.12} milliseconds.
3833 Set right channel balance. By default is @var{1}.
3836 Set right channel gain. By default is @var{1}.
3839 Change right phase. By default is enabled.
3844 Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
3845 embedded HDCD codes is expanded into a 20-bit PCM stream.
3847 The filter supports the Peak Extend and Low-level Gain Adjustment features
3848 of HDCD, and detects the Transient Filter flag.
3851 ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
3854 When using the filter with wav, note the default encoding for wav is 16-bit,
3855 so the resulting 20-bit stream will be truncated back to 16-bit. Use something
3856 like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
3858 ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
3859 ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
3862 The filter accepts the following options:
3865 @item disable_autoconvert
3866 Disable any automatic format conversion or resampling in the filter graph.
3868 @item process_stereo
3869 Process the stereo channels together. If target_gain does not match between
3870 channels, consider it invalid and use the last valid target_gain.
3873 Set the code detect timer period in ms.
3876 Always extend peaks above -3dBFS even if PE isn't signaled.
3879 Replace audio with a solid tone and adjust the amplitude to signal some
3880 specific aspect of the decoding process. The output file can be loaded in
3881 an audio editor alongside the original to aid analysis.
3883 @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
3890 Gain adjustment level at each sample
3892 Samples where peak extend occurs
3894 Samples where the code detect timer is active
3896 Samples where the target gain does not match between channels
3902 Apply head-related transfer functions (HRTFs) to create virtual
3903 loudspeakers around the user for binaural listening via headphones.
3904 The HRIRs are provided via additional streams, for each channel
3905 one stereo input stream is needed.
3907 The filter accepts the following options:
3911 Set mapping of input streams for convolution.
3912 The argument is a '|'-separated list of channel names in order as they
3913 are given as additional stream inputs for filter.
3914 This also specify number of input streams. Number of input streams
3915 must be not less than number of channels in first stream plus one.
3918 Set gain applied to audio. Value is in dB. Default is 0.
3921 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
3922 processing audio in time domain which is slow.
3923 @var{freq} is processing audio in frequency domain which is fast.
3924 Default is @var{freq}.
3927 Set custom gain for LFE channels. Value is in dB. Default is 0.
3930 Set size of frame in number of samples which will be processed at once.
3931 Default value is @var{1024}. Allowed range is from 1024 to 96000.
3934 Set format of hrir stream.
3935 Default value is @var{stereo}. Alternative value is @var{multich}.
3936 If value is set to @var{stereo}, number of additional streams should
3937 be greater or equal to number of input channels in first input stream.
3938 Also each additional stream should have stereo number of channels.
3939 If value is set to @var{multich}, number of additional streams should
3940 be exactly one. Also number of input channels of additional stream
3941 should be equal or greater than twice number of channels of first input
3945 @subsection Examples
3949 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
3950 each amovie filter use stereo file with IR coefficients as input.
3951 The files give coefficients for each position of virtual loudspeaker:
3954 -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"
3959 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
3960 but now in @var{multich} @var{hrir} format.
3962 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"
3969 Apply a high-pass filter with 3dB point frequency.
3970 The filter can be either single-pole, or double-pole (the default).
3971 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
3973 The filter accepts the following options:
3977 Set frequency in Hz. Default is 3000.
3980 Set number of poles. Default is 2.
3983 Set method to specify band-width of filter.
3998 Specify the band-width of a filter in width_type units.
3999 Applies only to double-pole filter.
4000 The default is 0.707q and gives a Butterworth response.
4003 How much to use filtered signal in output. Default is 1.
4004 Range is between 0 and 1.
4007 Specify which channels to filter, by default all available are filtered.
4010 Normalize biquad coefficients, by default is disabled.
4011 Enabling it will normalize magnitude response at DC to 0dB.
4014 @subsection Commands
4016 This filter supports the following commands:
4019 Change highpass frequency.
4020 Syntax for the command is : "@var{frequency}"
4023 Change highpass width_type.
4024 Syntax for the command is : "@var{width_type}"
4027 Change highpass width.
4028 Syntax for the command is : "@var{width}"
4031 Change highpass mix.
4032 Syntax for the command is : "@var{mix}"
4037 Join multiple input streams into one multi-channel stream.
4039 It accepts the following parameters:
4043 The number of input streams. It defaults to 2.
4045 @item channel_layout
4046 The desired output channel layout. It defaults to stereo.
4049 Map channels from inputs to output. The argument is a '|'-separated list of
4050 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
4051 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
4052 can be either the name of the input channel (e.g. FL for front left) or its
4053 index in the specified input stream. @var{out_channel} is the name of the output
4057 The filter will attempt to guess the mappings when they are not specified
4058 explicitly. It does so by first trying to find an unused matching input channel
4059 and if that fails it picks the first unused input channel.
4061 Join 3 inputs (with properly set channel layouts):
4063 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
4066 Build a 5.1 output from 6 single-channel streams:
4068 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
4069 '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'
4075 Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
4077 To enable compilation of this filter you need to configure FFmpeg with
4078 @code{--enable-ladspa}.
4082 Specifies the name of LADSPA plugin library to load. If the environment
4083 variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
4084 each one of the directories specified by the colon separated list in
4085 @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
4086 this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
4087 @file{/usr/lib/ladspa/}.
4090 Specifies the plugin within the library. Some libraries contain only
4091 one plugin, but others contain many of them. If this is not set filter
4092 will list all available plugins within the specified library.
4095 Set the '|' separated list of controls which are zero or more floating point
4096 values that determine the behavior of the loaded plugin (for example delay,
4098 Controls need to be defined using the following syntax:
4099 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
4100 @var{valuei} is the value set on the @var{i}-th control.
4101 Alternatively they can be also defined using the following syntax:
4102 @var{value0}|@var{value1}|@var{value2}|..., where
4103 @var{valuei} is the value set on the @var{i}-th control.
4104 If @option{controls} is set to @code{help}, all available controls and
4105 their valid ranges are printed.
4107 @item sample_rate, s
4108 Specify the sample rate, default to 44100. Only used if plugin have
4112 Set the number of samples per channel per each output frame, default
4113 is 1024. Only used if plugin have zero inputs.
4116 Set the minimum duration of the sourced audio. See
4117 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4118 for the accepted syntax.
4119 Note that the resulting duration may be greater than the specified duration,
4120 as the generated audio is always cut at the end of a complete frame.
4121 If not specified, or the expressed duration is negative, the audio is
4122 supposed to be generated forever.
4123 Only used if plugin have zero inputs.
4127 @subsection Examples
4131 List all available plugins within amp (LADSPA example plugin) library:
4137 List all available controls and their valid ranges for @code{vcf_notch}
4138 plugin from @code{VCF} library:
4140 ladspa=f=vcf:p=vcf_notch:c=help
4144 Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
4147 ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
4151 Add reverberation to the audio using TAP-plugins
4152 (Tom's Audio Processing plugins):
4154 ladspa=file=tap_reverb:tap_reverb
4158 Generate white noise, with 0.2 amplitude:
4160 ladspa=file=cmt:noise_source_white:c=c0=.2
4164 Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
4165 @code{C* Audio Plugin Suite} (CAPS) library:
4167 ladspa=file=caps:Click:c=c1=20'
4171 Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
4173 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
4177 Increase volume by 20dB using fast lookahead limiter from Steve Harris
4178 @code{SWH Plugins} collection:
4180 ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
4184 Attenuate low frequencies using Multiband EQ from Steve Harris
4185 @code{SWH Plugins} collection:
4187 ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
4191 Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite}
4194 ladspa=caps:Narrower
4198 Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library:
4200 ladspa=caps:White:.2
4204 Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library:
4206 ladspa=caps:Fractal:c=c1=1
4210 Dynamic volume normalization using @code{VLevel} plugin:
4212 ladspa=vlevel-ladspa:vlevel_mono
4216 @subsection Commands
4218 This filter supports the following commands:
4221 Modify the @var{N}-th control value.
4223 If the specified value is not valid, it is ignored and prior one is kept.
4228 EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
4229 Support for both single pass (livestreams, files) and double pass (files) modes.
4230 This algorithm can target IL, LRA, and maximum true peak. In dynamic mode, to accurately
4231 detect true peaks, the audio stream will be upsampled to 192 kHz.
4232 Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate.
4234 The filter accepts the following options:
4238 Set integrated loudness target.
4239 Range is -70.0 - -5.0. Default value is -24.0.
4242 Set loudness range target.
4243 Range is 1.0 - 20.0. Default value is 7.0.
4246 Set maximum true peak.
4247 Range is -9.0 - +0.0. Default value is -2.0.
4249 @item measured_I, measured_i
4250 Measured IL of input file.
4251 Range is -99.0 - +0.0.
4253 @item measured_LRA, measured_lra
4254 Measured LRA of input file.
4255 Range is 0.0 - 99.0.
4257 @item measured_TP, measured_tp
4258 Measured true peak of input file.
4259 Range is -99.0 - +99.0.
4261 @item measured_thresh
4262 Measured threshold of input file.
4263 Range is -99.0 - +0.0.
4266 Set offset gain. Gain is applied before the true-peak limiter.
4267 Range is -99.0 - +99.0. Default is +0.0.
4270 Normalize by linearly scaling the source audio.
4271 @code{measured_I}, @code{measured_LRA}, @code{measured_TP},
4272 and @code{measured_thresh} must all be specified. Target LRA shouldn't
4273 be lower than source LRA and the change in integrated loudness shouldn't
4274 result in a true peak which exceeds the target TP. If any of these
4275 conditions aren't met, normalization mode will revert to @var{dynamic}.
4276 Options are @code{true} or @code{false}. Default is @code{true}.
4279 Treat mono input files as "dual-mono". If a mono file is intended for playback
4280 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
4281 If set to @code{true}, this option will compensate for this effect.
4282 Multi-channel input files are not affected by this option.
4283 Options are true or false. Default is false.
4286 Set print format for stats. Options are summary, json, or none.
4287 Default value is none.
4292 Apply a low-pass filter with 3dB point frequency.
4293 The filter can be either single-pole or double-pole (the default).
4294 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
4296 The filter accepts the following options:
4300 Set frequency in Hz. Default is 500.
4303 Set number of poles. Default is 2.
4306 Set method to specify band-width of filter.
4321 Specify the band-width of a filter in width_type units.
4322 Applies only to double-pole filter.
4323 The default is 0.707q and gives a Butterworth response.
4326 How much to use filtered signal in output. Default is 1.
4327 Range is between 0 and 1.
4330 Specify which channels to filter, by default all available are filtered.
4333 Normalize biquad coefficients, by default is disabled.
4334 Enabling it will normalize magnitude response at DC to 0dB.
4337 @subsection Examples
4340 Lowpass only LFE channel, it LFE is not present it does nothing:
4346 @subsection Commands
4348 This filter supports the following commands:
4351 Change lowpass frequency.
4352 Syntax for the command is : "@var{frequency}"
4355 Change lowpass width_type.
4356 Syntax for the command is : "@var{width_type}"
4359 Change lowpass width.
4360 Syntax for the command is : "@var{width}"
4364 Syntax for the command is : "@var{mix}"
4369 Load a LV2 (LADSPA Version 2) plugin.
4371 To enable compilation of this filter you need to configure FFmpeg with
4372 @code{--enable-lv2}.
4376 Specifies the plugin URI. You may need to escape ':'.
4379 Set the '|' separated list of controls which are zero or more floating point
4380 values that determine the behavior of the loaded plugin (for example delay,
4382 If @option{controls} is set to @code{help}, all available controls and
4383 their valid ranges are printed.
4385 @item sample_rate, s
4386 Specify the sample rate, default to 44100. Only used if plugin have
4390 Set the number of samples per channel per each output frame, default
4391 is 1024. Only used if plugin have zero inputs.
4394 Set the minimum duration of the sourced audio. See
4395 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4396 for the accepted syntax.
4397 Note that the resulting duration may be greater than the specified duration,
4398 as the generated audio is always cut at the end of a complete frame.
4399 If not specified, or the expressed duration is negative, the audio is
4400 supposed to be generated forever.
4401 Only used if plugin have zero inputs.
4404 @subsection Examples
4408 Apply bass enhancer plugin from Calf:
4410 lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
4414 Apply vinyl plugin from Calf:
4416 lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
4420 Apply bit crusher plugin from ArtyFX:
4422 lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
4427 Multiband Compress or expand the audio's dynamic range.
4429 The input audio is divided into bands using 4th order Linkwitz-Riley IIRs.
4430 This is akin to the crossover of a loudspeaker, and results in flat frequency
4431 response when absent compander action.
4433 It accepts the following parameters:
4437 This option syntax is:
4438 attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ...
4439 For explanation of each item refer to compand filter documentation.
4445 Mix channels with specific gain levels. The filter accepts the output
4446 channel layout followed by a set of channels definitions.
4448 This filter is also designed to efficiently remap the channels of an audio
4451 The filter accepts parameters of the form:
4452 "@var{l}|@var{outdef}|@var{outdef}|..."
4456 output channel layout or number of channels
4459 output channel specification, of the form:
4460 "@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]"
4463 output channel to define, either a channel name (FL, FR, etc.) or a channel
4464 number (c0, c1, etc.)
4467 multiplicative coefficient for the channel, 1 leaving the volume unchanged
4470 input channel to use, see out_name for details; it is not possible to mix
4471 named and numbered input channels
4474 If the `=' in a channel specification is replaced by `<', then the gains for
4475 that specification will be renormalized so that the total is 1, thus
4476 avoiding clipping noise.
4478 @subsection Mixing examples
4480 For example, if you want to down-mix from stereo to mono, but with a bigger
4481 factor for the left channel:
4483 pan=1c|c0=0.9*c0+0.1*c1
4486 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
4487 7-channels surround:
4489 pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
4492 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
4493 that should be preferred (see "-ac" option) unless you have very specific
4496 @subsection Remapping examples
4498 The channel remapping will be effective if, and only if:
4501 @item gain coefficients are zeroes or ones,
4502 @item only one input per channel output,
4505 If all these conditions are satisfied, the filter will notify the user ("Pure
4506 channel mapping detected"), and use an optimized and lossless method to do the
4509 For example, if you have a 5.1 source and want a stereo audio stream by
4510 dropping the extra channels:
4512 pan="stereo| c0=FL | c1=FR"
4515 Given the same source, you can also switch front left and front right channels
4516 and keep the input channel layout:
4518 pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
4521 If the input is a stereo audio stream, you can mute the front left channel (and
4522 still keep the stereo channel layout) with:
4527 Still with a stereo audio stream input, you can copy the right channel in both
4528 front left and right:
4530 pan="stereo| c0=FR | c1=FR"
4535 ReplayGain scanner filter. This filter takes an audio stream as an input and
4536 outputs it unchanged.
4537 At end of filtering it displays @code{track_gain} and @code{track_peak}.
4541 Convert the audio sample format, sample rate and channel layout. It is
4542 not meant to be used directly.
4545 Apply time-stretching and pitch-shifting with librubberband.
4547 To enable compilation of this filter, you need to configure FFmpeg with
4548 @code{--enable-librubberband}.
4550 The filter accepts the following options:
4554 Set tempo scale factor.
4557 Set pitch scale factor.
4560 Set transients detector.
4561 Possible values are:
4570 Possible values are:
4579 Possible values are:
4586 Set processing window size.
4587 Possible values are:
4596 Possible values are:
4603 Enable formant preservation when shift pitching.
4604 Possible values are:
4612 Possible values are:
4621 Possible values are:
4628 @subsection Commands
4630 This filter supports the following commands:
4633 Change filter tempo scale factor.
4634 Syntax for the command is : "@var{tempo}"
4637 Change filter pitch scale factor.
4638 Syntax for the command is : "@var{pitch}"
4641 @section sidechaincompress
4643 This filter acts like normal compressor but has the ability to compress
4644 detected signal using second input signal.
4645 It needs two input streams and returns one output stream.
4646 First input stream will be processed depending on second stream signal.
4647 The filtered signal then can be filtered with other filters in later stages of
4648 processing. See @ref{pan} and @ref{amerge} filter.
4650 The filter accepts the following options:
4654 Set input gain. Default is 1. Range is between 0.015625 and 64.
4657 Set mode of compressor operation. Can be @code{upward} or @code{downward}.
4658 Default is @code{downward}.
4661 If a signal of second stream raises above this level it will affect the gain
4662 reduction of first stream.
4663 By default is 0.125. Range is between 0.00097563 and 1.
4666 Set a ratio about which the signal is reduced. 1:2 means that if the level
4667 raised 4dB above the threshold, it will be only 2dB above after the reduction.
4668 Default is 2. Range is between 1 and 20.
4671 Amount of milliseconds the signal has to rise above the threshold before gain
4672 reduction starts. Default is 20. Range is between 0.01 and 2000.
4675 Amount of milliseconds the signal has to fall below the threshold before
4676 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
4679 Set the amount by how much signal will be amplified after processing.
4680 Default is 1. Range is from 1 to 64.
4683 Curve the sharp knee around the threshold to enter gain reduction more softly.
4684 Default is 2.82843. Range is between 1 and 8.
4687 Choose if the @code{average} level between all channels of side-chain stream
4688 or the louder(@code{maximum}) channel of side-chain stream affects the
4689 reduction. Default is @code{average}.
4692 Should the exact signal be taken in case of @code{peak} or an RMS one in case
4693 of @code{rms}. Default is @code{rms} which is mainly smoother.
4696 Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
4699 How much to use compressed signal in output. Default is 1.
4700 Range is between 0 and 1.
4703 @subsection Commands
4705 This filter supports the all above options as @ref{commands}.
4707 @subsection Examples
4711 Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
4712 depending on the signal of 2nd input and later compressed signal to be
4713 merged with 2nd input:
4715 ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
4719 @section sidechaingate
4721 A sidechain gate acts like a normal (wideband) gate but has the ability to
4722 filter the detected signal before sending it to the gain reduction stage.
4723 Normally a gate uses the full range signal to detect a level above the
4725 For example: If you cut all lower frequencies from your sidechain signal
4726 the gate will decrease the volume of your track only if not enough highs
4727 appear. With this technique you are able to reduce the resonation of a
4728 natural drum or remove "rumbling" of muted strokes from a heavily distorted
4730 It needs two input streams and returns one output stream.
4731 First input stream will be processed depending on second stream signal.
4733 The filter accepts the following options:
4737 Set input level before filtering.
4738 Default is 1. Allowed range is from 0.015625 to 64.
4741 Set the mode of operation. Can be @code{upward} or @code{downward}.
4742 Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
4743 will be amplified, expanding dynamic range in upward direction.
4744 Otherwise, in case of @code{downward} lower parts of signal will be reduced.
4747 Set the level of gain reduction when the signal is below the threshold.
4748 Default is 0.06125. Allowed range is from 0 to 1.
4749 Setting this to 0 disables reduction and then filter behaves like expander.
4752 If a signal rises above this level the gain reduction is released.
4753 Default is 0.125. Allowed range is from 0 to 1.
4756 Set a ratio about which the signal is reduced.
4757 Default is 2. Allowed range is from 1 to 9000.
4760 Amount of milliseconds the signal has to rise above the threshold before gain
4762 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
4765 Amount of milliseconds the signal has to fall below the threshold before the
4766 reduction is increased again. Default is 250 milliseconds.
4767 Allowed range is from 0.01 to 9000.
4770 Set amount of amplification of signal after processing.
4771 Default is 1. Allowed range is from 1 to 64.
4774 Curve the sharp knee around the threshold to enter gain reduction more softly.
4775 Default is 2.828427125. Allowed range is from 1 to 8.
4778 Choose if exact signal should be taken for detection or an RMS like one.
4779 Default is rms. Can be peak or rms.
4782 Choose if the average level between all channels or the louder channel affects
4784 Default is average. Can be average or maximum.
4787 Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
4790 @section silencedetect
4792 Detect silence in an audio stream.
4794 This filter logs a message when it detects that the input audio volume is less
4795 or equal to a noise tolerance value for a duration greater or equal to the
4796 minimum detected noise duration.
4798 The printed times and duration are expressed in seconds. The
4799 @code{lavfi.silence_start} or @code{lavfi.silence_start.X} metadata key
4800 is set on the first frame whose timestamp equals or exceeds the detection
4801 duration and it contains the timestamp of the first frame of the silence.
4803 The @code{lavfi.silence_duration} or @code{lavfi.silence_duration.X}
4804 and @code{lavfi.silence_end} or @code{lavfi.silence_end.X} metadata
4805 keys are set on the first frame after the silence. If @option{mono} is
4806 enabled, and each channel is evaluated separately, the @code{.X}
4807 suffixed keys are used, and @code{X} corresponds to the channel number.
4809 The filter accepts the following options:
4813 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
4814 specified value) or amplitude ratio. Default is -60dB, or 0.001.
4817 Set silence duration until notification (default is 2 seconds). See
4818 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4819 for the accepted syntax.
4822 Process each channel separately, instead of combined. By default is disabled.
4825 @subsection Examples
4829 Detect 5 seconds of silence with -50dB noise tolerance:
4831 silencedetect=n=-50dB:d=5
4835 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
4836 tolerance in @file{silence.mp3}:
4838 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
4842 @section silenceremove
4844 Remove silence from the beginning, middle or end of the audio.
4846 The filter accepts the following options:
4850 This value is used to indicate if audio should be trimmed at beginning of
4851 the audio. A value of zero indicates no silence should be trimmed from the
4852 beginning. When specifying a non-zero value, it trims audio up until it
4853 finds non-silence. Normally, when trimming silence from beginning of audio
4854 the @var{start_periods} will be @code{1} but it can be increased to higher
4855 values to trim all audio up to specific count of non-silence periods.
4856 Default value is @code{0}.
4858 @item start_duration
4859 Specify the amount of time that non-silence must be detected before it stops
4860 trimming audio. By increasing the duration, bursts of noises can be treated
4861 as silence and trimmed off. Default value is @code{0}.
4863 @item start_threshold
4864 This indicates what sample value should be treated as silence. For digital
4865 audio, a value of @code{0} may be fine but for audio recorded from analog,
4866 you may wish to increase the value to account for background noise.
4867 Can be specified in dB (in case "dB" is appended to the specified value)
4868 or amplitude ratio. Default value is @code{0}.
4871 Specify max duration of silence at beginning that will be kept after
4872 trimming. Default is 0, which is equal to trimming all samples detected
4876 Specify mode of detection of silence end in start of multi-channel audio.
4877 Can be @var{any} or @var{all}. Default is @var{any}.
4878 With @var{any}, any sample that is detected as non-silence will cause
4879 stopped trimming of silence.
4880 With @var{all}, only if all channels are detected as non-silence will cause
4881 stopped trimming of silence.
4884 Set the count for trimming silence from the end of audio.
4885 To remove silence from the middle of a file, specify a @var{stop_periods}
4886 that is negative. This value is then treated as a positive value and is
4887 used to indicate the effect should restart processing as specified by
4888 @var{start_periods}, making it suitable for removing periods of silence
4889 in the middle of the audio.
4890 Default value is @code{0}.
4893 Specify a duration of silence that must exist before audio is not copied any
4894 more. By specifying a higher duration, silence that is wanted can be left in
4896 Default value is @code{0}.
4898 @item stop_threshold
4899 This is the same as @option{start_threshold} but for trimming silence from
4901 Can be specified in dB (in case "dB" is appended to the specified value)
4902 or amplitude ratio. Default value is @code{0}.
4905 Specify max duration of silence at end that will be kept after
4906 trimming. Default is 0, which is equal to trimming all samples detected
4910 Specify mode of detection of silence start in end of multi-channel audio.
4911 Can be @var{any} or @var{all}. Default is @var{any}.
4912 With @var{any}, any sample that is detected as non-silence will cause
4913 stopped trimming of silence.
4914 With @var{all}, only if all channels are detected as non-silence will cause
4915 stopped trimming of silence.
4918 Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
4919 and works better with digital silence which is exactly 0.
4920 Default value is @code{rms}.
4923 Set duration in number of seconds used to calculate size of window in number
4924 of samples for detecting silence.
4925 Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
4928 @subsection Examples
4932 The following example shows how this filter can be used to start a recording
4933 that does not contain the delay at the start which usually occurs between
4934 pressing the record button and the start of the performance:
4936 silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
4940 Trim all silence encountered from beginning to end where there is more than 1
4941 second of silence in audio:
4943 silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
4947 Trim all digital silence samples, using peak detection, from beginning to end
4948 where there is more than 0 samples of digital silence in audio and digital
4949 silence is detected in all channels at same positions in stream:
4951 silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0
4957 SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
4958 loudspeakers around the user for binaural listening via headphones (audio
4959 formats up to 9 channels supported).
4960 The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
4961 SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
4962 Austrian Academy of Sciences.
4964 To enable compilation of this filter you need to configure FFmpeg with
4965 @code{--enable-libmysofa}.
4967 The filter accepts the following options:
4971 Set the SOFA file used for rendering.
4974 Set gain applied to audio. Value is in dB. Default is 0.
4977 Set rotation of virtual loudspeakers in deg. Default is 0.
4980 Set elevation of virtual speakers in deg. Default is 0.
4983 Set distance in meters between loudspeakers and the listener with near-field
4984 HRTFs. Default is 1.
4987 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
4988 processing audio in time domain which is slow.
4989 @var{freq} is processing audio in frequency domain which is fast.
4990 Default is @var{freq}.
4993 Set custom positions of virtual loudspeakers. Syntax for this option is:
4994 <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
4995 Each virtual loudspeaker is described with short channel name following with
4996 azimuth and elevation in degrees.
4997 Each virtual loudspeaker description is separated by '|'.
4998 For example to override front left and front right channel positions use:
4999 'speakers=FL 45 15|FR 345 15'.
5000 Descriptions with unrecognised channel names are ignored.
5003 Set custom gain for LFE channels. Value is in dB. Default is 0.
5006 Set custom frame size in number of samples. Default is 1024.
5007 Allowed range is from 1024 to 96000. Only used if option @samp{type}
5008 is set to @var{freq}.
5011 Should all IRs be normalized upon importing SOFA file.
5012 By default is enabled.
5015 Should nearest IRs be interpolated with neighbor IRs if exact position
5016 does not match. By default is disabled.
5019 Minphase all IRs upon loading of SOFA file. By default is disabled.
5022 Set neighbor search angle step. Only used if option @var{interpolate} is enabled.
5025 Set neighbor search radius step. Only used if option @var{interpolate} is enabled.
5028 @subsection Examples
5032 Using ClubFritz6 sofa file:
5034 sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
5038 Using ClubFritz12 sofa file and bigger radius with small rotation:
5040 sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
5044 Similar as above but with custom speaker positions for front left, front right, back left and back right
5045 and also with custom gain:
5047 "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
5051 @section stereotools
5053 This filter has some handy utilities to manage stereo signals, for converting
5054 M/S stereo recordings to L/R signal while having control over the parameters
5055 or spreading the stereo image of master track.
5057 The filter accepts the following options:
5061 Set input level before filtering for both channels. Defaults is 1.
5062 Allowed range is from 0.015625 to 64.
5065 Set output level after filtering for both channels. Defaults is 1.
5066 Allowed range is from 0.015625 to 64.
5069 Set input balance between both channels. Default is 0.
5070 Allowed range is from -1 to 1.
5073 Set output balance between both channels. Default is 0.
5074 Allowed range is from -1 to 1.
5077 Enable softclipping. Results in analog distortion instead of harsh digital 0dB
5078 clipping. Disabled by default.
5081 Mute the left channel. Disabled by default.
5084 Mute the right channel. Disabled by default.
5087 Change the phase of the left channel. Disabled by default.
5090 Change the phase of the right channel. Disabled by default.
5093 Set stereo mode. Available values are:
5097 Left/Right to Left/Right, this is default.
5100 Left/Right to Mid/Side.
5103 Mid/Side to Left/Right.
5106 Left/Right to Left/Left.
5109 Left/Right to Right/Right.
5112 Left/Right to Left + Right.
5115 Left/Right to Right/Left.
5118 Mid/Side to Left/Left.
5121 Mid/Side to Right/Right.
5125 Set level of side signal. Default is 1.
5126 Allowed range is from 0.015625 to 64.
5129 Set balance of side signal. Default is 0.
5130 Allowed range is from -1 to 1.
5133 Set level of the middle signal. Default is 1.
5134 Allowed range is from 0.015625 to 64.
5137 Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
5140 Set stereo base between mono and inversed channels. Default is 0.
5141 Allowed range is from -1 to 1.
5144 Set delay in milliseconds how much to delay left from right channel and
5145 vice versa. Default is 0. Allowed range is from -20 to 20.
5148 Set S/C level. Default is 1. Allowed range is from 1 to 100.
5151 Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
5153 @item bmode_in, bmode_out
5154 Set balance mode for balance_in/balance_out option.
5156 Can be one of the following:
5160 Classic balance mode. Attenuate one channel at time.
5161 Gain is raised up to 1.
5164 Similar as classic mode above but gain is raised up to 2.
5167 Equal power distribution, from -6dB to +6dB range.
5171 @subsection Examples
5175 Apply karaoke like effect:
5177 stereotools=mlev=0.015625
5181 Convert M/S signal to L/R:
5183 "stereotools=mode=ms>lr"
5187 @section stereowiden
5189 This filter enhance the stereo effect by suppressing signal common to both
5190 channels and by delaying the signal of left into right and vice versa,
5191 thereby widening the stereo effect.
5193 The filter accepts the following options:
5197 Time in milliseconds of the delay of left signal into right and vice versa.
5198 Default is 20 milliseconds.
5201 Amount of gain in delayed signal into right and vice versa. Gives a delay
5202 effect of left signal in right output and vice versa which gives widening
5203 effect. Default is 0.3.
5206 Cross feed of left into right with inverted phase. This helps in suppressing
5207 the mono. If the value is 1 it will cancel all the signal common to both
5208 channels. Default is 0.3.
5211 Set level of input signal of original channel. Default is 0.8.
5214 @subsection Commands
5216 This filter supports the all above options except @code{delay} as @ref{commands}.
5218 @section superequalizer
5219 Apply 18 band equalizer.
5221 The filter accepts the following options:
5228 Set 131Hz band gain.
5230 Set 185Hz band gain.
5232 Set 262Hz band gain.
5234 Set 370Hz band gain.
5236 Set 523Hz band gain.
5238 Set 740Hz band gain.
5240 Set 1047Hz band gain.
5242 Set 1480Hz band gain.
5244 Set 2093Hz band gain.
5246 Set 2960Hz band gain.
5248 Set 4186Hz band gain.
5250 Set 5920Hz band gain.
5252 Set 8372Hz band gain.
5254 Set 11840Hz band gain.
5256 Set 16744Hz band gain.
5258 Set 20000Hz band gain.
5262 Apply audio surround upmix filter.
5264 This filter allows to produce multichannel output from audio stream.
5266 The filter accepts the following options:
5270 Set output channel layout. By default, this is @var{5.1}.
5272 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5273 for the required syntax.
5276 Set input channel layout. By default, this is @var{stereo}.
5278 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5279 for the required syntax.
5282 Set input volume level. By default, this is @var{1}.
5285 Set output volume level. By default, this is @var{1}.
5288 Enable LFE channel output if output channel layout has it. By default, this is enabled.
5291 Set LFE low cut off frequency. By default, this is @var{128} Hz.
5294 Set LFE high cut off frequency. By default, this is @var{256} Hz.
5297 Set LFE mode, can be @var{add} or @var{sub}. Default is @var{add}.
5298 In @var{add} mode, LFE channel is created from input audio and added to output.
5299 In @var{sub} mode, LFE channel is created from input audio and added to output but
5300 also all non-LFE output channels are subtracted with output LFE channel.
5303 Set angle of stereo surround transform, Allowed range is from @var{0} to @var{360}.
5304 Default is @var{90}.
5307 Set front center input volume. By default, this is @var{1}.
5310 Set front center output volume. By default, this is @var{1}.
5313 Set front left input volume. By default, this is @var{1}.
5316 Set front left output volume. By default, this is @var{1}.
5319 Set front right input volume. By default, this is @var{1}.
5322 Set front right output volume. By default, this is @var{1}.
5325 Set side left input volume. By default, this is @var{1}.
5328 Set side left output volume. By default, this is @var{1}.
5331 Set side right input volume. By default, this is @var{1}.
5334 Set side right output volume. By default, this is @var{1}.
5337 Set back left input volume. By default, this is @var{1}.
5340 Set back left output volume. By default, this is @var{1}.
5343 Set back right input volume. By default, this is @var{1}.
5346 Set back right output volume. By default, this is @var{1}.
5349 Set back center input volume. By default, this is @var{1}.
5352 Set back center output volume. By default, this is @var{1}.
5355 Set LFE input volume. By default, this is @var{1}.
5358 Set LFE output volume. By default, this is @var{1}.
5361 Set spread usage of stereo image across X axis for all channels.
5364 Set spread usage of stereo image across Y axis for all channels.
5366 @item fcx, flx, frx, blx, brx, slx, srx, bcx
5367 Set spread usage of stereo image across X axis for each channel.
5369 @item fcy, fly, fry, bly, bry, sly, sry, bcy
5370 Set spread usage of stereo image across Y axis for each channel.
5373 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
5376 Set window function.
5378 It accepts the following values:
5401 Default is @code{hann}.
5404 Set window overlap. If set to 1, the recommended overlap for selected
5405 window function will be picked. Default is @code{0.5}.
5408 @section treble, highshelf
5410 Boost or cut treble (upper) frequencies of the audio using a two-pole
5411 shelving filter with a response similar to that of a standard
5412 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
5414 The filter accepts the following options:
5418 Give the gain at whichever is the lower of ~22 kHz and the
5419 Nyquist frequency. Its useful range is about -20 (for a large cut)
5420 to +20 (for a large boost). Beware of clipping when using a positive gain.
5423 Set the filter's central frequency and so can be used
5424 to extend or reduce the frequency range to be boosted or cut.
5425 The default value is @code{3000} Hz.
5428 Set method to specify band-width of filter.
5443 Determine how steep is the filter's shelf transition.
5446 How much to use filtered signal in output. Default is 1.
5447 Range is between 0 and 1.
5450 Specify which channels to filter, by default all available are filtered.
5453 Normalize biquad coefficients, by default is disabled.
5454 Enabling it will normalize magnitude response at DC to 0dB.
5457 @subsection Commands
5459 This filter supports the following commands:
5462 Change treble frequency.
5463 Syntax for the command is : "@var{frequency}"
5466 Change treble width_type.
5467 Syntax for the command is : "@var{width_type}"
5470 Change treble width.
5471 Syntax for the command is : "@var{width}"
5475 Syntax for the command is : "@var{gain}"
5479 Syntax for the command is : "@var{mix}"
5484 Sinusoidal amplitude modulation.
5486 The filter accepts the following options:
5490 Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
5491 (20 Hz or lower) will result in a tremolo effect.
5492 This filter may also be used as a ring modulator by specifying
5493 a modulation frequency higher than 20 Hz.
5494 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
5497 Depth of modulation as a percentage. Range is 0.0 - 1.0.
5498 Default value is 0.5.
5503 Sinusoidal phase modulation.
5505 The filter accepts the following options:
5509 Modulation frequency in Hertz.
5510 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
5513 Depth of modulation as a percentage. Range is 0.0 - 1.0.
5514 Default value is 0.5.
5519 Adjust the input audio volume.
5521 It accepts the following parameters:
5525 Set audio volume expression.
5527 Output values are clipped to the maximum value.
5529 The output audio volume is given by the relation:
5531 @var{output_volume} = @var{volume} * @var{input_volume}
5534 The default value for @var{volume} is "1.0".
5537 This parameter represents the mathematical precision.
5539 It determines which input sample formats will be allowed, which affects the
5540 precision of the volume scaling.
5544 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
5546 32-bit floating-point; this limits input sample format to FLT. (default)
5548 64-bit floating-point; this limits input sample format to DBL.
5552 Choose the behaviour on encountering ReplayGain side data in input frames.
5556 Remove ReplayGain side data, ignoring its contents (the default).
5559 Ignore ReplayGain side data, but leave it in the frame.
5562 Prefer the track gain, if present.
5565 Prefer the album gain, if present.
5568 @item replaygain_preamp
5569 Pre-amplification gain in dB to apply to the selected replaygain gain.
5571 Default value for @var{replaygain_preamp} is 0.0.
5573 @item replaygain_noclip
5574 Prevent clipping by limiting the gain applied.
5576 Default value for @var{replaygain_noclip} is 1.
5579 Set when the volume expression is evaluated.
5581 It accepts the following values:
5584 only evaluate expression once during the filter initialization, or
5585 when the @samp{volume} command is sent
5588 evaluate expression for each incoming frame
5591 Default value is @samp{once}.
5594 The volume expression can contain the following parameters.
5598 frame number (starting at zero)
5601 @item nb_consumed_samples
5602 number of samples consumed by the filter
5604 number of samples in the current frame
5606 original frame position in the file
5612 PTS at start of stream
5614 time at start of stream
5620 last set volume value
5623 Note that when @option{eval} is set to @samp{once} only the
5624 @var{sample_rate} and @var{tb} variables are available, all other
5625 variables will evaluate to NAN.
5627 @subsection Commands
5629 This filter supports the following commands:
5632 Modify the volume expression.
5633 The command accepts the same syntax of the corresponding option.
5635 If the specified expression is not valid, it is kept at its current
5639 @subsection Examples
5643 Halve the input audio volume:
5647 volume=volume=-6.0206dB
5650 In all the above example the named key for @option{volume} can be
5651 omitted, for example like in:
5657 Increase input audio power by 6 decibels using fixed-point precision:
5659 volume=volume=6dB:precision=fixed
5663 Fade volume after time 10 with an annihilation period of 5 seconds:
5665 volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
5669 @section volumedetect
5671 Detect the volume of the input video.
5673 The filter has no parameters. The input is not modified. Statistics about
5674 the volume will be printed in the log when the input stream end is reached.
5676 In particular it will show the mean volume (root mean square), maximum
5677 volume (on a per-sample basis), and the beginning of a histogram of the
5678 registered volume values (from the maximum value to a cumulated 1/1000 of
5681 All volumes are in decibels relative to the maximum PCM value.
5683 @subsection Examples
5685 Here is an excerpt of the output:
5687 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
5688 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
5689 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
5690 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
5691 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
5692 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
5693 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
5694 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
5695 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
5701 The mean square energy is approximately -27 dB, or 10^-2.7.
5703 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
5705 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
5708 In other words, raising the volume by +4 dB does not cause any clipping,
5709 raising it by +5 dB causes clipping for 6 samples, etc.
5711 @c man end AUDIO FILTERS
5713 @chapter Audio Sources
5714 @c man begin AUDIO SOURCES
5716 Below is a description of the currently available audio sources.
5720 Buffer audio frames, and make them available to the filter chain.
5722 This source is mainly intended for a programmatic use, in particular
5723 through the interface defined in @file{libavfilter/asrc_abuffer.h}.
5725 It accepts the following parameters:
5729 The timebase which will be used for timestamps of submitted frames. It must be
5730 either a floating-point number or in @var{numerator}/@var{denominator} form.
5733 The sample rate of the incoming audio buffers.
5736 The sample format of the incoming audio buffers.
5737 Either a sample format name or its corresponding integer representation from
5738 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
5740 @item channel_layout
5741 The channel layout of the incoming audio buffers.
5742 Either a channel layout name from channel_layout_map in
5743 @file{libavutil/channel_layout.c} or its corresponding integer representation
5744 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
5747 The number of channels of the incoming audio buffers.
5748 If both @var{channels} and @var{channel_layout} are specified, then they
5753 @subsection Examples
5756 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
5759 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
5760 Since the sample format with name "s16p" corresponds to the number
5761 6 and the "stereo" channel layout corresponds to the value 0x3, this is
5764 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
5769 Generate an audio signal specified by an expression.
5771 This source accepts in input one or more expressions (one for each
5772 channel), which are evaluated and used to generate a corresponding
5775 This source accepts the following options:
5779 Set the '|'-separated expressions list for each separate channel. In case the
5780 @option{channel_layout} option is not specified, the selected channel layout
5781 depends on the number of provided expressions. Otherwise the last
5782 specified expression is applied to the remaining output channels.
5784 @item channel_layout, c
5785 Set the channel layout. The number of channels in the specified layout
5786 must be equal to the number of specified expressions.
5789 Set the minimum duration of the sourced audio. See
5790 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5791 for the accepted syntax.
5792 Note that the resulting duration may be greater than the specified
5793 duration, as the generated audio is always cut at the end of a
5796 If not specified, or the expressed duration is negative, the audio is
5797 supposed to be generated forever.
5800 Set the number of samples per channel per each output frame,
5803 @item sample_rate, s
5804 Specify the sample rate, default to 44100.
5807 Each expression in @var{exprs} can contain the following constants:
5811 number of the evaluated sample, starting from 0
5814 time of the evaluated sample expressed in seconds, starting from 0
5821 @subsection Examples
5831 Generate a sin signal with frequency of 440 Hz, set sample rate to
5834 aevalsrc="sin(440*2*PI*t):s=8000"
5838 Generate a two channels signal, specify the channel layout (Front
5839 Center + Back Center) explicitly:
5841 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
5845 Generate white noise:
5847 aevalsrc="-2+random(0)"
5851 Generate an amplitude modulated signal:
5853 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
5857 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
5859 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
5866 Generate a FIR coefficients using frequency sampling method.
5868 The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
5870 The filter accepts the following options:
5874 Set number of filter coefficents in output audio stream.
5875 Default value is 1025.
5878 Set frequency points from where magnitude and phase are set.
5879 This must be in non decreasing order, and first element must be 0, while last element
5880 must be 1. Elements are separated by white spaces.
5883 Set magnitude value for every frequency point set by @option{frequency}.
5884 Number of values must be same as number of frequency points.
5885 Values are separated by white spaces.
5888 Set phase value for every frequency point set by @option{frequency}.
5889 Number of values must be same as number of frequency points.
5890 Values are separated by white spaces.
5892 @item sample_rate, r
5893 Set sample rate, default is 44100.
5896 Set number of samples per each frame. Default is 1024.
5899 Set window function. Default is blackman.
5904 The null audio source, return unprocessed audio frames. It is mainly useful
5905 as a template and to be employed in analysis / debugging tools, or as
5906 the source for filters which ignore the input data (for example the sox
5909 This source accepts the following options:
5913 @item channel_layout, cl
5915 Specifies the channel layout, and can be either an integer or a string
5916 representing a channel layout. The default value of @var{channel_layout}
5919 Check the channel_layout_map definition in
5920 @file{libavutil/channel_layout.c} for the mapping between strings and
5921 channel layout values.
5923 @item sample_rate, r
5924 Specifies the sample rate, and defaults to 44100.
5927 Set the number of samples per requested frames.
5931 @subsection Examples
5935 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
5937 anullsrc=r=48000:cl=4
5941 Do the same operation with a more obvious syntax:
5943 anullsrc=r=48000:cl=mono
5947 All the parameters need to be explicitly defined.
5951 Synthesize a voice utterance using the libflite library.
5953 To enable compilation of this filter you need to configure FFmpeg with
5954 @code{--enable-libflite}.
5956 Note that versions of the flite library prior to 2.0 are not thread-safe.
5958 The filter accepts the following options:
5963 If set to 1, list the names of the available voices and exit
5964 immediately. Default value is 0.
5967 Set the maximum number of samples per frame. Default value is 512.
5970 Set the filename containing the text to speak.
5973 Set the text to speak.
5976 Set the voice to use for the speech synthesis. Default value is
5977 @code{kal}. See also the @var{list_voices} option.
5980 @subsection Examples
5984 Read from file @file{speech.txt}, and synthesize the text using the
5985 standard flite voice:
5987 flite=textfile=speech.txt
5991 Read the specified text selecting the @code{slt} voice:
5993 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
5997 Input text to ffmpeg:
5999 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
6003 Make @file{ffplay} speak the specified text, using @code{flite} and
6004 the @code{lavfi} device:
6006 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
6010 For more information about libflite, check:
6011 @url{http://www.festvox.org/flite/}
6015 Generate a noise audio signal.
6017 The filter accepts the following options:
6020 @item sample_rate, r
6021 Specify the sample rate. Default value is 48000 Hz.
6024 Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value
6028 Specify the duration of the generated audio stream. Not specifying this option
6029 results in noise with an infinite length.
6031 @item color, colour, c
6032 Specify the color of noise. Available noise colors are white, pink, brown,
6033 blue, violet and velvet. Default color is white.
6036 Specify a value used to seed the PRNG.
6039 Set the number of samples per each output frame, default is 1024.
6042 @subsection Examples
6047 Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5:
6049 anoisesrc=d=60:c=pink:r=44100:a=0.5
6055 Generate odd-tap Hilbert transform FIR coefficients.
6057 The resulting stream can be used with @ref{afir} filter for phase-shifting
6058 the signal by 90 degrees.
6060 This is used in many matrix coding schemes and for analytic signal generation.
6061 The process is often written as a multiplication by i (or j), the imaginary unit.
6063 The filter accepts the following options:
6067 @item sample_rate, s
6068 Set sample rate, default is 44100.
6071 Set length of FIR filter, default is 22051.
6074 Set number of samples per each frame.
6077 Set window function to be used when generating FIR coefficients.
6082 Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients.
6084 The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
6086 The filter accepts the following options:
6089 @item sample_rate, r
6090 Set sample rate, default is 44100.
6093 Set number of samples per each frame. Default is 1024.
6096 Set high-pass frequency. Default is 0.
6099 Set low-pass frequency. Default is 0.
6100 If high-pass frequency is lower than low-pass frequency and low-pass frequency
6101 is higher than 0 then filter will create band-pass filter coefficients,
6102 otherwise band-reject filter coefficients.
6105 Set filter phase response. Default is 50. Allowed range is from 0 to 100.
6108 Set Kaiser window beta.
6111 Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB.
6114 Enable rounding, by default is disabled.
6117 Set number of taps for high-pass filter.
6120 Set number of taps for low-pass filter.
6125 Generate an audio signal made of a sine wave with amplitude 1/8.
6127 The audio signal is bit-exact.
6129 The filter accepts the following options:
6134 Set the carrier frequency. Default is 440 Hz.
6136 @item beep_factor, b
6137 Enable a periodic beep every second with frequency @var{beep_factor} times
6138 the carrier frequency. Default is 0, meaning the beep is disabled.
6140 @item sample_rate, r
6141 Specify the sample rate, default is 44100.
6144 Specify the duration of the generated audio stream.
6146 @item samples_per_frame
6147 Set the number of samples per output frame.
6149 The expression can contain the following constants:
6153 The (sequential) number of the output audio frame, starting from 0.
6156 The PTS (Presentation TimeStamp) of the output audio frame,
6157 expressed in @var{TB} units.
6160 The PTS of the output audio frame, expressed in seconds.
6163 The timebase of the output audio frames.
6166 Default is @code{1024}.
6169 @subsection Examples
6174 Generate a simple 440 Hz sine wave:
6180 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
6184 sine=frequency=220:beep_factor=4:duration=5
6188 Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC
6191 sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
6195 @c man end AUDIO SOURCES
6197 @chapter Audio Sinks
6198 @c man begin AUDIO SINKS
6200 Below is a description of the currently available audio sinks.
6202 @section abuffersink
6204 Buffer audio frames, and make them available to the end of filter chain.
6206 This sink is mainly intended for programmatic use, in particular
6207 through the interface defined in @file{libavfilter/buffersink.h}
6208 or the options system.
6210 It accepts a pointer to an AVABufferSinkContext structure, which
6211 defines the incoming buffers' formats, to be passed as the opaque
6212 parameter to @code{avfilter_init_filter} for initialization.
6215 Null audio sink; do absolutely nothing with the input audio. It is
6216 mainly useful as a template and for use in analysis / debugging
6219 @c man end AUDIO SINKS
6221 @chapter Video Filters
6222 @c man begin VIDEO FILTERS
6224 When you configure your FFmpeg build, you can disable any of the
6225 existing filters using @code{--disable-filters}.
6226 The configure output will show the video filters included in your
6229 Below is a description of the currently available video filters.
6233 Mark a region of interest in a video frame.
6235 The frame data is passed through unchanged, but metadata is attached
6236 to the frame indicating regions of interest which can affect the
6237 behaviour of later encoding. Multiple regions can be marked by
6238 applying the filter multiple times.
6242 Region distance in pixels from the left edge of the frame.
6244 Region distance in pixels from the top edge of the frame.
6246 Region width in pixels.
6248 Region height in pixels.
6250 The parameters @var{x}, @var{y}, @var{w} and @var{h} are expressions,
6251 and may contain the following variables:
6254 Width of the input frame.
6256 Height of the input frame.
6260 Quantisation offset to apply within the region.
6262 This must be a real value in the range -1 to +1. A value of zero
6263 indicates no quality change. A negative value asks for better quality
6264 (less quantisation), while a positive value asks for worse quality
6265 (greater quantisation).
6267 The range is calibrated so that the extreme values indicate the
6268 largest possible offset - if the rest of the frame is encoded with the
6269 worst possible quality, an offset of -1 indicates that this region
6270 should be encoded with the best possible quality anyway. Intermediate
6271 values are then interpolated in some codec-dependent way.
6273 For example, in 10-bit H.264 the quantisation parameter varies between
6274 -12 and 51. A typical qoffset value of -1/10 therefore indicates that
6275 this region should be encoded with a QP around one-tenth of the full
6276 range better than the rest of the frame. So, if most of the frame
6277 were to be encoded with a QP of around 30, this region would get a QP
6278 of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3).
6279 An extreme value of -1 would indicate that this region should be
6280 encoded with the best possible quality regardless of the treatment of
6281 the rest of the frame - that is, should be encoded at a QP of -12.
6283 If set to true, remove any existing regions of interest marked on the
6284 frame before adding the new one.
6287 @subsection Examples
6291 Mark the centre quarter of the frame as interesting.
6293 addroi=iw/4:ih/4:iw/2:ih/2:-1/10
6296 Mark the 100-pixel-wide region on the left edge of the frame as very
6297 uninteresting (to be encoded at much lower quality than the rest of
6300 addroi=0:0:100:ih:+1/5
6304 @section alphaextract
6306 Extract the alpha component from the input as a grayscale video. This
6307 is especially useful with the @var{alphamerge} filter.
6311 Add or replace the alpha component of the primary input with the
6312 grayscale value of a second input. This is intended for use with
6313 @var{alphaextract} to allow the transmission or storage of frame
6314 sequences that have alpha in a format that doesn't support an alpha
6317 For example, to reconstruct full frames from a normal YUV-encoded video
6318 and a separate video created with @var{alphaextract}, you might use:
6320 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
6323 Since this filter is designed for reconstruction, it operates on frame
6324 sequences without considering timestamps, and terminates when either
6325 input reaches end of stream. This will cause problems if your encoding
6326 pipeline drops frames. If you're trying to apply an image as an
6327 overlay to a video stream, consider the @var{overlay} filter instead.
6331 Amplify differences between current pixel and pixels of adjacent frames in
6332 same pixel location.
6334 This filter accepts the following options:
6338 Set frame radius. Default is 2. Allowed range is from 1 to 63.
6339 For example radius of 3 will instruct filter to calculate average of 7 frames.
6342 Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535.
6345 Set threshold for difference amplification. Any difference greater or equal to
6346 this value will not alter source pixel. Default is 10.
6347 Allowed range is from 0 to 65535.
6350 Set tolerance for difference amplification. Any difference lower to
6351 this value will not alter source pixel. Default is 0.
6352 Allowed range is from 0 to 65535.
6355 Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
6356 This option controls maximum possible value that will decrease source pixel value.
6359 Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
6360 This option controls maximum possible value that will increase source pixel value.
6363 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
6366 @subsection Commands
6368 This filter supports the following @ref{commands} that corresponds to option of same name:
6380 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
6381 and libavformat to work. On the other hand, it is limited to ASS (Advanced
6382 Substation Alpha) subtitles files.
6384 This filter accepts the following option in addition to the common options from
6385 the @ref{subtitles} filter:
6389 Set the shaping engine
6391 Available values are:
6394 The default libass shaping engine, which is the best available.
6396 Fast, font-agnostic shaper that can do only substitutions
6398 Slower shaper using OpenType for substitutions and positioning
6401 The default is @code{auto}.
6405 Apply an Adaptive Temporal Averaging Denoiser to the video input.
6407 The filter accepts the following options:
6411 Set threshold A for 1st plane. Default is 0.02.
6412 Valid range is 0 to 0.3.
6415 Set threshold B for 1st plane. Default is 0.04.
6416 Valid range is 0 to 5.
6419 Set threshold A for 2nd plane. Default is 0.02.
6420 Valid range is 0 to 0.3.
6423 Set threshold B for 2nd plane. Default is 0.04.
6424 Valid range is 0 to 5.
6427 Set threshold A for 3rd plane. Default is 0.02.
6428 Valid range is 0 to 0.3.
6431 Set threshold B for 3rd plane. Default is 0.04.
6432 Valid range is 0 to 5.
6434 Threshold A is designed to react on abrupt changes in the input signal and
6435 threshold B is designed to react on continuous changes in the input signal.
6438 Set number of frames filter will use for averaging. Default is 9. Must be odd
6439 number in range [5, 129].
6442 Set what planes of frame filter will use for averaging. Default is all.
6445 Set what variant of algorithm filter will use for averaging. Default is @code{p} parallel.
6446 Alternatively can be set to @code{s} serial.
6448 Parallel can be faster then serial, while other way around is never true.
6449 Parallel will abort early on first change being greater then thresholds, while serial
6450 will continue processing other side of frames if they are equal or bellow thresholds.
6453 @subsection Commands
6454 This filter supports same @ref{commands} as options except option @code{s}.
6455 The command accepts the same syntax of the corresponding option.
6459 Apply average blur filter.
6461 The filter accepts the following options:
6465 Set horizontal radius size.
6468 Set which planes to filter. By default all planes are filtered.
6471 Set vertical radius size, if zero it will be same as @code{sizeX}.
6472 Default is @code{0}.
6475 @subsection Commands
6476 This filter supports same commands as options.
6477 The command accepts the same syntax of the corresponding option.
6479 If the specified expression is not valid, it is kept at its current
6484 Compute the bounding box for the non-black pixels in the input frame
6487 This filter computes the bounding box containing all the pixels with a
6488 luminance value greater than the minimum allowed value.
6489 The parameters describing the bounding box are printed on the filter
6492 The filter accepts the following option:
6496 Set the minimal luminance value. Default is @code{16}.
6500 Apply bilateral filter, spatial smoothing while preserving edges.
6502 The filter accepts the following options:
6505 Set sigma of gaussian function to calculate spatial weight.
6506 Allowed range is 0 to 10. Default is 0.1.
6509 Set sigma of gaussian function to calculate range weight.
6510 Allowed range is 0 to 1. Default is 0.1.
6513 Set planes to filter. Default is first only.
6516 @section bitplanenoise
6518 Show and measure bit plane noise.
6520 The filter accepts the following options:
6524 Set which plane to analyze. Default is @code{1}.
6527 Filter out noisy pixels from @code{bitplane} set above.
6528 Default is disabled.
6531 @section blackdetect
6533 Detect video intervals that are (almost) completely black. Can be
6534 useful to detect chapter transitions, commercials, or invalid
6535 recordings. Output lines contains the time for the start, end and
6536 duration of the detected black interval expressed in seconds.
6538 In order to display the output lines, you need to set the loglevel at
6539 least to the AV_LOG_INFO value.
6541 The filter accepts the following options:
6544 @item black_min_duration, d
6545 Set the minimum detected black duration expressed in seconds. It must
6546 be a non-negative floating point number.
6548 Default value is 2.0.
6550 @item picture_black_ratio_th, pic_th
6551 Set the threshold for considering a picture "black".
6552 Express the minimum value for the ratio:
6554 @var{nb_black_pixels} / @var{nb_pixels}
6557 for which a picture is considered black.
6558 Default value is 0.98.
6560 @item pixel_black_th, pix_th
6561 Set the threshold for considering a pixel "black".
6563 The threshold expresses the maximum pixel luminance value for which a
6564 pixel is considered "black". The provided value is scaled according to
6565 the following equation:
6567 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
6570 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
6571 the input video format, the range is [0-255] for YUV full-range
6572 formats and [16-235] for YUV non full-range formats.
6574 Default value is 0.10.
6577 The following example sets the maximum pixel threshold to the minimum
6578 value, and detects only black intervals of 2 or more seconds:
6580 blackdetect=d=2:pix_th=0.00
6585 Detect frames that are (almost) completely black. Can be useful to
6586 detect chapter transitions or commercials. Output lines consist of
6587 the frame number of the detected frame, the percentage of blackness,
6588 the position in the file if known or -1 and the timestamp in seconds.
6590 In order to display the output lines, you need to set the loglevel at
6591 least to the AV_LOG_INFO value.
6593 This filter exports frame metadata @code{lavfi.blackframe.pblack}.
6594 The value represents the percentage of pixels in the picture that
6595 are below the threshold value.
6597 It accepts the following parameters:
6602 The percentage of the pixels that have to be below the threshold; it defaults to
6605 @item threshold, thresh
6606 The threshold below which a pixel value is considered black; it defaults to
6611 @section blend, tblend
6613 Blend two video frames into each other.
6615 The @code{blend} filter takes two input streams and outputs one
6616 stream, the first input is the "top" layer and second input is
6617 "bottom" layer. By default, the output terminates when the longest input terminates.
6619 The @code{tblend} (time blend) filter takes two consecutive frames
6620 from one single stream, and outputs the result obtained by blending
6621 the new frame on top of the old frame.
6623 A description of the accepted options follows.
6631 Set blend mode for specific pixel component or all pixel components in case
6632 of @var{all_mode}. Default value is @code{normal}.
6634 Available values for component modes are:
6676 Set blend opacity for specific pixel component or all pixel components in case
6677 of @var{all_opacity}. Only used in combination with pixel component blend modes.
6684 Set blend expression for specific pixel component or all pixel components in case
6685 of @var{all_expr}. Note that related mode options will be ignored if those are set.
6687 The expressions can use the following variables:
6691 The sequential number of the filtered frame, starting from @code{0}.
6695 the coordinates of the current sample
6699 the width and height of currently filtered plane
6703 Width and height scale for the plane being filtered. It is the
6704 ratio between the dimensions of the current plane to the luma plane,
6705 e.g. for a @code{yuv420p} frame, the values are @code{1,1} for
6706 the luma plane and @code{0.5,0.5} for the chroma planes.
6709 Time of the current frame, expressed in seconds.
6712 Value of pixel component at current location for first video frame (top layer).
6715 Value of pixel component at current location for second video frame (bottom layer).
6719 The @code{blend} filter also supports the @ref{framesync} options.
6721 @subsection Examples
6725 Apply transition from bottom layer to top layer in first 10 seconds:
6727 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
6731 Apply linear horizontal transition from top layer to bottom layer:
6733 blend=all_expr='A*(X/W)+B*(1-X/W)'
6737 Apply 1x1 checkerboard effect:
6739 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
6743 Apply uncover left effect:
6745 blend=all_expr='if(gte(N*SW+X,W),A,B)'
6749 Apply uncover down effect:
6751 blend=all_expr='if(gte(Y-N*SH,0),A,B)'
6755 Apply uncover up-left effect:
6757 blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
6761 Split diagonally video and shows top and bottom layer on each side:
6763 blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
6767 Display differences between the current and the previous frame:
6769 tblend=all_mode=grainextract
6775 Denoise frames using Block-Matching 3D algorithm.
6777 The filter accepts the following options.
6781 Set denoising strength. Default value is 1.
6782 Allowed range is from 0 to 999.9.
6783 The denoising algorithm is very sensitive to sigma, so adjust it
6784 according to the source.
6787 Set local patch size. This sets dimensions in 2D.
6790 Set sliding step for processing blocks. Default value is 4.
6791 Allowed range is from 1 to 64.
6792 Smaller values allows processing more reference blocks and is slower.
6795 Set maximal number of similar blocks for 3rd dimension. Default value is 1.
6796 When set to 1, no block matching is done. Larger values allows more blocks
6798 Allowed range is from 1 to 256.
6801 Set radius for search block matching. Default is 9.
6802 Allowed range is from 1 to INT32_MAX.
6805 Set step between two search locations for block matching. Default is 1.
6806 Allowed range is from 1 to 64. Smaller is slower.
6809 Set threshold of mean square error for block matching. Valid range is 0 to
6813 Set thresholding parameter for hard thresholding in 3D transformed domain.
6814 Larger values results in stronger hard-thresholding filtering in frequency
6818 Set filtering estimation mode. Can be @code{basic} or @code{final}.
6819 Default is @code{basic}.
6822 If enabled, filter will use 2nd stream for block matching.
6823 Default is disabled for @code{basic} value of @var{estim} option,
6824 and always enabled if value of @var{estim} is @code{final}.
6827 Set planes to filter. Default is all available except alpha.
6830 @subsection Examples
6834 Basic filtering with bm3d:
6836 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
6840 Same as above, but filtering only luma:
6842 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
6846 Same as above, but with both estimation modes:
6848 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
6852 Same as above, but prefilter with @ref{nlmeans} filter instead:
6854 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
6860 Apply a boxblur algorithm to the input video.
6862 It accepts the following parameters:
6866 @item luma_radius, lr
6867 @item luma_power, lp
6868 @item chroma_radius, cr
6869 @item chroma_power, cp
6870 @item alpha_radius, ar
6871 @item alpha_power, ap
6875 A description of the accepted options follows.
6878 @item luma_radius, lr
6879 @item chroma_radius, cr
6880 @item alpha_radius, ar
6881 Set an expression for the box radius in pixels used for blurring the
6882 corresponding input plane.
6884 The radius value must be a non-negative number, and must not be
6885 greater than the value of the expression @code{min(w,h)/2} for the
6886 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
6889 Default value for @option{luma_radius} is "2". If not specified,
6890 @option{chroma_radius} and @option{alpha_radius} default to the
6891 corresponding value set for @option{luma_radius}.
6893 The expressions can contain the following constants:
6897 The input width and height in pixels.
6901 The input chroma image width and height in pixels.
6905 The horizontal and vertical chroma subsample values. For example, for the
6906 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
6909 @item luma_power, lp
6910 @item chroma_power, cp
6911 @item alpha_power, ap
6912 Specify how many times the boxblur filter is applied to the
6913 corresponding plane.
6915 Default value for @option{luma_power} is 2. If not specified,
6916 @option{chroma_power} and @option{alpha_power} default to the
6917 corresponding value set for @option{luma_power}.
6919 A value of 0 will disable the effect.
6922 @subsection Examples
6926 Apply a boxblur filter with the luma, chroma, and alpha radii
6929 boxblur=luma_radius=2:luma_power=1
6934 Set the luma radius to 2, and alpha and chroma radius to 0:
6936 boxblur=2:1:cr=0:ar=0
6940 Set the luma and chroma radii to a fraction of the video dimension:
6942 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
6948 Deinterlace the input video ("bwdif" stands for "Bob Weaver
6949 Deinterlacing Filter").
6951 Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
6952 interpolation algorithms.
6953 It accepts the following parameters:
6957 The interlacing mode to adopt. It accepts one of the following values:
6961 Output one frame for each frame.
6963 Output one frame for each field.
6966 The default value is @code{send_field}.
6969 The picture field parity assumed for the input interlaced video. It accepts one
6970 of the following values:
6974 Assume the top field is first.
6976 Assume the bottom field is first.
6978 Enable automatic detection of field parity.
6981 The default value is @code{auto}.
6982 If the interlacing is unknown or the decoder does not export this information,
6983 top field first will be assumed.
6986 Specify which frames to deinterlace. Accepts one of the following
6991 Deinterlace all frames.
6993 Only deinterlace frames marked as interlaced.
6996 The default value is @code{all}.
7000 Remove all color information for all colors except for certain one.
7002 The filter accepts the following options:
7006 The color which will not be replaced with neutral chroma.
7009 Similarity percentage with the above color.
7010 0.01 matches only the exact key color, while 1.0 matches everything.
7014 0.0 makes pixels either fully gray, or not gray at all.
7015 Higher values result in more preserved color.
7018 Signals that the color passed is already in YUV instead of RGB.
7020 Literal colors like "green" or "red" don't make sense with this enabled anymore.
7021 This can be used to pass exact YUV values as hexadecimal numbers.
7024 @subsection Commands
7025 This filter supports same @ref{commands} as options.
7026 The command accepts the same syntax of the corresponding option.
7028 If the specified expression is not valid, it is kept at its current
7032 YUV colorspace color/chroma keying.
7034 The filter accepts the following options:
7038 The color which will be replaced with transparency.
7041 Similarity percentage with the key color.
7043 0.01 matches only the exact key color, while 1.0 matches everything.
7048 0.0 makes pixels either fully transparent, or not transparent at all.
7050 Higher values result in semi-transparent pixels, with a higher transparency
7051 the more similar the pixels color is to the key color.
7054 Signals that the color passed is already in YUV instead of RGB.
7056 Literal colors like "green" or "red" don't make sense with this enabled anymore.
7057 This can be used to pass exact YUV values as hexadecimal numbers.
7060 @subsection Commands
7061 This filter supports same @ref{commands} as options.
7062 The command accepts the same syntax of the corresponding option.
7064 If the specified expression is not valid, it is kept at its current
7067 @subsection Examples
7071 Make every green pixel in the input image transparent:
7073 ffmpeg -i input.png -vf chromakey=green out.png
7077 Overlay a greenscreen-video on top of a static black background.
7079 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
7083 @section chromashift
7084 Shift chroma pixels horizontally and/or vertically.
7086 The filter accepts the following options:
7089 Set amount to shift chroma-blue horizontally.
7091 Set amount to shift chroma-blue vertically.
7093 Set amount to shift chroma-red horizontally.
7095 Set amount to shift chroma-red vertically.
7097 Set edge mode, can be @var{smear}, default, or @var{warp}.
7100 @subsection Commands
7102 This filter supports the all above options as @ref{commands}.
7106 Display CIE color diagram with pixels overlaid onto it.
7108 The filter accepts the following options:
7123 @item uhdtv, rec2020
7137 Set what gamuts to draw.
7139 See @code{system} option for available values.
7142 Set ciescope size, by default set to 512.
7145 Set intensity used to map input pixel values to CIE diagram.
7148 Set contrast used to draw tongue colors that are out of active color system gamut.
7151 Correct gamma displayed on scope, by default enabled.
7154 Show white point on CIE diagram, by default disabled.
7157 Set input gamma. Used only with XYZ input color space.
7162 Visualize information exported by some codecs.
7164 Some codecs can export information through frames using side-data or other
7165 means. For example, some MPEG based codecs export motion vectors through the
7166 @var{export_mvs} flag in the codec @option{flags2} option.
7168 The filter accepts the following option:
7172 Set motion vectors to visualize.
7174 Available flags for @var{mv} are:
7178 forward predicted MVs of P-frames
7180 forward predicted MVs of B-frames
7182 backward predicted MVs of B-frames
7186 Display quantization parameters using the chroma planes.
7189 Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
7191 Available flags for @var{mv_type} are:
7195 forward predicted MVs
7197 backward predicted MVs
7200 @item frame_type, ft
7201 Set frame type to visualize motion vectors of.
7203 Available flags for @var{frame_type} are:
7207 intra-coded frames (I-frames)
7209 predicted frames (P-frames)
7211 bi-directionally predicted frames (B-frames)
7215 @subsection Examples
7219 Visualize forward predicted MVs of all frames using @command{ffplay}:
7221 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
7225 Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
7227 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
7231 @section colorbalance
7232 Modify intensity of primary colors (red, green and blue) of input frames.
7234 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
7235 regions for the red-cyan, green-magenta or blue-yellow balance.
7237 A positive adjustment value shifts the balance towards the primary color, a negative
7238 value towards the complementary color.
7240 The filter accepts the following options:
7246 Adjust red, green and blue shadows (darkest pixels).
7251 Adjust red, green and blue midtones (medium pixels).
7256 Adjust red, green and blue highlights (brightest pixels).
7258 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
7261 Preserve lightness when changing color balance. Default is disabled.
7264 @subsection Examples
7268 Add red color cast to shadows:
7274 @subsection Commands
7276 This filter supports the all above options as @ref{commands}.
7278 @section colorchannelmixer
7280 Adjust video input frames by re-mixing color channels.
7282 This filter modifies a color channel by adding the values associated to
7283 the other channels of the same pixels. For example if the value to
7284 modify is red, the output value will be:
7286 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
7289 The filter accepts the following options:
7296 Adjust contribution of input red, green, blue and alpha channels for output red channel.
7297 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
7303 Adjust contribution of input red, green, blue and alpha channels for output green channel.
7304 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
7310 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
7311 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
7317 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
7318 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
7320 Allowed ranges for options are @code{[-2.0, 2.0]}.
7323 @subsection Examples
7327 Convert source to grayscale:
7329 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
7332 Simulate sepia tones:
7334 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
7338 @subsection Commands
7340 This filter supports the all above options as @ref{commands}.
7343 RGB colorspace color keying.
7345 The filter accepts the following options:
7349 The color which will be replaced with transparency.
7352 Similarity percentage with the key color.
7354 0.01 matches only the exact key color, while 1.0 matches everything.
7359 0.0 makes pixels either fully transparent, or not transparent at all.
7361 Higher values result in semi-transparent pixels, with a higher transparency
7362 the more similar the pixels color is to the key color.
7365 @subsection Examples
7369 Make every green pixel in the input image transparent:
7371 ffmpeg -i input.png -vf colorkey=green out.png
7375 Overlay a greenscreen-video on top of a static background image.
7377 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
7381 @subsection Commands
7382 This filter supports same @ref{commands} as options.
7383 The command accepts the same syntax of the corresponding option.
7385 If the specified expression is not valid, it is kept at its current
7389 Remove all color information for all RGB colors except for certain one.
7391 The filter accepts the following options:
7395 The color which will not be replaced with neutral gray.
7398 Similarity percentage with the above color.
7399 0.01 matches only the exact key color, while 1.0 matches everything.
7402 Blend percentage. 0.0 makes pixels fully gray.
7403 Higher values result in more preserved color.
7406 @subsection Commands
7407 This filter supports same @ref{commands} as options.
7408 The command accepts the same syntax of the corresponding option.
7410 If the specified expression is not valid, it is kept at its current
7413 @section colorlevels
7415 Adjust video input frames using levels.
7417 The filter accepts the following options:
7424 Adjust red, green, blue and alpha input black point.
7425 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
7431 Adjust red, green, blue and alpha input white point.
7432 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
7434 Input levels are used to lighten highlights (bright tones), darken shadows
7435 (dark tones), change the balance of bright and dark tones.
7441 Adjust red, green, blue and alpha output black point.
7442 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
7448 Adjust red, green, blue and alpha output white point.
7449 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
7451 Output levels allows manual selection of a constrained output level range.
7454 @subsection Examples
7458 Make video output darker:
7460 colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
7466 colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
7470 Make video output lighter:
7472 colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
7476 Increase brightness:
7478 colorlevels=romin=0.5:gomin=0.5:bomin=0.5
7482 @subsection Commands
7484 This filter supports the all above options as @ref{commands}.
7486 @section colormatrix
7488 Convert color matrix.
7490 The filter accepts the following options:
7495 Specify the source and destination color matrix. Both values must be
7498 The accepted values are:
7526 For example to convert from BT.601 to SMPTE-240M, use the command:
7528 colormatrix=bt601:smpte240m
7533 Convert colorspace, transfer characteristics or color primaries.
7534 Input video needs to have an even size.
7536 The filter accepts the following options:
7541 Specify all color properties at once.
7543 The accepted values are:
7573 Specify output colorspace.
7575 The accepted values are:
7584 BT.470BG or BT.601-6 625
7587 SMPTE-170M or BT.601-6 525
7596 BT.2020 with non-constant luminance
7602 Specify output transfer characteristics.
7604 The accepted values are:
7616 Constant gamma of 2.2
7619 Constant gamma of 2.8
7622 SMPTE-170M, BT.601-6 625 or BT.601-6 525
7640 BT.2020 for 10-bits content
7643 BT.2020 for 12-bits content
7649 Specify output color primaries.
7651 The accepted values are:
7660 BT.470BG or BT.601-6 625
7663 SMPTE-170M or BT.601-6 525
7687 Specify output color range.
7689 The accepted values are:
7692 TV (restricted) range
7695 MPEG (restricted) range
7706 Specify output color format.
7708 The accepted values are:
7711 YUV 4:2:0 planar 8-bits
7714 YUV 4:2:0 planar 10-bits
7717 YUV 4:2:0 planar 12-bits
7720 YUV 4:2:2 planar 8-bits
7723 YUV 4:2:2 planar 10-bits
7726 YUV 4:2:2 planar 12-bits
7729 YUV 4:4:4 planar 8-bits
7732 YUV 4:4:4 planar 10-bits
7735 YUV 4:4:4 planar 12-bits
7740 Do a fast conversion, which skips gamma/primary correction. This will take
7741 significantly less CPU, but will be mathematically incorrect. To get output
7742 compatible with that produced by the colormatrix filter, use fast=1.
7745 Specify dithering mode.
7747 The accepted values are:
7753 Floyd-Steinberg dithering
7757 Whitepoint adaptation mode.
7759 The accepted values are:
7762 Bradford whitepoint adaptation
7765 von Kries whitepoint adaptation
7768 identity whitepoint adaptation (i.e. no whitepoint adaptation)
7772 Override all input properties at once. Same accepted values as @ref{all}.
7775 Override input colorspace. Same accepted values as @ref{space}.
7778 Override input color primaries. Same accepted values as @ref{primaries}.
7781 Override input transfer characteristics. Same accepted values as @ref{trc}.
7784 Override input color range. Same accepted values as @ref{range}.
7788 The filter converts the transfer characteristics, color space and color
7789 primaries to the specified user values. The output value, if not specified,
7790 is set to a default value based on the "all" property. If that property is
7791 also not specified, the filter will log an error. The output color range and
7792 format default to the same value as the input color range and format. The
7793 input transfer characteristics, color space, color primaries and color range
7794 should be set on the input data. If any of these are missing, the filter will
7795 log an error and no conversion will take place.
7797 For example to convert the input to SMPTE-240M, use the command:
7799 colorspace=smpte240m
7802 @section convolution
7804 Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
7806 The filter accepts the following options:
7813 Set matrix for each plane.
7814 Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode,
7815 and from 1 to 49 odd number of signed integers in @var{row} mode.
7821 Set multiplier for calculated value for each plane.
7822 If unset or 0, it will be sum of all matrix elements.
7828 Set bias for each plane. This value is added to the result of the multiplication.
7829 Useful for making the overall image brighter or darker. Default is 0.0.
7835 Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}.
7836 Default is @var{square}.
7839 @subsection Examples
7845 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"
7851 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"
7857 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"
7863 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"
7867 Apply laplacian edge detector which includes diagonals:
7869 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"
7875 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"
7881 Apply 2D convolution of video stream in frequency domain using second stream
7884 The filter accepts the following options:
7888 Set which planes to process.
7891 Set which impulse video frames will be processed, can be @var{first}
7892 or @var{all}. Default is @var{all}.
7895 The @code{convolve} filter also supports the @ref{framesync} options.
7899 Copy the input video source unchanged to the output. This is mainly useful for
7904 Video filtering on GPU using Apple's CoreImage API on OSX.
7906 Hardware acceleration is based on an OpenGL context. Usually, this means it is
7907 processed by video hardware. However, software-based OpenGL implementations
7908 exist which means there is no guarantee for hardware processing. It depends on
7911 There are many filters and image generators provided by Apple that come with a
7912 large variety of options. The filter has to be referenced by its name along
7915 The coreimage filter accepts the following options:
7918 List all available filters and generators along with all their respective
7919 options as well as possible minimum and maximum values along with the default
7926 Specify all filters by their respective name and options.
7927 Use @var{list_filters} to determine all valid filter names and options.
7928 Numerical options are specified by a float value and are automatically clamped
7929 to their respective value range. Vector and color options have to be specified
7930 by a list of space separated float values. Character escaping has to be done.
7931 A special option name @code{default} is available to use default options for a
7934 It is required to specify either @code{default} or at least one of the filter options.
7935 All omitted options are used with their default values.
7936 The syntax of the filter string is as follows:
7938 filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
7942 Specify a rectangle where the output of the filter chain is copied into the
7943 input image. It is given by a list of space separated float values:
7945 output_rect=x\ y\ width\ height
7947 If not given, the output rectangle equals the dimensions of the input image.
7948 The output rectangle is automatically cropped at the borders of the input
7949 image. Negative values are valid for each component.
7951 output_rect=25\ 25\ 100\ 100
7955 Several filters can be chained for successive processing without GPU-HOST
7956 transfers allowing for fast processing of complex filter chains.
7957 Currently, only filters with zero (generators) or exactly one (filters) input
7958 image and one output image are supported. Also, transition filters are not yet
7961 Some filters generate output images with additional padding depending on the
7962 respective filter kernel. The padding is automatically removed to ensure the
7963 filter output has the same size as the input image.
7965 For image generators, the size of the output image is determined by the
7966 previous output image of the filter chain or the input image of the whole
7967 filterchain, respectively. The generators do not use the pixel information of
7968 this image to generate their output. However, the generated output is
7969 blended onto this image, resulting in partial or complete coverage of the
7972 The @ref{coreimagesrc} video source can be used for generating input images
7973 which are directly fed into the filter chain. By using it, providing input
7974 images by another video source or an input video is not required.
7976 @subsection Examples
7981 List all filters available:
7983 coreimage=list_filters=true
7987 Use the CIBoxBlur filter with default options to blur an image:
7989 coreimage=filter=CIBoxBlur@@default
7993 Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
7994 its center at 100x100 and a radius of 50 pixels:
7996 coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
8000 Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
8001 given as complete and escaped command-line for Apple's standard bash shell:
8003 ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
8009 Cover a rectangular object
8011 It accepts the following options:
8015 Filepath of the optional cover image, needs to be in yuv420.
8020 It accepts the following values:
8023 cover it by the supplied image
8025 cover it by interpolating the surrounding pixels
8028 Default value is @var{blur}.
8031 @subsection Examples
8035 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
8037 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
8043 Crop the input video to given dimensions.
8045 It accepts the following parameters:
8049 The width of the output video. It defaults to @code{iw}.
8050 This expression is evaluated only once during the filter
8051 configuration, or when the @samp{w} or @samp{out_w} command is sent.
8054 The height of the output video. It defaults to @code{ih}.
8055 This expression is evaluated only once during the filter
8056 configuration, or when the @samp{h} or @samp{out_h} command is sent.
8059 The horizontal position, in the input video, of the left edge of the output
8060 video. It defaults to @code{(in_w-out_w)/2}.
8061 This expression is evaluated per-frame.
8064 The vertical position, in the input video, of the top edge of the output video.
8065 It defaults to @code{(in_h-out_h)/2}.
8066 This expression is evaluated per-frame.
8069 If set to 1 will force the output display aspect ratio
8070 to be the same of the input, by changing the output sample aspect
8071 ratio. It defaults to 0.
8074 Enable exact cropping. If enabled, subsampled videos will be cropped at exact
8075 width/height/x/y as specified and will not be rounded to nearest smaller value.
8079 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
8080 expressions containing the following constants:
8085 The computed values for @var{x} and @var{y}. They are evaluated for
8090 The input width and height.
8094 These are the same as @var{in_w} and @var{in_h}.
8098 The output (cropped) width and height.
8102 These are the same as @var{out_w} and @var{out_h}.
8105 same as @var{iw} / @var{ih}
8108 input sample aspect ratio
8111 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
8115 horizontal and vertical chroma subsample values. For example for the
8116 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8119 The number of the input frame, starting from 0.
8122 the position in the file of the input frame, NAN if unknown
8125 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
8129 The expression for @var{out_w} may depend on the value of @var{out_h},
8130 and the expression for @var{out_h} may depend on @var{out_w}, but they
8131 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
8132 evaluated after @var{out_w} and @var{out_h}.
8134 The @var{x} and @var{y} parameters specify the expressions for the
8135 position of the top-left corner of the output (non-cropped) area. They
8136 are evaluated for each frame. If the evaluated value is not valid, it
8137 is approximated to the nearest valid value.
8139 The expression for @var{x} may depend on @var{y}, and the expression
8140 for @var{y} may depend on @var{x}.
8142 @subsection Examples
8146 Crop area with size 100x100 at position (12,34).
8151 Using named options, the example above becomes:
8153 crop=w=100:h=100:x=12:y=34
8157 Crop the central input area with size 100x100:
8163 Crop the central input area with size 2/3 of the input video:
8165 crop=2/3*in_w:2/3*in_h
8169 Crop the input video central square:
8176 Delimit the rectangle with the top-left corner placed at position
8177 100:100 and the right-bottom corner corresponding to the right-bottom
8178 corner of the input image.
8180 crop=in_w-100:in_h-100:100:100
8184 Crop 10 pixels from the left and right borders, and 20 pixels from
8185 the top and bottom borders
8187 crop=in_w-2*10:in_h-2*20
8191 Keep only the bottom right quarter of the input image:
8193 crop=in_w/2:in_h/2:in_w/2:in_h/2
8197 Crop height for getting Greek harmony:
8199 crop=in_w:1/PHI*in_w
8203 Apply trembling effect:
8205 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)
8209 Apply erratic camera effect depending on timestamp:
8211 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)"
8215 Set x depending on the value of y:
8217 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
8221 @subsection Commands
8223 This filter supports the following commands:
8229 Set width/height of the output video and the horizontal/vertical position
8231 The command accepts the same syntax of the corresponding option.
8233 If the specified expression is not valid, it is kept at its current
8239 Auto-detect the crop size.
8241 It calculates the necessary cropping parameters and prints the
8242 recommended parameters via the logging system. The detected dimensions
8243 correspond to the non-black area of the input video.
8245 It accepts the following parameters:
8250 Set higher black value threshold, which can be optionally specified
8251 from nothing (0) to everything (255 for 8-bit based formats). An intensity
8252 value greater to the set value is considered non-black. It defaults to 24.
8253 You can also specify a value between 0.0 and 1.0 which will be scaled depending
8254 on the bitdepth of the pixel format.
8257 The value which the width/height should be divisible by. It defaults to
8258 16. The offset is automatically adjusted to center the video. Use 2 to
8259 get only even dimensions (needed for 4:2:2 video). 16 is best when
8260 encoding to most video codecs.
8262 @item reset_count, reset
8263 Set the counter that determines after how many frames cropdetect will
8264 reset the previously detected largest video area and start over to
8265 detect the current optimal crop area. Default value is 0.
8267 This can be useful when channel logos distort the video area. 0
8268 indicates 'never reset', and returns the largest area encountered during
8275 Delay video filtering until a given wallclock timestamp. The filter first
8276 passes on @option{preroll} amount of frames, then it buffers at most
8277 @option{buffer} amount of frames and waits for the cue. After reaching the cue
8278 it forwards the buffered frames and also any subsequent frames coming in its
8281 The filter can be used synchronize the output of multiple ffmpeg processes for
8282 realtime output devices like decklink. By putting the delay in the filtering
8283 chain and pre-buffering frames the process can pass on data to output almost
8284 immediately after the target wallclock timestamp is reached.
8286 Perfect frame accuracy cannot be guaranteed, but the result is good enough for
8292 The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0.
8295 The duration of content to pass on as preroll expressed in seconds. Default is 0.
8298 The maximum duration of content to buffer before waiting for the cue expressed
8299 in seconds. Default is 0.
8306 Apply color adjustments using curves.
8308 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
8309 component (red, green and blue) has its values defined by @var{N} key points
8310 tied from each other using a smooth curve. The x-axis represents the pixel
8311 values from the input frame, and the y-axis the new pixel values to be set for
8314 By default, a component curve is defined by the two points @var{(0;0)} and
8315 @var{(1;1)}. This creates a straight line where each original pixel value is
8316 "adjusted" to its own value, which means no change to the image.
8318 The filter allows you to redefine these two points and add some more. A new
8319 curve (using a natural cubic spline interpolation) will be define to pass
8320 smoothly through all these new coordinates. The new defined points needs to be
8321 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
8322 be in the @var{[0;1]} interval. If the computed curves happened to go outside
8323 the vector spaces, the values will be clipped accordingly.
8325 The filter accepts the following options:
8329 Select one of the available color presets. This option can be used in addition
8330 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
8331 options takes priority on the preset values.
8332 Available presets are:
8335 @item color_negative
8338 @item increase_contrast
8340 @item linear_contrast
8341 @item medium_contrast
8343 @item strong_contrast
8346 Default is @code{none}.
8348 Set the master key points. These points will define a second pass mapping. It
8349 is sometimes called a "luminance" or "value" mapping. It can be used with
8350 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
8351 post-processing LUT.
8353 Set the key points for the red component.
8355 Set the key points for the green component.
8357 Set the key points for the blue component.
8359 Set the key points for all components (not including master).
8360 Can be used in addition to the other key points component
8361 options. In this case, the unset component(s) will fallback on this
8362 @option{all} setting.
8364 Specify a Photoshop curves file (@code{.acv}) to import the settings from.
8366 Save Gnuplot script of the curves in specified file.
8369 To avoid some filtergraph syntax conflicts, each key points list need to be
8370 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
8372 @subsection Examples
8376 Increase slightly the middle level of blue:
8378 curves=blue='0/0 0.5/0.58 1/1'
8384 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'
8386 Here we obtain the following coordinates for each components:
8389 @code{(0;0.11) (0.42;0.51) (1;0.95)}
8391 @code{(0;0) (0.50;0.48) (1;1)}
8393 @code{(0;0.22) (0.49;0.44) (1;0.80)}
8397 The previous example can also be achieved with the associated built-in preset:
8399 curves=preset=vintage
8409 Use a Photoshop preset and redefine the points of the green component:
8411 curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
8415 Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
8416 and @command{gnuplot}:
8418 ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
8419 gnuplot -p /tmp/curves.plt
8425 Video data analysis filter.
8427 This filter shows hexadecimal pixel values of part of video.
8429 The filter accepts the following options:
8433 Set output video size.
8436 Set x offset from where to pick pixels.
8439 Set y offset from where to pick pixels.
8442 Set scope mode, can be one of the following:
8445 Draw hexadecimal pixel values with white color on black background.
8448 Draw hexadecimal pixel values with input video pixel color on black
8452 Draw hexadecimal pixel values on color background picked from input video,
8453 the text color is picked in such way so its always visible.
8457 Draw rows and columns numbers on left and top of video.
8460 Set background opacity.
8463 Set display number format. Can be @code{hex}, or @code{dec}. Default is @code{hex}.
8468 Denoise frames using 2D DCT (frequency domain filtering).
8470 This filter is not designed for real time.
8472 The filter accepts the following options:
8476 Set the noise sigma constant.
8478 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
8479 coefficient (absolute value) below this threshold with be dropped.
8481 If you need a more advanced filtering, see @option{expr}.
8483 Default is @code{0}.
8486 Set number overlapping pixels for each block. Since the filter can be slow, you
8487 may want to reduce this value, at the cost of a less effective filter and the
8488 risk of various artefacts.
8490 If the overlapping value doesn't permit processing the whole input width or
8491 height, a warning will be displayed and according borders won't be denoised.
8493 Default value is @var{blocksize}-1, which is the best possible setting.
8496 Set the coefficient factor expression.
8498 For each coefficient of a DCT block, this expression will be evaluated as a
8499 multiplier value for the coefficient.
8501 If this is option is set, the @option{sigma} option will be ignored.
8503 The absolute value of the coefficient can be accessed through the @var{c}
8507 Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
8508 @var{blocksize}, which is the width and height of the processed blocks.
8510 The default value is @var{3} (8x8) and can be raised to @var{4} for a
8511 @var{blocksize} of 16x16. Note that changing this setting has huge consequences
8512 on the speed processing. Also, a larger block size does not necessarily means a
8516 @subsection Examples
8518 Apply a denoise with a @option{sigma} of @code{4.5}:
8523 The same operation can be achieved using the expression system:
8525 dctdnoiz=e='gte(c, 4.5*3)'
8528 Violent denoise using a block size of @code{16x16}:
8535 Remove banding artifacts from input video.
8536 It works by replacing banded pixels with average value of referenced pixels.
8538 The filter accepts the following options:
8545 Set banding detection threshold for each plane. Default is 0.02.
8546 Valid range is 0.00003 to 0.5.
8547 If difference between current pixel and reference pixel is less than threshold,
8548 it will be considered as banded.
8551 Banding detection range in pixels. Default is 16. If positive, random number
8552 in range 0 to set value will be used. If negative, exact absolute value
8554 The range defines square of four pixels around current pixel.
8557 Set direction in radians from which four pixel will be compared. If positive,
8558 random direction from 0 to set direction will be picked. If negative, exact of
8559 absolute value will be picked. For example direction 0, -PI or -2*PI radians
8560 will pick only pixels on same row and -PI/2 will pick only pixels on same
8564 If enabled, current pixel is compared with average value of all four
8565 surrounding pixels. The default is enabled. If disabled current pixel is
8566 compared with all four surrounding pixels. The pixel is considered banded
8567 if only all four differences with surrounding pixels are less than threshold.
8570 If enabled, current pixel is changed if and only if all pixel components are banded,
8571 e.g. banding detection threshold is triggered for all color components.
8572 The default is disabled.
8577 Remove blocking artifacts from input video.
8579 The filter accepts the following options:
8583 Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}.
8584 This controls what kind of deblocking is applied.
8587 Set size of block, allowed range is from 4 to 512. Default is @var{8}.
8593 Set blocking detection thresholds. Allowed range is 0 to 1.
8594 Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest.
8595 Using higher threshold gives more deblocking strength.
8596 Setting @var{alpha} controls threshold detection at exact edge of block.
8597 Remaining options controls threshold detection near the edge. Each one for
8598 below/above or left/right. Setting any of those to @var{0} disables
8602 Set planes to filter. Default is to filter all available planes.
8605 @subsection Examples
8609 Deblock using weak filter and block size of 4 pixels.
8611 deblock=filter=weak:block=4
8615 Deblock using strong filter, block size of 4 pixels and custom thresholds for
8616 deblocking more edges.
8618 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
8622 Similar as above, but filter only first plane.
8624 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
8628 Similar as above, but filter only second and third plane.
8630 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
8637 Drop duplicated frames at regular intervals.
8639 The filter accepts the following options:
8643 Set the number of frames from which one will be dropped. Setting this to
8644 @var{N} means one frame in every batch of @var{N} frames will be dropped.
8645 Default is @code{5}.
8648 Set the threshold for duplicate detection. If the difference metric for a frame
8649 is less than or equal to this value, then it is declared as duplicate. Default
8653 Set scene change threshold. Default is @code{15}.
8657 Set the size of the x and y-axis blocks used during metric calculations.
8658 Larger blocks give better noise suppression, but also give worse detection of
8659 small movements. Must be a power of two. Default is @code{32}.
8662 Mark main input as a pre-processed input and activate clean source input
8663 stream. This allows the input to be pre-processed with various filters to help
8664 the metrics calculation while keeping the frame selection lossless. When set to
8665 @code{1}, the first stream is for the pre-processed input, and the second
8666 stream is the clean source from where the kept frames are chosen. Default is
8670 Set whether or not chroma is considered in the metric calculations. Default is
8676 Apply 2D deconvolution of video stream in frequency domain using second stream
8679 The filter accepts the following options:
8683 Set which planes to process.
8686 Set which impulse video frames will be processed, can be @var{first}
8687 or @var{all}. Default is @var{all}.
8690 Set noise when doing divisions. Default is @var{0.0000001}. Useful when width
8691 and height are not same and not power of 2 or if stream prior to convolving
8695 The @code{deconvolve} filter also supports the @ref{framesync} options.
8699 Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video.
8701 It accepts the following options:
8705 Set mode of operation. Can be combination of @var{dotcrawl} for cross-luminance reduction and/or
8706 @var{rainbows} for cross-color reduction.
8709 Set spatial luma threshold. Lower values increases reduction of cross-luminance.
8712 Set tolerance for temporal luma. Higher values increases reduction of cross-luminance.
8715 Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color.
8718 Set temporal chroma threshold. Lower values increases reduction of cross-color.
8723 Apply deflate effect to the video.
8725 This filter replaces the pixel by the local(3x3) average by taking into account
8726 only values lower than the pixel.
8728 It accepts the following options:
8735 Limit the maximum change for each plane, default is 65535.
8736 If 0, plane will remain unchanged.
8739 @subsection Commands
8741 This filter supports the all above options as @ref{commands}.
8745 Remove temporal frame luminance variations.
8747 It accepts the following options:
8751 Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129.
8754 Set averaging mode to smooth temporal luminance variations.
8756 Available values are:
8781 Do not actually modify frame. Useful when one only wants metadata.
8786 Remove judder produced by partially interlaced telecined content.
8788 Judder can be introduced, for instance, by @ref{pullup} filter. If the original
8789 source was partially telecined content then the output of @code{pullup,dejudder}
8790 will have a variable frame rate. May change the recorded frame rate of the
8791 container. Aside from that change, this filter will not affect constant frame
8794 The option available in this filter is:
8798 Specify the length of the window over which the judder repeats.
8800 Accepts any integer greater than 1. Useful values are:
8804 If the original was telecined from 24 to 30 fps (Film to NTSC).
8807 If the original was telecined from 25 to 30 fps (PAL to NTSC).
8810 If a mixture of the two.
8813 The default is @samp{4}.
8818 Suppress a TV station logo by a simple interpolation of the surrounding
8819 pixels. Just set a rectangle covering the logo and watch it disappear
8820 (and sometimes something even uglier appear - your mileage may vary).
8822 It accepts the following parameters:
8827 Specify the top left corner coordinates of the logo. They must be
8832 Specify the width and height of the logo to clear. They must be
8836 Specify the thickness of the fuzzy edge of the rectangle (added to
8837 @var{w} and @var{h}). The default value is 1. This option is
8838 deprecated, setting higher values should no longer be necessary and
8842 When set to 1, a green rectangle is drawn on the screen to simplify
8843 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
8844 The default value is 0.
8846 The rectangle is drawn on the outermost pixels which will be (partly)
8847 replaced with interpolated values. The values of the next pixels
8848 immediately outside this rectangle in each direction will be used to
8849 compute the interpolated pixel values inside the rectangle.
8853 @subsection Examples
8857 Set a rectangle covering the area with top left corner coordinates 0,0
8858 and size 100x77, and a band of size 10:
8860 delogo=x=0:y=0:w=100:h=77:band=10
8867 Remove the rain in the input image/video by applying the derain methods based on
8868 convolutional neural networks. Supported models:
8872 Recurrent Squeeze-and-Excitation Context Aggregation Net (RESCAN).
8873 See @url{http://openaccess.thecvf.com/content_ECCV_2018/papers/Xia_Li_Recurrent_Squeeze-and-Excitation_Context_ECCV_2018_paper.pdf}.
8876 Training as well as model generation scripts are provided in
8877 the repository at @url{https://github.com/XueweiMeng/derain_filter.git}.
8879 Native model files (.model) can be generated from TensorFlow model
8880 files (.pb) by using tools/python/convert.py
8882 The filter accepts the following options:
8886 Specify which filter to use. This option accepts the following values:
8890 Derain filter. To conduct derain filter, you need to use a derain model.
8893 Dehaze filter. To conduct dehaze filter, you need to use a dehaze model.
8895 Default value is @samp{derain}.
8898 Specify which DNN backend to use for model loading and execution. This option accepts
8899 the following values:
8903 Native implementation of DNN loading and execution.
8906 TensorFlow backend. To enable this backend you
8907 need to install the TensorFlow for C library (see
8908 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
8909 @code{--enable-libtensorflow}
8911 Default value is @samp{native}.
8914 Set path to model file specifying network architecture and its parameters.
8915 Note that different backends use different file formats. TensorFlow and native
8916 backend can load files for only its format.
8921 Attempt to fix small changes in horizontal and/or vertical shift. This
8922 filter helps remove camera shake from hand-holding a camera, bumping a
8923 tripod, moving on a vehicle, etc.
8925 The filter accepts the following options:
8933 Specify a rectangular area where to limit the search for motion
8935 If desired the search for motion vectors can be limited to a
8936 rectangular area of the frame defined by its top left corner, width
8937 and height. These parameters have the same meaning as the drawbox
8938 filter which can be used to visualise the position of the bounding
8941 This is useful when simultaneous movement of subjects within the frame
8942 might be confused for camera motion by the motion vector search.
8944 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
8945 then the full frame is used. This allows later options to be set
8946 without specifying the bounding box for the motion vector search.
8948 Default - search the whole frame.
8952 Specify the maximum extent of movement in x and y directions in the
8953 range 0-64 pixels. Default 16.
8956 Specify how to generate pixels to fill blanks at the edge of the
8957 frame. Available values are:
8960 Fill zeroes at blank locations
8962 Original image at blank locations
8964 Extruded edge value at blank locations
8966 Mirrored edge at blank locations
8968 Default value is @samp{mirror}.
8971 Specify the blocksize to use for motion search. Range 4-128 pixels,
8975 Specify the contrast threshold for blocks. Only blocks with more than
8976 the specified contrast (difference between darkest and lightest
8977 pixels) will be considered. Range 1-255, default 125.
8980 Specify the search strategy. Available values are:
8983 Set exhaustive search
8985 Set less exhaustive search.
8987 Default value is @samp{exhaustive}.
8990 If set then a detailed log of the motion search is written to the
8997 Remove unwanted contamination of foreground colors, caused by reflected color of
8998 greenscreen or bluescreen.
9000 This filter accepts the following options:
9004 Set what type of despill to use.
9007 Set how spillmap will be generated.
9010 Set how much to get rid of still remaining spill.
9013 Controls amount of red in spill area.
9016 Controls amount of green in spill area.
9017 Should be -1 for greenscreen.
9020 Controls amount of blue in spill area.
9021 Should be -1 for bluescreen.
9024 Controls brightness of spill area, preserving colors.
9027 Modify alpha from generated spillmap.
9032 Apply an exact inverse of the telecine operation. It requires a predefined
9033 pattern specified using the pattern option which must be the same as that passed
9034 to the telecine filter.
9036 This filter accepts the following options:
9045 The default value is @code{top}.
9049 A string of numbers representing the pulldown pattern you wish to apply.
9050 The default value is @code{23}.
9053 A number representing position of the first frame with respect to the telecine
9054 pattern. This is to be used if the stream is cut. The default value is @code{0}.
9059 Apply dilation effect to the video.
9061 This filter replaces the pixel by the local(3x3) maximum.
9063 It accepts the following options:
9070 Limit the maximum change for each plane, default is 65535.
9071 If 0, plane will remain unchanged.
9074 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
9077 Flags to local 3x3 coordinates maps like this:
9084 @subsection Commands
9086 This filter supports the all above options as @ref{commands}.
9090 Displace pixels as indicated by second and third input stream.
9092 It takes three input streams and outputs one stream, the first input is the
9093 source, and second and third input are displacement maps.
9095 The second input specifies how much to displace pixels along the
9096 x-axis, while the third input specifies how much to displace pixels
9098 If one of displacement map streams terminates, last frame from that
9099 displacement map will be used.
9101 Note that once generated, displacements maps can be reused over and over again.
9103 A description of the accepted options follows.
9107 Set displace behavior for pixels that are out of range.
9109 Available values are:
9112 Missing pixels are replaced by black pixels.
9115 Adjacent pixels will spread out to replace missing pixels.
9118 Out of range pixels are wrapped so they point to pixels of other side.
9121 Out of range pixels will be replaced with mirrored pixels.
9123 Default is @samp{smear}.
9127 @subsection Examples
9131 Add ripple effect to rgb input of video size hd720:
9133 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
9137 Add wave effect to rgb input of video size hd720:
9139 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
9143 @section dnn_processing
9145 Do image processing with deep neural networks. It works together with another filter
9146 which converts the pixel format of the Frame to what the dnn network requires.
9148 The filter accepts the following options:
9152 Specify which DNN backend to use for model loading and execution. This option accepts
9153 the following values:
9157 Native implementation of DNN loading and execution.
9160 TensorFlow backend. To enable this backend you
9161 need to install the TensorFlow for C library (see
9162 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
9163 @code{--enable-libtensorflow}
9166 Default value is @samp{native}.
9169 Set path to model file specifying network architecture and its parameters.
9170 Note that different backends use different file formats. TensorFlow and native
9171 backend can load files for only its format.
9173 Native model file (.model) can be generated from TensorFlow model file (.pb) by using tools/python/convert.py
9176 Set the input name of the dnn network.
9179 Set the output name of the dnn network.
9185 Halve the red channle of the frame with format rgb24:
9187 ffmpeg -i input.jpg -vf format=rgb24,dnn_processing=model=halve_first_channel.model:input=dnn_in:output=dnn_out:dnn_backend=native out.native.png
9191 Halve the pixel value of the frame with format gray32f:
9193 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
9200 Draw a colored box on the input image.
9202 It accepts the following parameters:
9207 The expressions which specify the top left corner coordinates of the box. It defaults to 0.
9211 The expressions which specify the width and height of the box; if 0 they are interpreted as
9212 the input width and height. It defaults to 0.
9215 Specify the color of the box to write. For the general syntax of this option,
9216 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
9217 value @code{invert} is used, the box edge color is the same as the
9218 video with inverted luma.
9221 The expression which sets the thickness of the box edge.
9222 A value of @code{fill} will create a filled box. Default value is @code{3}.
9224 See below for the list of accepted constants.
9227 Applicable if the input has alpha. With value @code{1}, the pixels of the painted box
9228 will overwrite the video's color and alpha pixels.
9229 Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact.
9232 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
9233 following constants:
9237 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
9241 horizontal and vertical chroma subsample values. For example for the
9242 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9246 The input width and height.
9249 The input sample aspect ratio.
9253 The x and y offset coordinates where the box is drawn.
9257 The width and height of the drawn box.
9260 The thickness of the drawn box.
9262 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
9263 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
9267 @subsection Examples
9271 Draw a black box around the edge of the input image:
9277 Draw a box with color red and an opacity of 50%:
9279 drawbox=10:20:200:60:red@@0.5
9282 The previous example can be specified as:
9284 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
9288 Fill the box with pink color:
9290 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill
9294 Draw a 2-pixel red 2.40:1 mask:
9296 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
9300 @subsection Commands
9301 This filter supports same commands as options.
9302 The command accepts the same syntax of the corresponding option.
9304 If the specified expression is not valid, it is kept at its current
9309 Draw a graph using input video metadata.
9311 It accepts the following parameters:
9315 Set 1st frame metadata key from which metadata values will be used to draw a graph.
9318 Set 1st foreground color expression.
9321 Set 2nd frame metadata key from which metadata values will be used to draw a graph.
9324 Set 2nd foreground color expression.
9327 Set 3rd frame metadata key from which metadata values will be used to draw a graph.
9330 Set 3rd foreground color expression.
9333 Set 4th frame metadata key from which metadata values will be used to draw a graph.
9336 Set 4th foreground color expression.
9339 Set minimal value of metadata value.
9342 Set maximal value of metadata value.
9345 Set graph background color. Default is white.
9350 Available values for mode is:
9357 Default is @code{line}.
9362 Available values for slide is:
9365 Draw new frame when right border is reached.
9368 Replace old columns with new ones.
9371 Scroll from right to left.
9374 Scroll from left to right.
9377 Draw single picture.
9380 Default is @code{frame}.
9383 Set size of graph video. For the syntax of this option, check the
9384 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
9385 The default value is @code{900x256}.
9388 Set the output frame rate. Default value is @code{25}.
9390 The foreground color expressions can use the following variables:
9393 Minimal value of metadata value.
9396 Maximal value of metadata value.
9399 Current metadata key value.
9402 The color is defined as 0xAABBGGRR.
9405 Example using metadata from @ref{signalstats} filter:
9407 signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
9410 Example using metadata from @ref{ebur128} filter:
9412 ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
9417 Draw a grid on the input image.
9419 It accepts the following parameters:
9424 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
9428 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
9429 input width and height, respectively, minus @code{thickness}, so image gets
9430 framed. Default to 0.
9433 Specify the color of the grid. For the general syntax of this option,
9434 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
9435 value @code{invert} is used, the grid color is the same as the
9436 video with inverted luma.
9439 The expression which sets the thickness of the grid line. Default value is @code{1}.
9441 See below for the list of accepted constants.
9444 Applicable if the input has alpha. With @code{1} the pixels of the painted grid
9445 will overwrite the video's color and alpha pixels.
9446 Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact.
9449 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
9450 following constants:
9454 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
9458 horizontal and vertical chroma subsample values. For example for the
9459 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9463 The input grid cell width and height.
9466 The input sample aspect ratio.
9470 The x and y coordinates of some point of grid intersection (meant to configure offset).
9474 The width and height of the drawn cell.
9477 The thickness of the drawn cell.
9479 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
9480 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
9484 @subsection Examples
9488 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
9490 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
9494 Draw a white 3x3 grid with an opacity of 50%:
9496 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
9500 @subsection Commands
9501 This filter supports same commands as options.
9502 The command accepts the same syntax of the corresponding option.
9504 If the specified expression is not valid, it is kept at its current
9510 Draw a text string or text from a specified file on top of a video, using the
9511 libfreetype library.
9513 To enable compilation of this filter, you need to configure FFmpeg with
9514 @code{--enable-libfreetype}.
9515 To enable default font fallback and the @var{font} option you need to
9516 configure FFmpeg with @code{--enable-libfontconfig}.
9517 To enable the @var{text_shaping} option, you need to configure FFmpeg with
9518 @code{--enable-libfribidi}.
9522 It accepts the following parameters:
9527 Used to draw a box around text using the background color.
9528 The value must be either 1 (enable) or 0 (disable).
9529 The default value of @var{box} is 0.
9532 Set the width of the border to be drawn around the box using @var{boxcolor}.
9533 The default value of @var{boxborderw} is 0.
9536 The color to be used for drawing box around text. For the syntax of this
9537 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9539 The default value of @var{boxcolor} is "white".
9542 Set the line spacing in pixels of the border to be drawn around the box using @var{box}.
9543 The default value of @var{line_spacing} is 0.
9546 Set the width of the border to be drawn around the text using @var{bordercolor}.
9547 The default value of @var{borderw} is 0.
9550 Set the color to be used for drawing border around text. For the syntax of this
9551 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9553 The default value of @var{bordercolor} is "black".
9556 Select how the @var{text} is expanded. Can be either @code{none},
9557 @code{strftime} (deprecated) or
9558 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
9562 Set a start time for the count. Value is in microseconds. Only applied
9563 in the deprecated strftime expansion mode. To emulate in normal expansion
9564 mode use the @code{pts} function, supplying the start time (in seconds)
9565 as the second argument.
9568 If true, check and fix text coords to avoid clipping.
9571 The color to be used for drawing fonts. For the syntax of this option, check
9572 the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9574 The default value of @var{fontcolor} is "black".
9576 @item fontcolor_expr
9577 String which is expanded the same way as @var{text} to obtain dynamic
9578 @var{fontcolor} value. By default this option has empty value and is not
9579 processed. When this option is set, it overrides @var{fontcolor} option.
9582 The font family to be used for drawing text. By default Sans.
9585 The font file to be used for drawing text. The path must be included.
9586 This parameter is mandatory if the fontconfig support is disabled.
9589 Draw the text applying alpha blending. The value can
9590 be a number between 0.0 and 1.0.
9591 The expression accepts the same variables @var{x, y} as well.
9592 The default value is 1.
9593 Please see @var{fontcolor_expr}.
9596 The font size to be used for drawing text.
9597 The default value of @var{fontsize} is 16.
9600 If set to 1, attempt to shape the text (for example, reverse the order of
9601 right-to-left text and join Arabic characters) before drawing it.
9602 Otherwise, just draw the text exactly as given.
9603 By default 1 (if supported).
9606 The flags to be used for loading the fonts.
9608 The flags map the corresponding flags supported by libfreetype, and are
9609 a combination of the following values:
9616 @item vertical_layout
9617 @item force_autohint
9620 @item ignore_global_advance_width
9622 @item ignore_transform
9628 Default value is "default".
9630 For more information consult the documentation for the FT_LOAD_*
9634 The color to be used for drawing a shadow behind the drawn text. For the
9635 syntax of this option, check the @ref{color syntax,,"Color" section in the
9636 ffmpeg-utils manual,ffmpeg-utils}.
9638 The default value of @var{shadowcolor} is "black".
9642 The x and y offsets for the text shadow position with respect to the
9643 position of the text. They can be either positive or negative
9644 values. The default value for both is "0".
9647 The starting frame number for the n/frame_num variable. The default value
9651 The size in number of spaces to use for rendering the tab.
9655 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
9656 format. It can be used with or without text parameter. @var{timecode_rate}
9657 option must be specified.
9659 @item timecode_rate, rate, r
9660 Set the timecode frame rate (timecode only). Value will be rounded to nearest
9661 integer. Minimum value is "1".
9662 Drop-frame timecode is supported for frame rates 30 & 60.
9665 If set to 1, the output of the timecode option will wrap around at 24 hours.
9666 Default is 0 (disabled).
9669 The text string to be drawn. The text must be a sequence of UTF-8
9671 This parameter is mandatory if no file is specified with the parameter
9675 A text file containing text to be drawn. The text must be a sequence
9676 of UTF-8 encoded characters.
9678 This parameter is mandatory if no text string is specified with the
9679 parameter @var{text}.
9681 If both @var{text} and @var{textfile} are specified, an error is thrown.
9684 If set to 1, the @var{textfile} will be reloaded before each frame.
9685 Be sure to update it atomically, or it may be read partially, or even fail.
9689 The expressions which specify the offsets where text will be drawn
9690 within the video frame. They are relative to the top/left border of the
9693 The default value of @var{x} and @var{y} is "0".
9695 See below for the list of accepted constants and functions.
9698 The parameters for @var{x} and @var{y} are expressions containing the
9699 following constants and functions:
9703 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
9707 horizontal and vertical chroma subsample values. For example for the
9708 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9711 the height of each text line
9719 @item max_glyph_a, ascent
9720 the maximum distance from the baseline to the highest/upper grid
9721 coordinate used to place a glyph outline point, for all the rendered
9723 It is a positive value, due to the grid's orientation with the Y axis
9726 @item max_glyph_d, descent
9727 the maximum distance from the baseline to the lowest grid coordinate
9728 used to place a glyph outline point, for all the rendered glyphs.
9729 This is a negative value, due to the grid's orientation, with the Y axis
9733 maximum glyph height, that is the maximum height for all the glyphs
9734 contained in the rendered text, it is equivalent to @var{ascent} -
9738 maximum glyph width, that is the maximum width for all the glyphs
9739 contained in the rendered text
9742 the number of input frame, starting from 0
9744 @item rand(min, max)
9745 return a random number included between @var{min} and @var{max}
9748 The input sample aspect ratio.
9751 timestamp expressed in seconds, NAN if the input timestamp is unknown
9754 the height of the rendered text
9757 the width of the rendered text
9761 the x and y offset coordinates where the text is drawn.
9763 These parameters allow the @var{x} and @var{y} expressions to refer
9764 to each other, so you can for example specify @code{y=x/dar}.
9767 A one character description of the current frame's picture type.
9770 The current packet's position in the input file or stream
9771 (in bytes, from the start of the input). A value of -1 indicates
9772 this info is not available.
9775 The current packet's duration, in seconds.
9778 The current packet's size (in bytes).
9781 @anchor{drawtext_expansion}
9782 @subsection Text expansion
9784 If @option{expansion} is set to @code{strftime},
9785 the filter recognizes strftime() sequences in the provided text and
9786 expands them accordingly. Check the documentation of strftime(). This
9787 feature is deprecated.
9789 If @option{expansion} is set to @code{none}, the text is printed verbatim.
9791 If @option{expansion} is set to @code{normal} (which is the default),
9792 the following expansion mechanism is used.
9794 The backslash character @samp{\}, followed by any character, always expands to
9795 the second character.
9797 Sequences of the form @code{%@{...@}} are expanded. The text between the
9798 braces is a function name, possibly followed by arguments separated by ':'.
9799 If the arguments contain special characters or delimiters (':' or '@}'),
9800 they should be escaped.
9802 Note that they probably must also be escaped as the value for the
9803 @option{text} option in the filter argument string and as the filter
9804 argument in the filtergraph description, and possibly also for the shell,
9805 that makes up to four levels of escaping; using a text file avoids these
9808 The following functions are available:
9813 The expression evaluation result.
9815 It must take one argument specifying the expression to be evaluated,
9816 which accepts the same constants and functions as the @var{x} and
9817 @var{y} values. Note that not all constants should be used, for
9818 example the text size is not known when evaluating the expression, so
9819 the constants @var{text_w} and @var{text_h} will have an undefined
9822 @item expr_int_format, eif
9823 Evaluate the expression's value and output as formatted integer.
9825 The first argument is the expression to be evaluated, just as for the @var{expr} function.
9826 The second argument specifies the output format. Allowed values are @samp{x},
9827 @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
9828 @code{printf} function.
9829 The third parameter is optional and sets the number of positions taken by the output.
9830 It can be used to add padding with zeros from the left.
9833 The time at which the filter is running, expressed in UTC.
9834 It can accept an argument: a strftime() format string.
9837 The time at which the filter is running, expressed in the local time zone.
9838 It can accept an argument: a strftime() format string.
9841 Frame metadata. Takes one or two arguments.
9843 The first argument is mandatory and specifies the metadata key.
9845 The second argument is optional and specifies a default value, used when the
9846 metadata key is not found or empty.
9848 Available metadata can be identified by inspecting entries
9849 starting with TAG included within each frame section
9850 printed by running @code{ffprobe -show_frames}.
9852 String metadata generated in filters leading to
9853 the drawtext filter are also available.
9856 The frame number, starting from 0.
9859 A one character description of the current picture type.
9862 The timestamp of the current frame.
9863 It can take up to three arguments.
9865 The first argument is the format of the timestamp; it defaults to @code{flt}
9866 for seconds as a decimal number with microsecond accuracy; @code{hms} stands
9867 for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
9868 @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
9869 @code{localtime} stands for the timestamp of the frame formatted as
9870 local time zone time.
9872 The second argument is an offset added to the timestamp.
9874 If the format is set to @code{hms}, a third argument @code{24HH} may be
9875 supplied to present the hour part of the formatted timestamp in 24h format
9878 If the format is set to @code{localtime} or @code{gmtime},
9879 a third argument may be supplied: a strftime() format string.
9880 By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
9883 @subsection Commands
9885 This filter supports altering parameters via commands:
9888 Alter existing filter parameters.
9890 Syntax for the argument is the same as for filter invocation, e.g.
9893 fontsize=56:fontcolor=green:text='Hello World'
9896 Full filter invocation with sendcmd would look like this:
9899 sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World'
9903 If the entire argument can't be parsed or applied as valid values then the filter will
9904 continue with its existing parameters.
9906 @subsection Examples
9910 Draw "Test Text" with font FreeSerif, using the default values for the
9911 optional parameters.
9914 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
9918 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
9919 and y=50 (counting from the top-left corner of the screen), text is
9920 yellow with a red box around it. Both the text and the box have an
9924 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
9925 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
9928 Note that the double quotes are not necessary if spaces are not used
9929 within the parameter list.
9932 Show the text at the center of the video frame:
9934 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
9938 Show the text at a random position, switching to a new position every 30 seconds:
9940 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)"
9944 Show a text line sliding from right to left in the last row of the video
9945 frame. The file @file{LONG_LINE} is assumed to contain a single line
9948 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
9952 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
9954 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
9958 Draw a single green letter "g", at the center of the input video.
9959 The glyph baseline is placed at half screen height.
9961 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
9965 Show text for 1 second every 3 seconds:
9967 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
9971 Use fontconfig to set the font. Note that the colons need to be escaped.
9973 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
9977 Print the date of a real-time encoding (see strftime(3)):
9979 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
9983 Show text fading in and out (appearing/disappearing):
9986 DS=1.0 # display start
9987 DE=10.0 # display end
9988 FID=1.5 # fade in duration
9989 FOD=5 # fade out duration
9990 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 @}"
9994 Horizontally align multiple separate texts. Note that @option{max_glyph_a}
9995 and the @option{fontsize} value are included in the @option{y} offset.
9997 drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
9998 drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
10002 Plot special @var{lavf.image2dec.source_basename} metadata onto each frame if
10003 such metadata exists. Otherwise, plot the string "NA". Note that image2 demuxer
10004 must have option @option{-export_path_metadata 1} for the special metadata fields
10005 to be available for filters.
10007 drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%@{metadata\:lavf.image2dec.source_basename\:NA@}':x=10:y=10"
10012 For more information about libfreetype, check:
10013 @url{http://www.freetype.org/}.
10015 For more information about fontconfig, check:
10016 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
10018 For more information about libfribidi, check:
10019 @url{http://fribidi.org/}.
10021 @section edgedetect
10023 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
10025 The filter accepts the following options:
10030 Set low and high threshold values used by the Canny thresholding
10033 The high threshold selects the "strong" edge pixels, which are then
10034 connected through 8-connectivity with the "weak" edge pixels selected
10035 by the low threshold.
10037 @var{low} and @var{high} threshold values must be chosen in the range
10038 [0,1], and @var{low} should be lesser or equal to @var{high}.
10040 Default value for @var{low} is @code{20/255}, and default value for @var{high}
10044 Define the drawing mode.
10048 Draw white/gray wires on black background.
10051 Mix the colors to create a paint/cartoon effect.
10054 Apply Canny edge detector on all selected planes.
10056 Default value is @var{wires}.
10059 Select planes for filtering. By default all available planes are filtered.
10062 @subsection Examples
10066 Standard edge detection with custom values for the hysteresis thresholding:
10068 edgedetect=low=0.1:high=0.4
10072 Painting effect without thresholding:
10074 edgedetect=mode=colormix:high=0
10080 Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
10082 For each input image, the filter will compute the optimal mapping from
10083 the input to the output given the codebook length, that is the number
10084 of distinct output colors.
10086 This filter accepts the following options.
10089 @item codebook_length, l
10090 Set codebook length. The value must be a positive integer, and
10091 represents the number of distinct output colors. Default value is 256.
10094 Set the maximum number of iterations to apply for computing the optimal
10095 mapping. The higher the value the better the result and the higher the
10096 computation time. Default value is 1.
10099 Set a random seed, must be an integer included between 0 and
10100 UINT32_MAX. If not specified, or if explicitly set to -1, the filter
10101 will try to use a good random seed on a best effort basis.
10104 Set pal8 output pixel format. This option does not work with codebook
10105 length greater than 256.
10110 Measure graylevel entropy in histogram of color channels of video frames.
10112 It accepts the following parameters:
10116 Can be either @var{normal} or @var{diff}. Default is @var{normal}.
10118 @var{diff} mode measures entropy of histogram delta values, absolute differences
10119 between neighbour histogram values.
10123 Set brightness, contrast, saturation and approximate gamma adjustment.
10125 The filter accepts the following options:
10129 Set the contrast expression. The value must be a float value in range
10130 @code{-1000.0} to @code{1000.0}. The default value is "1".
10133 Set the brightness expression. The value must be a float value in
10134 range @code{-1.0} to @code{1.0}. The default value is "0".
10137 Set the saturation expression. The value must be a float in
10138 range @code{0.0} to @code{3.0}. The default value is "1".
10141 Set the gamma expression. The value must be a float in range
10142 @code{0.1} to @code{10.0}. The default value is "1".
10145 Set the gamma expression for red. The value must be a float in
10146 range @code{0.1} to @code{10.0}. The default value is "1".
10149 Set the gamma expression for green. The value must be a float in range
10150 @code{0.1} to @code{10.0}. The default value is "1".
10153 Set the gamma expression for blue. The value must be a float in range
10154 @code{0.1} to @code{10.0}. The default value is "1".
10157 Set the gamma weight expression. It can be used to reduce the effect
10158 of a high gamma value on bright image areas, e.g. keep them from
10159 getting overamplified and just plain white. The value must be a float
10160 in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
10161 gamma correction all the way down while @code{1.0} leaves it at its
10162 full strength. Default is "1".
10165 Set when the expressions for brightness, contrast, saturation and
10166 gamma expressions are evaluated.
10168 It accepts the following values:
10171 only evaluate expressions once during the filter initialization or
10172 when a command is processed
10175 evaluate expressions for each incoming frame
10178 Default value is @samp{init}.
10181 The expressions accept the following parameters:
10184 frame count of the input frame starting from 0
10187 byte position of the corresponding packet in the input file, NAN if
10191 frame rate of the input video, NAN if the input frame rate is unknown
10194 timestamp expressed in seconds, NAN if the input timestamp is unknown
10197 @subsection Commands
10198 The filter supports the following commands:
10202 Set the contrast expression.
10205 Set the brightness expression.
10208 Set the saturation expression.
10211 Set the gamma expression.
10214 Set the gamma_r expression.
10217 Set gamma_g expression.
10220 Set gamma_b expression.
10223 Set gamma_weight expression.
10225 The command accepts the same syntax of the corresponding option.
10227 If the specified expression is not valid, it is kept at its current
10234 Apply erosion effect to the video.
10236 This filter replaces the pixel by the local(3x3) minimum.
10238 It accepts the following options:
10245 Limit the maximum change for each plane, default is 65535.
10246 If 0, plane will remain unchanged.
10249 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
10252 Flags to local 3x3 coordinates maps like this:
10259 @subsection Commands
10261 This filter supports the all above options as @ref{commands}.
10263 @section extractplanes
10265 Extract color channel components from input video stream into
10266 separate grayscale video streams.
10268 The filter accepts the following option:
10272 Set plane(s) to extract.
10274 Available values for planes are:
10285 Choosing planes not available in the input will result in an error.
10286 That means you cannot select @code{r}, @code{g}, @code{b} planes
10287 with @code{y}, @code{u}, @code{v} planes at same time.
10290 @subsection Examples
10294 Extract luma, u and v color channel component from input video frame
10295 into 3 grayscale outputs:
10297 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
10303 Apply a fade-in/out effect to the input video.
10305 It accepts the following parameters:
10309 The effect type can be either "in" for a fade-in, or "out" for a fade-out
10311 Default is @code{in}.
10313 @item start_frame, s
10314 Specify the number of the frame to start applying the fade
10315 effect at. Default is 0.
10318 The number of frames that the fade effect lasts. At the end of the
10319 fade-in effect, the output video will have the same intensity as the input video.
10320 At the end of the fade-out transition, the output video will be filled with the
10321 selected @option{color}.
10325 If set to 1, fade only alpha channel, if one exists on the input.
10326 Default value is 0.
10328 @item start_time, st
10329 Specify the timestamp (in seconds) of the frame to start to apply the fade
10330 effect. If both start_frame and start_time are specified, the fade will start at
10331 whichever comes last. Default is 0.
10334 The number of seconds for which the fade effect has to last. At the end of the
10335 fade-in effect the output video will have the same intensity as the input video,
10336 at the end of the fade-out transition the output video will be filled with the
10337 selected @option{color}.
10338 If both duration and nb_frames are specified, duration is used. Default is 0
10339 (nb_frames is used by default).
10342 Specify the color of the fade. Default is "black".
10345 @subsection Examples
10349 Fade in the first 30 frames of video:
10354 The command above is equivalent to:
10360 Fade out the last 45 frames of a 200-frame video:
10363 fade=type=out:start_frame=155:nb_frames=45
10367 Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
10369 fade=in:0:25, fade=out:975:25
10373 Make the first 5 frames yellow, then fade in from frame 5-24:
10375 fade=in:5:20:color=yellow
10379 Fade in alpha over first 25 frames of video:
10381 fade=in:0:25:alpha=1
10385 Make the first 5.5 seconds black, then fade in for 0.5 seconds:
10387 fade=t=in:st=5.5:d=0.5
10393 Denoise frames using 3D FFT (frequency domain filtering).
10395 The filter accepts the following options:
10399 Set the noise sigma constant. This sets denoising strength.
10400 Default value is 1. Allowed range is from 0 to 30.
10401 Using very high sigma with low overlap may give blocking artifacts.
10404 Set amount of denoising. By default all detected noise is reduced.
10405 Default value is 1. Allowed range is from 0 to 1.
10408 Set size of block, Default is 4, can be 3, 4, 5 or 6.
10409 Actual size of block in pixels is 2 to power of @var{block}, so by default
10410 block size in pixels is 2^4 which is 16.
10413 Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8.
10416 Set number of previous frames to use for denoising. By default is set to 0.
10419 Set number of next frames to to use for denoising. By default is set to 0.
10422 Set planes which will be filtered, by default are all available filtered
10427 Apply arbitrary expressions to samples in frequency domain
10431 Adjust the dc value (gain) of the luma plane of the image. The filter
10432 accepts an integer value in range @code{0} to @code{1000}. The default
10433 value is set to @code{0}.
10436 Adjust the dc value (gain) of the 1st chroma plane of the image. The
10437 filter accepts an integer value in range @code{0} to @code{1000}. The
10438 default value is set to @code{0}.
10441 Adjust the dc value (gain) of the 2nd chroma plane of the image. The
10442 filter accepts an integer value in range @code{0} to @code{1000}. The
10443 default value is set to @code{0}.
10446 Set the frequency domain weight expression for the luma plane.
10449 Set the frequency domain weight expression for the 1st chroma plane.
10452 Set the frequency domain weight expression for the 2nd chroma plane.
10455 Set when the expressions are evaluated.
10457 It accepts the following values:
10460 Only evaluate expressions once during the filter initialization.
10463 Evaluate expressions for each incoming frame.
10466 Default value is @samp{init}.
10468 The filter accepts the following variables:
10471 The coordinates of the current sample.
10475 The width and height of the image.
10478 The number of input frame, starting from 0.
10481 @subsection Examples
10487 fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
10493 fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
10499 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
10505 fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
10512 Extract a single field from an interlaced image using stride
10513 arithmetic to avoid wasting CPU time. The output frames are marked as
10516 The filter accepts the following options:
10520 Specify whether to extract the top (if the value is @code{0} or
10521 @code{top}) or the bottom field (if the value is @code{1} or
10527 Create new frames by copying the top and bottom fields from surrounding frames
10528 supplied as numbers by the hint file.
10532 Set file containing hints: absolute/relative frame numbers.
10534 There must be one line for each frame in a clip. Each line must contain two
10535 numbers separated by the comma, optionally followed by @code{-} or @code{+}.
10536 Numbers supplied on each line of file can not be out of [N-1,N+1] where N
10537 is current frame number for @code{absolute} mode or out of [-1, 1] range
10538 for @code{relative} mode. First number tells from which frame to pick up top
10539 field and second number tells from which frame to pick up bottom field.
10541 If optionally followed by @code{+} output frame will be marked as interlaced,
10542 else if followed by @code{-} output frame will be marked as progressive, else
10543 it will be marked same as input frame.
10544 If optionally followed by @code{t} output frame will use only top field, or in
10545 case of @code{b} it will use only bottom field.
10546 If line starts with @code{#} or @code{;} that line is skipped.
10549 Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
10552 Example of first several lines of @code{hint} file for @code{relative} mode:
10554 0,0 - # first frame
10555 1,0 - # second frame, use third's frame top field and second's frame bottom field
10556 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
10571 @section fieldmatch
10573 Field matching filter for inverse telecine. It is meant to reconstruct the
10574 progressive frames from a telecined stream. The filter does not drop duplicated
10575 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
10576 followed by a decimation filter such as @ref{decimate} in the filtergraph.
10578 The separation of the field matching and the decimation is notably motivated by
10579 the possibility of inserting a de-interlacing filter fallback between the two.
10580 If the source has mixed telecined and real interlaced content,
10581 @code{fieldmatch} will not be able to match fields for the interlaced parts.
10582 But these remaining combed frames will be marked as interlaced, and thus can be
10583 de-interlaced by a later filter such as @ref{yadif} before decimation.
10585 In addition to the various configuration options, @code{fieldmatch} can take an
10586 optional second stream, activated through the @option{ppsrc} option. If
10587 enabled, the frames reconstruction will be based on the fields and frames from
10588 this second stream. This allows the first input to be pre-processed in order to
10589 help the various algorithms of the filter, while keeping the output lossless
10590 (assuming the fields are matched properly). Typically, a field-aware denoiser,
10591 or brightness/contrast adjustments can help.
10593 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
10594 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
10595 which @code{fieldmatch} is based on. While the semantic and usage are very
10596 close, some behaviour and options names can differ.
10598 The @ref{decimate} filter currently only works for constant frame rate input.
10599 If your input has mixed telecined (30fps) and progressive content with a lower
10600 framerate like 24fps use the following filterchain to produce the necessary cfr
10601 stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
10603 The filter accepts the following options:
10607 Specify the assumed field order of the input stream. Available values are:
10611 Auto detect parity (use FFmpeg's internal parity value).
10613 Assume bottom field first.
10615 Assume top field first.
10618 Note that it is sometimes recommended not to trust the parity announced by the
10621 Default value is @var{auto}.
10624 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
10625 sense that it won't risk creating jerkiness due to duplicate frames when
10626 possible, but if there are bad edits or blended fields it will end up
10627 outputting combed frames when a good match might actually exist. On the other
10628 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
10629 but will almost always find a good frame if there is one. The other values are
10630 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
10631 jerkiness and creating duplicate frames versus finding good matches in sections
10632 with bad edits, orphaned fields, blended fields, etc.
10634 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
10636 Available values are:
10640 2-way matching (p/c)
10642 2-way matching, and trying 3rd match if still combed (p/c + n)
10644 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
10646 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
10647 still combed (p/c + n + u/b)
10649 3-way matching (p/c/n)
10651 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
10652 detected as combed (p/c/n + u/b)
10655 The parenthesis at the end indicate the matches that would be used for that
10656 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
10659 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
10662 Default value is @var{pc_n}.
10665 Mark the main input stream as a pre-processed input, and enable the secondary
10666 input stream as the clean source to pick the fields from. See the filter
10667 introduction for more details. It is similar to the @option{clip2} feature from
10670 Default value is @code{0} (disabled).
10673 Set the field to match from. It is recommended to set this to the same value as
10674 @option{order} unless you experience matching failures with that setting. In
10675 certain circumstances changing the field that is used to match from can have a
10676 large impact on matching performance. Available values are:
10680 Automatic (same value as @option{order}).
10682 Match from the bottom field.
10684 Match from the top field.
10687 Default value is @var{auto}.
10690 Set whether or not chroma is included during the match comparisons. In most
10691 cases it is recommended to leave this enabled. You should set this to @code{0}
10692 only if your clip has bad chroma problems such as heavy rainbowing or other
10693 artifacts. Setting this to @code{0} could also be used to speed things up at
10694 the cost of some accuracy.
10696 Default value is @code{1}.
10700 These define an exclusion band which excludes the lines between @option{y0} and
10701 @option{y1} from being included in the field matching decision. An exclusion
10702 band can be used to ignore subtitles, a logo, or other things that may
10703 interfere with the matching. @option{y0} sets the starting scan line and
10704 @option{y1} sets the ending line; all lines in between @option{y0} and
10705 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
10706 @option{y0} and @option{y1} to the same value will disable the feature.
10707 @option{y0} and @option{y1} defaults to @code{0}.
10710 Set the scene change detection threshold as a percentage of maximum change on
10711 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
10712 detection is only relevant in case @option{combmatch}=@var{sc}. The range for
10713 @option{scthresh} is @code{[0.0, 100.0]}.
10715 Default value is @code{12.0}.
10718 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
10719 account the combed scores of matches when deciding what match to use as the
10720 final match. Available values are:
10724 No final matching based on combed scores.
10726 Combed scores are only used when a scene change is detected.
10728 Use combed scores all the time.
10731 Default is @var{sc}.
10734 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
10735 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
10736 Available values are:
10740 No forced calculation.
10742 Force p/c/n calculations.
10744 Force p/c/n/u/b calculations.
10747 Default value is @var{none}.
10750 This is the area combing threshold used for combed frame detection. This
10751 essentially controls how "strong" or "visible" combing must be to be detected.
10752 Larger values mean combing must be more visible and smaller values mean combing
10753 can be less visible or strong and still be detected. Valid settings are from
10754 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
10755 be detected as combed). This is basically a pixel difference value. A good
10756 range is @code{[8, 12]}.
10758 Default value is @code{9}.
10761 Sets whether or not chroma is considered in the combed frame decision. Only
10762 disable this if your source has chroma problems (rainbowing, etc.) that are
10763 causing problems for the combed frame detection with chroma enabled. Actually,
10764 using @option{chroma}=@var{0} is usually more reliable, except for the case
10765 where there is chroma only combing in the source.
10767 Default value is @code{0}.
10771 Respectively set the x-axis and y-axis size of the window used during combed
10772 frame detection. This has to do with the size of the area in which
10773 @option{combpel} pixels are required to be detected as combed for a frame to be
10774 declared combed. See the @option{combpel} parameter description for more info.
10775 Possible values are any number that is a power of 2 starting at 4 and going up
10778 Default value is @code{16}.
10781 The number of combed pixels inside any of the @option{blocky} by
10782 @option{blockx} size blocks on the frame for the frame to be detected as
10783 combed. While @option{cthresh} controls how "visible" the combing must be, this
10784 setting controls "how much" combing there must be in any localized area (a
10785 window defined by the @option{blockx} and @option{blocky} settings) on the
10786 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
10787 which point no frames will ever be detected as combed). This setting is known
10788 as @option{MI} in TFM/VFM vocabulary.
10790 Default value is @code{80}.
10793 @anchor{p/c/n/u/b meaning}
10794 @subsection p/c/n/u/b meaning
10796 @subsubsection p/c/n
10798 We assume the following telecined stream:
10801 Top fields: 1 2 2 3 4
10802 Bottom fields: 1 2 3 4 4
10805 The numbers correspond to the progressive frame the fields relate to. Here, the
10806 first two frames are progressive, the 3rd and 4th are combed, and so on.
10808 When @code{fieldmatch} is configured to run a matching from bottom
10809 (@option{field}=@var{bottom}) this is how this input stream get transformed:
10814 B 1 2 3 4 4 <-- matching reference
10823 As a result of the field matching, we can see that some frames get duplicated.
10824 To perform a complete inverse telecine, you need to rely on a decimation filter
10825 after this operation. See for instance the @ref{decimate} filter.
10827 The same operation now matching from top fields (@option{field}=@var{top})
10832 T 1 2 2 3 4 <-- matching reference
10842 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
10843 basically, they refer to the frame and field of the opposite parity:
10846 @item @var{p} matches the field of the opposite parity in the previous frame
10847 @item @var{c} matches the field of the opposite parity in the current frame
10848 @item @var{n} matches the field of the opposite parity in the next frame
10853 The @var{u} and @var{b} matching are a bit special in the sense that they match
10854 from the opposite parity flag. In the following examples, we assume that we are
10855 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
10856 'x' is placed above and below each matched fields.
10858 With bottom matching (@option{field}=@var{bottom}):
10863 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
10864 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
10872 With top matching (@option{field}=@var{top}):
10877 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
10878 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
10886 @subsection Examples
10888 Simple IVTC of a top field first telecined stream:
10890 fieldmatch=order=tff:combmatch=none, decimate
10893 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
10895 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
10898 @section fieldorder
10900 Transform the field order of the input video.
10902 It accepts the following parameters:
10907 The output field order. Valid values are @var{tff} for top field first or @var{bff}
10908 for bottom field first.
10911 The default value is @samp{tff}.
10913 The transformation is done by shifting the picture content up or down
10914 by one line, and filling the remaining line with appropriate picture content.
10915 This method is consistent with most broadcast field order converters.
10917 If the input video is not flagged as being interlaced, or it is already
10918 flagged as being of the required output field order, then this filter does
10919 not alter the incoming video.
10921 It is very useful when converting to or from PAL DV material,
10922 which is bottom field first.
10926 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
10929 @section fifo, afifo
10931 Buffer input images and send them when they are requested.
10933 It is mainly useful when auto-inserted by the libavfilter
10936 It does not take parameters.
10938 @section fillborders
10940 Fill borders of the input video, without changing video stream dimensions.
10941 Sometimes video can have garbage at the four edges and you may not want to
10942 crop video input to keep size multiple of some number.
10944 This filter accepts the following options:
10948 Number of pixels to fill from left border.
10951 Number of pixels to fill from right border.
10954 Number of pixels to fill from top border.
10957 Number of pixels to fill from bottom border.
10962 It accepts the following values:
10965 fill pixels using outermost pixels
10968 fill pixels using mirroring
10971 fill pixels with constant value
10974 Default is @var{smear}.
10977 Set color for pixels in fixed mode. Default is @var{black}.
10980 @subsection Commands
10981 This filter supports same @ref{commands} as options.
10982 The command accepts the same syntax of the corresponding option.
10984 If the specified expression is not valid, it is kept at its current
10989 Find a rectangular object
10991 It accepts the following options:
10995 Filepath of the object image, needs to be in gray8.
10998 Detection threshold, default is 0.5.
11001 Number of mipmaps, default is 3.
11003 @item xmin, ymin, xmax, ymax
11004 Specifies the rectangle in which to search.
11007 @subsection Examples
11011 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
11013 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
11019 Flood area with values of same pixel components with another values.
11021 It accepts the following options:
11024 Set pixel x coordinate.
11027 Set pixel y coordinate.
11030 Set source #0 component value.
11033 Set source #1 component value.
11036 Set source #2 component value.
11039 Set source #3 component value.
11042 Set destination #0 component value.
11045 Set destination #1 component value.
11048 Set destination #2 component value.
11051 Set destination #3 component value.
11057 Convert the input video to one of the specified pixel formats.
11058 Libavfilter will try to pick one that is suitable as input to
11061 It accepts the following parameters:
11065 A '|'-separated list of pixel format names, such as
11066 "pix_fmts=yuv420p|monow|rgb24".
11070 @subsection Examples
11074 Convert the input video to the @var{yuv420p} format
11076 format=pix_fmts=yuv420p
11079 Convert the input video to any of the formats in the list
11081 format=pix_fmts=yuv420p|yuv444p|yuv410p
11088 Convert the video to specified constant frame rate by duplicating or dropping
11089 frames as necessary.
11091 It accepts the following parameters:
11095 The desired output frame rate. The default is @code{25}.
11098 Assume the first PTS should be the given value, in seconds. This allows for
11099 padding/trimming at the start of stream. By default, no assumption is made
11100 about the first frame's expected PTS, so no padding or trimming is done.
11101 For example, this could be set to 0 to pad the beginning with duplicates of
11102 the first frame if a video stream starts after the audio stream or to trim any
11103 frames with a negative PTS.
11106 Timestamp (PTS) rounding method.
11108 Possible values are:
11115 round towards -infinity
11117 round towards +infinity
11121 The default is @code{near}.
11124 Action performed when reading the last frame.
11126 Possible values are:
11129 Use same timestamp rounding method as used for other frames.
11131 Pass through last frame if input duration has not been reached yet.
11133 The default is @code{round}.
11137 Alternatively, the options can be specified as a flat string:
11138 @var{fps}[:@var{start_time}[:@var{round}]].
11140 See also the @ref{setpts} filter.
11142 @subsection Examples
11146 A typical usage in order to set the fps to 25:
11152 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
11154 fps=fps=film:round=near
11160 Pack two different video streams into a stereoscopic video, setting proper
11161 metadata on supported codecs. The two views should have the same size and
11162 framerate and processing will stop when the shorter video ends. Please note
11163 that you may conveniently adjust view properties with the @ref{scale} and
11166 It accepts the following parameters:
11170 The desired packing format. Supported values are:
11175 The views are next to each other (default).
11178 The views are on top of each other.
11181 The views are packed by line.
11184 The views are packed by column.
11187 The views are temporally interleaved.
11196 # Convert left and right views into a frame-sequential video
11197 ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
11199 # Convert views into a side-by-side video with the same output resolution as the input
11200 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
11205 Change the frame rate by interpolating new video output frames from the source
11208 This filter is not designed to function correctly with interlaced media. If
11209 you wish to change the frame rate of interlaced media then you are required
11210 to deinterlace before this filter and re-interlace after this filter.
11212 A description of the accepted options follows.
11216 Specify the output frames per second. This option can also be specified
11217 as a value alone. The default is @code{50}.
11220 Specify the start of a range where the output frame will be created as a
11221 linear interpolation of two frames. The range is [@code{0}-@code{255}],
11222 the default is @code{15}.
11225 Specify the end of a range where the output frame will be created as a
11226 linear interpolation of two frames. The range is [@code{0}-@code{255}],
11227 the default is @code{240}.
11230 Specify the level at which a scene change is detected as a value between
11231 0 and 100 to indicate a new scene; a low value reflects a low
11232 probability for the current frame to introduce a new scene, while a higher
11233 value means the current frame is more likely to be one.
11234 The default is @code{8.2}.
11237 Specify flags influencing the filter process.
11239 Available value for @var{flags} is:
11242 @item scene_change_detect, scd
11243 Enable scene change detection using the value of the option @var{scene}.
11244 This flag is enabled by default.
11250 Select one frame every N-th frame.
11252 This filter accepts the following option:
11255 Select frame after every @code{step} frames.
11256 Allowed values are positive integers higher than 0. Default value is @code{1}.
11259 @section freezedetect
11261 Detect frozen video.
11263 This filter logs a message and sets frame metadata when it detects that the
11264 input video has no significant change in content during a specified duration.
11265 Video freeze detection calculates the mean average absolute difference of all
11266 the components of video frames and compares it to a noise floor.
11268 The printed times and duration are expressed in seconds. The
11269 @code{lavfi.freezedetect.freeze_start} metadata key is set on the first frame
11270 whose timestamp equals or exceeds the detection duration and it contains the
11271 timestamp of the first frame of the freeze. The
11272 @code{lavfi.freezedetect.freeze_duration} and
11273 @code{lavfi.freezedetect.freeze_end} metadata keys are set on the first frame
11276 The filter accepts the following options:
11280 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
11281 specified value) or as a difference ratio between 0 and 1. Default is -60dB, or
11285 Set freeze duration until notification (default is 2 seconds).
11288 @section freezeframes
11290 Freeze video frames.
11292 This filter freezes video frames using frame from 2nd input.
11294 The filter accepts the following options:
11298 Set number of first frame from which to start freeze.
11301 Set number of last frame from which to end freeze.
11304 Set number of frame from 2nd input which will be used instead of replaced frames.
11310 Apply a frei0r effect to the input video.
11312 To enable the compilation of this filter, you need to install the frei0r
11313 header and configure FFmpeg with @code{--enable-frei0r}.
11315 It accepts the following parameters:
11320 The name of the frei0r effect to load. If the environment variable
11321 @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
11322 directories specified by the colon-separated list in @env{FREI0R_PATH}.
11323 Otherwise, the standard frei0r paths are searched, in this order:
11324 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
11325 @file{/usr/lib/frei0r-1/}.
11327 @item filter_params
11328 A '|'-separated list of parameters to pass to the frei0r effect.
11332 A frei0r effect parameter can be a boolean (its value is either
11333 "y" or "n"), a double, a color (specified as
11334 @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
11335 numbers between 0.0 and 1.0, inclusive) or a color description as specified in the
11336 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils},
11337 a position (specified as @var{X}/@var{Y}, where
11338 @var{X} and @var{Y} are floating point numbers) and/or a string.
11340 The number and types of parameters depend on the loaded effect. If an
11341 effect parameter is not specified, the default value is set.
11343 @subsection Examples
11347 Apply the distort0r effect, setting the first two double parameters:
11349 frei0r=filter_name=distort0r:filter_params=0.5|0.01
11353 Apply the colordistance effect, taking a color as the first parameter:
11355 frei0r=colordistance:0.2/0.3/0.4
11356 frei0r=colordistance:violet
11357 frei0r=colordistance:0x112233
11361 Apply the perspective effect, specifying the top left and top right image
11364 frei0r=perspective:0.2/0.2|0.8/0.2
11368 For more information, see
11369 @url{http://frei0r.dyne.org}
11373 Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
11375 It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
11376 processing filter, one of them is performed once per block, not per pixel.
11377 This allows for much higher speed.
11379 The filter accepts the following options:
11383 Set quality. This option defines the number of levels for averaging. It accepts
11384 an integer in the range 4-5. Default value is @code{4}.
11387 Force a constant quantization parameter. It accepts an integer in range 0-63.
11388 If not set, the filter will use the QP from the video stream (if available).
11391 Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
11392 more details but also more artifacts, while higher values make the image smoother
11393 but also blurrier. Default value is @code{0} − PSNR optimal.
11395 @item use_bframe_qp
11396 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
11397 option may cause flicker since the B-Frames have often larger QP. Default is
11398 @code{0} (not enabled).
11404 Apply Gaussian blur filter.
11406 The filter accepts the following options:
11410 Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
11413 Set number of steps for Gaussian approximation. Default is @code{1}.
11416 Set which planes to filter. By default all planes are filtered.
11419 Set vertical sigma, if negative it will be same as @code{sigma}.
11420 Default is @code{-1}.
11423 @subsection Commands
11424 This filter supports same commands as options.
11425 The command accepts the same syntax of the corresponding option.
11427 If the specified expression is not valid, it is kept at its current
11432 Apply generic equation to each pixel.
11434 The filter accepts the following options:
11437 @item lum_expr, lum
11438 Set the luminance expression.
11440 Set the chrominance blue expression.
11442 Set the chrominance red expression.
11443 @item alpha_expr, a
11444 Set the alpha expression.
11446 Set the red expression.
11447 @item green_expr, g
11448 Set the green expression.
11450 Set the blue expression.
11453 The colorspace is selected according to the specified options. If one
11454 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
11455 options is specified, the filter will automatically select a YCbCr
11456 colorspace. If one of the @option{red_expr}, @option{green_expr}, or
11457 @option{blue_expr} options is specified, it will select an RGB
11460 If one of the chrominance expression is not defined, it falls back on the other
11461 one. If no alpha expression is specified it will evaluate to opaque value.
11462 If none of chrominance expressions are specified, they will evaluate
11463 to the luminance expression.
11465 The expressions can use the following variables and functions:
11469 The sequential number of the filtered frame, starting from @code{0}.
11473 The coordinates of the current sample.
11477 The width and height of the image.
11481 Width and height scale depending on the currently filtered plane. It is the
11482 ratio between the corresponding luma plane number of pixels and the current
11483 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
11484 @code{0.5,0.5} for chroma planes.
11487 Time of the current frame, expressed in seconds.
11490 Return the value of the pixel at location (@var{x},@var{y}) of the current
11494 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
11498 Return the value of the pixel at location (@var{x},@var{y}) of the
11499 blue-difference chroma plane. Return 0 if there is no such plane.
11502 Return the value of the pixel at location (@var{x},@var{y}) of the
11503 red-difference chroma plane. Return 0 if there is no such plane.
11508 Return the value of the pixel at location (@var{x},@var{y}) of the
11509 red/green/blue component. Return 0 if there is no such component.
11512 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
11513 plane. Return 0 if there is no such plane.
11515 @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)
11516 Sum of sample values in the rectangle from (0,0) to (x,y), this allows obtaining
11517 sums of samples within a rectangle. See the functions without the sum postfix.
11519 @item interpolation
11520 Set one of interpolation methods:
11525 Default is bilinear.
11528 For functions, if @var{x} and @var{y} are outside the area, the value will be
11529 automatically clipped to the closer edge.
11531 Please note that this filter can use multiple threads in which case each slice
11532 will have its own expression state. If you want to use only a single expression
11533 state because your expressions depend on previous state then you should limit
11534 the number of filter threads to 1.
11536 @subsection Examples
11540 Flip the image horizontally:
11546 Generate a bidimensional sine wave, with angle @code{PI/3} and a
11547 wavelength of 100 pixels:
11549 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
11553 Generate a fancy enigmatic moving light:
11555 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
11559 Generate a quick emboss effect:
11561 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
11565 Modify RGB components depending on pixel position:
11567 geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
11571 Create a radial gradient that is the same size as the input (also see
11572 the @ref{vignette} filter):
11574 geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
11580 Fix the banding artifacts that are sometimes introduced into nearly flat
11581 regions by truncation to 8-bit color depth.
11582 Interpolate the gradients that should go where the bands are, and
11585 It is designed for playback only. Do not use it prior to
11586 lossy compression, because compression tends to lose the dither and
11587 bring back the bands.
11589 It accepts the following parameters:
11594 The maximum amount by which the filter will change any one pixel. This is also
11595 the threshold for detecting nearly flat regions. Acceptable values range from
11596 .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
11600 The neighborhood to fit the gradient to. A larger radius makes for smoother
11601 gradients, but also prevents the filter from modifying the pixels near detailed
11602 regions. Acceptable values are 8-32; the default value is 16. Out-of-range
11603 values will be clipped to the valid range.
11607 Alternatively, the options can be specified as a flat string:
11608 @var{strength}[:@var{radius}]
11610 @subsection Examples
11614 Apply the filter with a @code{3.5} strength and radius of @code{8}:
11620 Specify radius, omitting the strength (which will fall-back to the default
11628 @anchor{graphmonitor}
11629 @section graphmonitor
11630 Show various filtergraph stats.
11632 With this filter one can debug complete filtergraph.
11633 Especially issues with links filling with queued frames.
11635 The filter accepts the following options:
11639 Set video output size. Default is @var{hd720}.
11642 Set video opacity. Default is @var{0.9}. Allowed range is from @var{0} to @var{1}.
11645 Set output mode, can be @var{fulll} or @var{compact}.
11646 In @var{compact} mode only filters with some queued frames have displayed stats.
11649 Set flags which enable which stats are shown in video.
11651 Available values for flags are:
11654 Display number of queued frames in each link.
11656 @item frame_count_in
11657 Display number of frames taken from filter.
11659 @item frame_count_out
11660 Display number of frames given out from filter.
11663 Display current filtered frame pts.
11666 Display current filtered frame time.
11669 Display time base for filter link.
11672 Display used format for filter link.
11675 Display video size or number of audio channels in case of audio used by filter link.
11678 Display video frame rate or sample rate in case of audio used by filter link.
11682 Set upper limit for video rate of output stream, Default value is @var{25}.
11683 This guarantee that output video frame rate will not be higher than this value.
11687 A color constancy variation filter which estimates scene illumination via grey edge algorithm
11688 and corrects the scene colors accordingly.
11690 See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf}
11692 The filter accepts the following options:
11696 The order of differentiation to be applied on the scene. Must be chosen in the range
11697 [0,2] and default value is 1.
11700 The Minkowski parameter to be used for calculating the Minkowski distance. Must
11701 be chosen in the range [0,20] and default value is 1. Set to 0 for getting
11702 max value instead of calculating Minkowski distance.
11705 The standard deviation of Gaussian blur to be applied on the scene. Must be
11706 chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) )
11707 can't be equal to 0 if @var{difford} is greater than 0.
11710 @subsection Examples
11716 greyedge=difford=1:minknorm=5:sigma=2
11722 greyedge=difford=1:minknorm=0:sigma=2
11730 Apply a Hald CLUT to a video stream.
11732 First input is the video stream to process, and second one is the Hald CLUT.
11733 The Hald CLUT input can be a simple picture or a complete video stream.
11735 The filter accepts the following options:
11739 Force termination when the shortest input terminates. Default is @code{0}.
11741 Continue applying the last CLUT after the end of the stream. A value of
11742 @code{0} disable the filter after the last frame of the CLUT is reached.
11743 Default is @code{1}.
11746 @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
11747 filters share the same internals).
11749 This filter also supports the @ref{framesync} options.
11751 More information about the Hald CLUT can be found on Eskil Steenberg's website
11752 (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
11754 @subsection Workflow examples
11756 @subsubsection Hald CLUT video stream
11758 Generate an identity Hald CLUT stream altered with various effects:
11760 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
11763 Note: make sure you use a lossless codec.
11765 Then use it with @code{haldclut} to apply it on some random stream:
11767 ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
11770 The Hald CLUT will be applied to the 10 first seconds (duration of
11771 @file{clut.nut}), then the latest picture of that CLUT stream will be applied
11772 to the remaining frames of the @code{mandelbrot} stream.
11774 @subsubsection Hald CLUT with preview
11776 A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
11777 @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
11778 biggest possible square starting at the top left of the picture. The remaining
11779 padding pixels (bottom or right) will be ignored. This area can be used to add
11780 a preview of the Hald CLUT.
11782 Typically, the following generated Hald CLUT will be supported by the
11783 @code{haldclut} filter:
11786 ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
11787 pad=iw+320 [padded_clut];
11788 smptebars=s=320x256, split [a][b];
11789 [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
11790 [main][b] overlay=W-320" -frames:v 1 clut.png
11793 It contains the original and a preview of the effect of the CLUT: SMPTE color
11794 bars are displayed on the right-top, and below the same color bars processed by
11797 Then, the effect of this Hald CLUT can be visualized with:
11799 ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
11804 Flip the input video horizontally.
11806 For example, to horizontally flip the input video with @command{ffmpeg}:
11808 ffmpeg -i in.avi -vf "hflip" out.avi
11812 This filter applies a global color histogram equalization on a
11815 It can be used to correct video that has a compressed range of pixel
11816 intensities. The filter redistributes the pixel intensities to
11817 equalize their distribution across the intensity range. It may be
11818 viewed as an "automatically adjusting contrast filter". This filter is
11819 useful only for correcting degraded or poorly captured source
11822 The filter accepts the following options:
11826 Determine the amount of equalization to be applied. As the strength
11827 is reduced, the distribution of pixel intensities more-and-more
11828 approaches that of the input frame. The value must be a float number
11829 in the range [0,1] and defaults to 0.200.
11832 Set the maximum intensity that can generated and scale the output
11833 values appropriately. The strength should be set as desired and then
11834 the intensity can be limited if needed to avoid washing-out. The value
11835 must be a float number in the range [0,1] and defaults to 0.210.
11838 Set the antibanding level. If enabled the filter will randomly vary
11839 the luminance of output pixels by a small amount to avoid banding of
11840 the histogram. Possible values are @code{none}, @code{weak} or
11841 @code{strong}. It defaults to @code{none}.
11847 Compute and draw a color distribution histogram for the input video.
11849 The computed histogram is a representation of the color component
11850 distribution in an image.
11852 Standard histogram displays the color components distribution in an image.
11853 Displays color graph for each color component. Shows distribution of
11854 the Y, U, V, A or R, G, B components, depending on input format, in the
11855 current frame. Below each graph a color component scale meter is shown.
11857 The filter accepts the following options:
11861 Set height of level. Default value is @code{200}.
11862 Allowed range is [50, 2048].
11865 Set height of color scale. Default value is @code{12}.
11866 Allowed range is [0, 40].
11870 It accepts the following values:
11873 Per color component graphs are placed below each other.
11876 Per color component graphs are placed side by side.
11879 Presents information identical to that in the @code{parade}, except
11880 that the graphs representing color components are superimposed directly
11883 Default is @code{stack}.
11886 Set mode. Can be either @code{linear}, or @code{logarithmic}.
11887 Default is @code{linear}.
11890 Set what color components to display.
11891 Default is @code{7}.
11894 Set foreground opacity. Default is @code{0.7}.
11897 Set background opacity. Default is @code{0.5}.
11900 @subsection Examples
11905 Calculate and draw histogram:
11907 ffplay -i input -vf histogram
11915 This is a high precision/quality 3d denoise filter. It aims to reduce
11916 image noise, producing smooth images and making still images really
11917 still. It should enhance compressibility.
11919 It accepts the following optional parameters:
11923 A non-negative floating point number which specifies spatial luma strength.
11924 It defaults to 4.0.
11926 @item chroma_spatial
11927 A non-negative floating point number which specifies spatial chroma strength.
11928 It defaults to 3.0*@var{luma_spatial}/4.0.
11931 A floating point number which specifies luma temporal strength. It defaults to
11932 6.0*@var{luma_spatial}/4.0.
11935 A floating point number which specifies chroma temporal strength. It defaults to
11936 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
11939 @subsection Commands
11940 This filter supports same @ref{commands} as options.
11941 The command accepts the same syntax of the corresponding option.
11943 If the specified expression is not valid, it is kept at its current
11946 @anchor{hwdownload}
11947 @section hwdownload
11949 Download hardware frames to system memory.
11951 The input must be in hardware frames, and the output a non-hardware format.
11952 Not all formats will be supported on the output - it may be necessary to insert
11953 an additional @option{format} filter immediately following in the graph to get
11954 the output in a supported format.
11958 Map hardware frames to system memory or to another device.
11960 This filter has several different modes of operation; which one is used depends
11961 on the input and output formats:
11964 Hardware frame input, normal frame output
11966 Map the input frames to system memory and pass them to the output. If the
11967 original hardware frame is later required (for example, after overlaying
11968 something else on part of it), the @option{hwmap} filter can be used again
11969 in the next mode to retrieve it.
11971 Normal frame input, hardware frame output
11973 If the input is actually a software-mapped hardware frame, then unmap it -
11974 that is, return the original hardware frame.
11976 Otherwise, a device must be provided. Create new hardware surfaces on that
11977 device for the output, then map them back to the software format at the input
11978 and give those frames to the preceding filter. This will then act like the
11979 @option{hwupload} filter, but may be able to avoid an additional copy when
11980 the input is already in a compatible format.
11982 Hardware frame input and output
11984 A device must be supplied for the output, either directly or with the
11985 @option{derive_device} option. The input and output devices must be of
11986 different types and compatible - the exact meaning of this is
11987 system-dependent, but typically it means that they must refer to the same
11988 underlying hardware context (for example, refer to the same graphics card).
11990 If the input frames were originally created on the output device, then unmap
11991 to retrieve the original frames.
11993 Otherwise, map the frames to the output device - create new hardware frames
11994 on the output corresponding to the frames on the input.
11997 The following additional parameters are accepted:
12001 Set the frame mapping mode. Some combination of:
12004 The mapped frame should be readable.
12006 The mapped frame should be writeable.
12008 The mapping will always overwrite the entire frame.
12010 This may improve performance in some cases, as the original contents of the
12011 frame need not be loaded.
12013 The mapping must not involve any copying.
12015 Indirect mappings to copies of frames are created in some cases where either
12016 direct mapping is not possible or it would have unexpected properties.
12017 Setting this flag ensures that the mapping is direct and will fail if that is
12020 Defaults to @var{read+write} if not specified.
12022 @item derive_device @var{type}
12023 Rather than using the device supplied at initialisation, instead derive a new
12024 device of type @var{type} from the device the input frames exist on.
12027 In a hardware to hardware mapping, map in reverse - create frames in the sink
12028 and map them back to the source. This may be necessary in some cases where
12029 a mapping in one direction is required but only the opposite direction is
12030 supported by the devices being used.
12032 This option is dangerous - it may break the preceding filter in undefined
12033 ways if there are any additional constraints on that filter's output.
12034 Do not use it without fully understanding the implications of its use.
12040 Upload system memory frames to hardware surfaces.
12042 The device to upload to must be supplied when the filter is initialised. If
12043 using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
12044 option or with the @option{derive_device} option. The input and output devices
12045 must be of different types and compatible - the exact meaning of this is
12046 system-dependent, but typically it means that they must refer to the same
12047 underlying hardware context (for example, refer to the same graphics card).
12049 The following additional parameters are accepted:
12052 @item derive_device @var{type}
12053 Rather than using the device supplied at initialisation, instead derive a new
12054 device of type @var{type} from the device the input frames exist on.
12057 @anchor{hwupload_cuda}
12058 @section hwupload_cuda
12060 Upload system memory frames to a CUDA device.
12062 It accepts the following optional parameters:
12066 The number of the CUDA device to use
12071 Apply a high-quality magnification filter designed for pixel art. This filter
12072 was originally created by Maxim Stepin.
12074 It accepts the following option:
12078 Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
12079 @code{hq3x} and @code{4} for @code{hq4x}.
12080 Default is @code{3}.
12084 Stack input videos horizontally.
12086 All streams must be of same pixel format and of same height.
12088 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
12089 to create same output.
12091 The filter accepts the following option:
12095 Set number of input streams. Default is 2.
12098 If set to 1, force the output to terminate when the shortest input
12099 terminates. Default value is 0.
12104 Modify the hue and/or the saturation of the input.
12106 It accepts the following parameters:
12110 Specify the hue angle as a number of degrees. It accepts an expression,
12111 and defaults to "0".
12114 Specify the saturation in the [-10,10] range. It accepts an expression and
12118 Specify the hue angle as a number of radians. It accepts an
12119 expression, and defaults to "0".
12122 Specify the brightness in the [-10,10] range. It accepts an expression and
12126 @option{h} and @option{H} are mutually exclusive, and can't be
12127 specified at the same time.
12129 The @option{b}, @option{h}, @option{H} and @option{s} option values are
12130 expressions containing the following constants:
12134 frame count of the input frame starting from 0
12137 presentation timestamp of the input frame expressed in time base units
12140 frame rate of the input video, NAN if the input frame rate is unknown
12143 timestamp expressed in seconds, NAN if the input timestamp is unknown
12146 time base of the input video
12149 @subsection Examples
12153 Set the hue to 90 degrees and the saturation to 1.0:
12159 Same command but expressing the hue in radians:
12165 Rotate hue and make the saturation swing between 0
12166 and 2 over a period of 1 second:
12168 hue="H=2*PI*t: s=sin(2*PI*t)+1"
12172 Apply a 3 seconds saturation fade-in effect starting at 0:
12174 hue="s=min(t/3\,1)"
12177 The general fade-in expression can be written as:
12179 hue="s=min(0\, max((t-START)/DURATION\, 1))"
12183 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
12185 hue="s=max(0\, min(1\, (8-t)/3))"
12188 The general fade-out expression can be written as:
12190 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
12195 @subsection Commands
12197 This filter supports the following commands:
12203 Modify the hue and/or the saturation and/or brightness of the input video.
12204 The command accepts the same syntax of the corresponding option.
12206 If the specified expression is not valid, it is kept at its current
12210 @section hysteresis
12212 Grow first stream into second stream by connecting components.
12213 This makes it possible to build more robust edge masks.
12215 This filter accepts the following options:
12219 Set which planes will be processed as bitmap, unprocessed planes will be
12220 copied from first stream.
12221 By default value 0xf, all planes will be processed.
12224 Set threshold which is used in filtering. If pixel component value is higher than
12225 this value filter algorithm for connecting components is activated.
12226 By default value is 0.
12231 Detect video interlacing type.
12233 This filter tries to detect if the input frames are interlaced, progressive,
12234 top or bottom field first. It will also try to detect fields that are
12235 repeated between adjacent frames (a sign of telecine).
12237 Single frame detection considers only immediately adjacent frames when classifying each frame.
12238 Multiple frame detection incorporates the classification history of previous frames.
12240 The filter will log these metadata values:
12243 @item single.current_frame
12244 Detected type of current frame using single-frame detection. One of:
12245 ``tff'' (top field first), ``bff'' (bottom field first),
12246 ``progressive'', or ``undetermined''
12249 Cumulative number of frames detected as top field first using single-frame detection.
12252 Cumulative number of frames detected as top field first using multiple-frame detection.
12255 Cumulative number of frames detected as bottom field first using single-frame detection.
12257 @item multiple.current_frame
12258 Detected type of current frame using multiple-frame detection. One of:
12259 ``tff'' (top field first), ``bff'' (bottom field first),
12260 ``progressive'', or ``undetermined''
12263 Cumulative number of frames detected as bottom field first using multiple-frame detection.
12265 @item single.progressive
12266 Cumulative number of frames detected as progressive using single-frame detection.
12268 @item multiple.progressive
12269 Cumulative number of frames detected as progressive using multiple-frame detection.
12271 @item single.undetermined
12272 Cumulative number of frames that could not be classified using single-frame detection.
12274 @item multiple.undetermined
12275 Cumulative number of frames that could not be classified using multiple-frame detection.
12277 @item repeated.current_frame
12278 Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
12280 @item repeated.neither
12281 Cumulative number of frames with no repeated field.
12284 Cumulative number of frames with the top field repeated from the previous frame's top field.
12286 @item repeated.bottom
12287 Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
12290 The filter accepts the following options:
12294 Set interlacing threshold.
12296 Set progressive threshold.
12298 Threshold for repeated field detection.
12300 Number of frames after which a given frame's contribution to the
12301 statistics is halved (i.e., it contributes only 0.5 to its
12302 classification). The default of 0 means that all frames seen are given
12303 full weight of 1.0 forever.
12304 @item analyze_interlaced_flag
12305 When this is not 0 then idet will use the specified number of frames to determine
12306 if the interlaced flag is accurate, it will not count undetermined frames.
12307 If the flag is found to be accurate it will be used without any further
12308 computations, if it is found to be inaccurate it will be cleared without any
12309 further computations. This allows inserting the idet filter as a low computational
12310 method to clean up the interlaced flag
12315 Deinterleave or interleave fields.
12317 This filter allows one to process interlaced images fields without
12318 deinterlacing them. Deinterleaving splits the input frame into 2
12319 fields (so called half pictures). Odd lines are moved to the top
12320 half of the output image, even lines to the bottom half.
12321 You can process (filter) them independently and then re-interleave them.
12323 The filter accepts the following options:
12327 @item chroma_mode, c
12328 @item alpha_mode, a
12329 Available values for @var{luma_mode}, @var{chroma_mode} and
12330 @var{alpha_mode} are:
12336 @item deinterleave, d
12337 Deinterleave fields, placing one above the other.
12339 @item interleave, i
12340 Interleave fields. Reverse the effect of deinterleaving.
12342 Default value is @code{none}.
12344 @item luma_swap, ls
12345 @item chroma_swap, cs
12346 @item alpha_swap, as
12347 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
12350 @subsection Commands
12352 This filter supports the all above options as @ref{commands}.
12356 Apply inflate effect to the video.
12358 This filter replaces the pixel by the local(3x3) average by taking into account
12359 only values higher than the pixel.
12361 It accepts the following options:
12368 Limit the maximum change for each plane, default is 65535.
12369 If 0, plane will remain unchanged.
12372 @subsection Commands
12374 This filter supports the all above options as @ref{commands}.
12378 Simple interlacing filter from progressive contents. This interleaves upper (or
12379 lower) lines from odd frames with lower (or upper) lines from even frames,
12380 halving the frame rate and preserving image height.
12383 Original Original New Frame
12384 Frame 'j' Frame 'j+1' (tff)
12385 ========== =========== ==================
12386 Line 0 --------------------> Frame 'j' Line 0
12387 Line 1 Line 1 ----> Frame 'j+1' Line 1
12388 Line 2 ---------------------> Frame 'j' Line 2
12389 Line 3 Line 3 ----> Frame 'j+1' Line 3
12391 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
12394 It accepts the following optional parameters:
12398 This determines whether the interlaced frame is taken from the even
12399 (tff - default) or odd (bff) lines of the progressive frame.
12402 Vertical lowpass filter to avoid twitter interlacing and
12403 reduce moire patterns.
12407 Disable vertical lowpass filter
12410 Enable linear filter (default)
12413 Enable complex filter. This will slightly less reduce twitter and moire
12414 but better retain detail and subjective sharpness impression.
12421 Deinterlace input video by applying Donald Graft's adaptive kernel
12422 deinterling. Work on interlaced parts of a video to produce
12423 progressive frames.
12425 The description of the accepted parameters follows.
12429 Set the threshold which affects the filter's tolerance when
12430 determining if a pixel line must be processed. It must be an integer
12431 in the range [0,255] and defaults to 10. A value of 0 will result in
12432 applying the process on every pixels.
12435 Paint pixels exceeding the threshold value to white if set to 1.
12439 Set the fields order. Swap fields if set to 1, leave fields alone if
12443 Enable additional sharpening if set to 1. Default is 0.
12446 Enable twoway sharpening if set to 1. Default is 0.
12449 @subsection Examples
12453 Apply default values:
12455 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
12459 Enable additional sharpening:
12465 Paint processed pixels in white:
12473 Slowly update darker pixels.
12475 This filter makes short flashes of light appear longer.
12476 This filter accepts the following options:
12480 Set factor for decaying. Default is .95. Allowed range is from 0 to 1.
12483 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
12486 @section lenscorrection
12488 Correct radial lens distortion
12490 This filter can be used to correct for radial distortion as can result from the use
12491 of wide angle lenses, and thereby re-rectify the image. To find the right parameters
12492 one can use tools available for example as part of opencv or simply trial-and-error.
12493 To use opencv use the calibration sample (under samples/cpp) from the opencv sources
12494 and extract the k1 and k2 coefficients from the resulting matrix.
12496 Note that effectively the same filter is available in the open-source tools Krita and
12497 Digikam from the KDE project.
12499 In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
12500 this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
12501 brightness distribution, so you may want to use both filters together in certain
12502 cases, though you will have to take care of ordering, i.e. whether vignetting should
12503 be applied before or after lens correction.
12505 @subsection Options
12507 The filter accepts the following options:
12511 Relative x-coordinate of the focal point of the image, and thereby the center of the
12512 distortion. This value has a range [0,1] and is expressed as fractions of the image
12513 width. Default is 0.5.
12515 Relative y-coordinate of the focal point of the image, and thereby the center of the
12516 distortion. This value has a range [0,1] and is expressed as fractions of the image
12517 height. Default is 0.5.
12519 Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means
12520 no correction. Default is 0.
12522 Coefficient of the double quadratic correction term. This value has a range [-1,1].
12523 0 means no correction. Default is 0.
12526 The formula that generates the correction is:
12528 @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)
12530 where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
12531 distances from the focal point in the source and target images, respectively.
12535 Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}).
12537 The @code{lensfun} filter requires the camera make, camera model, and lens model
12538 to apply the lens correction. The filter will load the lensfun database and
12539 query it to find the corresponding camera and lens entries in the database. As
12540 long as these entries can be found with the given options, the filter can
12541 perform corrections on frames. Note that incomplete strings will result in the
12542 filter choosing the best match with the given options, and the filter will
12543 output the chosen camera and lens models (logged with level "info"). You must
12544 provide the make, camera model, and lens model as they are required.
12546 The filter accepts the following options:
12550 The make of the camera (for example, "Canon"). This option is required.
12553 The model of the camera (for example, "Canon EOS 100D"). This option is
12557 The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This
12558 option is required.
12561 The type of correction to apply. The following values are valid options:
12565 Enables fixing lens vignetting.
12568 Enables fixing lens geometry. This is the default.
12571 Enables fixing chromatic aberrations.
12574 Enables fixing lens vignetting and lens geometry.
12577 Enables fixing lens vignetting and chromatic aberrations.
12580 Enables fixing both lens geometry and chromatic aberrations.
12583 Enables all possible corrections.
12587 The focal length of the image/video (zoom; expected constant for video). For
12588 example, a 18--55mm lens has focal length range of [18--55], so a value in that
12589 range should be chosen when using that lens. Default 18.
12592 The aperture of the image/video (expected constant for video). Note that
12593 aperture is only used for vignetting correction. Default 3.5.
12595 @item focus_distance
12596 The focus distance of the image/video (expected constant for video). Note that
12597 focus distance is only used for vignetting and only slightly affects the
12598 vignetting correction process. If unknown, leave it at the default value (which
12602 The scale factor which is applied after transformation. After correction the
12603 video is no longer necessarily rectangular. This parameter controls how much of
12604 the resulting image is visible. The value 0 means that a value will be chosen
12605 automatically such that there is little or no unmapped area in the output
12606 image. 1.0 means that no additional scaling is done. Lower values may result
12607 in more of the corrected image being visible, while higher values may avoid
12608 unmapped areas in the output.
12610 @item target_geometry
12611 The target geometry of the output image/video. The following values are valid
12615 @item rectilinear (default)
12618 @item equirectangular
12619 @item fisheye_orthographic
12620 @item fisheye_stereographic
12621 @item fisheye_equisolid
12622 @item fisheye_thoby
12625 Apply the reverse of image correction (instead of correcting distortion, apply
12628 @item interpolation
12629 The type of interpolation used when correcting distortion. The following values
12634 @item linear (default)
12639 @subsection Examples
12643 Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens
12644 model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and
12648 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
12652 Apply the same as before, but only for the first 5 seconds of video.
12655 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
12662 Obtain the VMAF (Video Multi-Method Assessment Fusion)
12663 score between two input videos.
12665 The obtained VMAF score is printed through the logging system.
12667 It requires Netflix's vmaf library (libvmaf) as a pre-requisite.
12668 After installing the library it can be enabled using:
12669 @code{./configure --enable-libvmaf --enable-version3}.
12670 If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}.
12672 The filter has following options:
12676 Set the model path which is to be used for SVM.
12677 Default value: @code{"/usr/local/share/model/vmaf_v0.6.1.pkl"}
12680 Set the file path to be used to store logs.
12683 Set the format of the log file (xml or json).
12685 @item enable_transform
12686 This option can enable/disable the @code{score_transform} applied to the final predicted VMAF score,
12687 if you have specified score_transform option in the input parameter file passed to @code{run_vmaf_training.py}
12688 Default value: @code{false}
12691 Invokes the phone model which will generate VMAF scores higher than in the
12692 regular model, which is more suitable for laptop, TV, etc. viewing conditions.
12693 Default value: @code{false}
12696 Enables computing psnr along with vmaf.
12697 Default value: @code{false}
12700 Enables computing ssim along with vmaf.
12701 Default value: @code{false}
12704 Enables computing ms_ssim along with vmaf.
12705 Default value: @code{false}
12708 Set the pool method to be used for computing vmaf.
12709 Options are @code{min}, @code{harmonic_mean} or @code{mean} (default).
12712 Set number of threads to be used when computing vmaf.
12713 Default value: @code{0}, which makes use of all available logical processors.
12716 Set interval for frame subsampling used when computing vmaf.
12717 Default value: @code{1}
12719 @item enable_conf_interval
12720 Enables confidence interval.
12721 Default value: @code{false}
12724 This filter also supports the @ref{framesync} options.
12726 @subsection Examples
12729 On the below examples the input file @file{main.mpg} being processed is
12730 compared with the reference file @file{ref.mpg}.
12733 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
12737 Example with options:
12739 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:log_fmt=json" -f null -
12743 Example with options and different containers:
12745 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 -
12751 Limits the pixel components values to the specified range [min, max].
12753 The filter accepts the following options:
12757 Lower bound. Defaults to the lowest allowed value for the input.
12760 Upper bound. Defaults to the highest allowed value for the input.
12763 Specify which planes will be processed. Defaults to all available.
12770 The filter accepts the following options:
12774 Set the number of loops. Setting this value to -1 will result in infinite loops.
12778 Set maximal size in number of frames. Default is 0.
12781 Set first frame of loop. Default is 0.
12784 @subsection Examples
12788 Loop single first frame infinitely:
12790 loop=loop=-1:size=1:start=0
12794 Loop single first frame 10 times:
12796 loop=loop=10:size=1:start=0
12800 Loop 10 first frames 5 times:
12802 loop=loop=5:size=10:start=0
12808 Apply a 1D LUT to an input video.
12810 The filter accepts the following options:
12814 Set the 1D LUT file name.
12816 Currently supported formats:
12825 Select interpolation mode.
12827 Available values are:
12831 Use values from the nearest defined point.
12833 Interpolate values using the linear interpolation.
12835 Interpolate values using the cosine interpolation.
12837 Interpolate values using the cubic interpolation.
12839 Interpolate values using the spline interpolation.
12846 Apply a 3D LUT to an input video.
12848 The filter accepts the following options:
12852 Set the 3D LUT file name.
12854 Currently supported formats:
12868 Select interpolation mode.
12870 Available values are:
12874 Use values from the nearest defined point.
12876 Interpolate values using the 8 points defining a cube.
12878 Interpolate values using a tetrahedron.
12884 Turn certain luma values into transparency.
12886 The filter accepts the following options:
12890 Set the luma which will be used as base for transparency.
12891 Default value is @code{0}.
12894 Set the range of luma values to be keyed out.
12895 Default value is @code{0.01}.
12898 Set the range of softness. Default value is @code{0}.
12899 Use this to control gradual transition from zero to full transparency.
12902 @subsection Commands
12903 This filter supports same @ref{commands} as options.
12904 The command accepts the same syntax of the corresponding option.
12906 If the specified expression is not valid, it is kept at its current
12909 @section lut, lutrgb, lutyuv
12911 Compute a look-up table for binding each pixel component input value
12912 to an output value, and apply it to the input video.
12914 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
12915 to an RGB input video.
12917 These filters accept the following parameters:
12920 set first pixel component expression
12922 set second pixel component expression
12924 set third pixel component expression
12926 set fourth pixel component expression, corresponds to the alpha component
12929 set red component expression
12931 set green component expression
12933 set blue component expression
12935 alpha component expression
12938 set Y/luminance component expression
12940 set U/Cb component expression
12942 set V/Cr component expression
12945 Each of them specifies the expression to use for computing the lookup table for
12946 the corresponding pixel component values.
12948 The exact component associated to each of the @var{c*} options depends on the
12951 The @var{lut} filter requires either YUV or RGB pixel formats in input,
12952 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
12954 The expressions can contain the following constants and functions:
12959 The input width and height.
12962 The input value for the pixel component.
12965 The input value, clipped to the @var{minval}-@var{maxval} range.
12968 The maximum value for the pixel component.
12971 The minimum value for the pixel component.
12974 The negated value for the pixel component value, clipped to the
12975 @var{minval}-@var{maxval} range; it corresponds to the expression
12976 "maxval-clipval+minval".
12979 The computed value in @var{val}, clipped to the
12980 @var{minval}-@var{maxval} range.
12982 @item gammaval(gamma)
12983 The computed gamma correction value of the pixel component value,
12984 clipped to the @var{minval}-@var{maxval} range. It corresponds to the
12986 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
12990 All expressions default to "val".
12992 @subsection Examples
12996 Negate input video:
12998 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
12999 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
13002 The above is the same as:
13004 lutrgb="r=negval:g=negval:b=negval"
13005 lutyuv="y=negval:u=negval:v=negval"
13015 Remove chroma components, turning the video into a graytone image:
13017 lutyuv="u=128:v=128"
13021 Apply a luma burning effect:
13027 Remove green and blue components:
13033 Set a constant alpha channel value on input:
13035 format=rgba,lutrgb=a="maxval-minval/2"
13039 Correct luminance gamma by a factor of 0.5:
13041 lutyuv=y=gammaval(0.5)
13045 Discard least significant bits of luma:
13047 lutyuv=y='bitand(val, 128+64+32)'
13051 Technicolor like effect:
13053 lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
13057 @section lut2, tlut2
13059 The @code{lut2} filter takes two input streams and outputs one
13062 The @code{tlut2} (time lut2) filter takes two consecutive frames
13063 from one single stream.
13065 This filter accepts the following parameters:
13068 set first pixel component expression
13070 set second pixel component expression
13072 set third pixel component expression
13074 set fourth pixel component expression, corresponds to the alpha component
13077 set output bit depth, only available for @code{lut2} filter. By default is 0,
13078 which means bit depth is automatically picked from first input format.
13081 Each of them specifies the expression to use for computing the lookup table for
13082 the corresponding pixel component values.
13084 The exact component associated to each of the @var{c*} options depends on the
13087 The expressions can contain the following constants:
13092 The input width and height.
13095 The first input value for the pixel component.
13098 The second input value for the pixel component.
13101 The first input video bit depth.
13104 The second input video bit depth.
13107 All expressions default to "x".
13109 @subsection Examples
13113 Highlight differences between two RGB video streams:
13115 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)'
13119 Highlight differences between two YUV video streams:
13121 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)'
13125 Show max difference between two video streams:
13127 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)))'
13131 @section maskedclamp
13133 Clamp the first input stream with the second input and third input stream.
13135 Returns the value of first stream to be between second input
13136 stream - @code{undershoot} and third input stream + @code{overshoot}.
13138 This filter accepts the following options:
13141 Default value is @code{0}.
13144 Default value is @code{0}.
13147 Set which planes will be processed as bitmap, unprocessed planes will be
13148 copied from first stream.
13149 By default value 0xf, all planes will be processed.
13154 Merge the second and third input stream into output stream using absolute differences
13155 between second input stream and first input stream and absolute difference between
13156 third input stream and first input stream. The picked value will be from second input
13157 stream if second absolute difference is greater than first one or from third input stream
13160 This filter accepts the following options:
13163 Set which planes will be processed as bitmap, unprocessed planes will be
13164 copied from first stream.
13165 By default value 0xf, all planes will be processed.
13168 @section maskedmerge
13170 Merge the first input stream with the second input stream using per pixel
13171 weights in the third input stream.
13173 A value of 0 in the third stream pixel component means that pixel component
13174 from first stream is returned unchanged, while maximum value (eg. 255 for
13175 8-bit videos) means that pixel component from second stream is returned
13176 unchanged. Intermediate values define the amount of merging between both
13177 input stream's pixel components.
13179 This filter accepts the following options:
13182 Set which planes will be processed as bitmap, unprocessed planes will be
13183 copied from first stream.
13184 By default value 0xf, all planes will be processed.
13189 Merge the second and third input stream into output stream using absolute differences
13190 between second input stream and first input stream and absolute difference between
13191 third input stream and first input stream. The picked value will be from second input
13192 stream if second absolute difference is less than first one or from third input stream
13195 This filter accepts the following options:
13198 Set which planes will be processed as bitmap, unprocessed planes will be
13199 copied from first stream.
13200 By default value 0xf, all planes will be processed.
13204 Create mask from input video.
13206 For example it is useful to create motion masks after @code{tblend} filter.
13208 This filter accepts the following options:
13212 Set low threshold. Any pixel component lower or exact than this value will be set to 0.
13215 Set high threshold. Any pixel component higher than this value will be set to max value
13216 allowed for current pixel format.
13219 Set planes to filter, by default all available planes are filtered.
13222 Fill all frame pixels with this value.
13225 Set max average pixel value for frame. If sum of all pixel components is higher that this
13226 average, output frame will be completely filled with value set by @var{fill} option.
13227 Typically useful for scene changes when used in combination with @code{tblend} filter.
13232 Apply motion-compensation deinterlacing.
13234 It needs one field per frame as input and must thus be used together
13235 with yadif=1/3 or equivalent.
13237 This filter accepts the following options:
13240 Set the deinterlacing mode.
13242 It accepts one of the following values:
13247 use iterative motion estimation
13249 like @samp{slow}, but use multiple reference frames.
13251 Default value is @samp{fast}.
13254 Set the picture field parity assumed for the input video. It must be
13255 one of the following values:
13259 assume top field first
13261 assume bottom field first
13264 Default value is @samp{bff}.
13267 Set per-block quantization parameter (QP) used by the internal
13270 Higher values should result in a smoother motion vector field but less
13271 optimal individual vectors. Default value is 1.
13276 Pick median pixel from certain rectangle defined by radius.
13278 This filter accepts the following options:
13282 Set horizontal radius size. Default value is @code{1}.
13283 Allowed range is integer from 1 to 127.
13286 Set which planes to process. Default is @code{15}, which is all available planes.
13289 Set vertical radius size. Default value is @code{0}.
13290 Allowed range is integer from 0 to 127.
13291 If it is 0, value will be picked from horizontal @code{radius} option.
13294 @subsection Commands
13295 This filter supports same @ref{commands} as options.
13296 The command accepts the same syntax of the corresponding option.
13298 If the specified expression is not valid, it is kept at its current
13301 @section mergeplanes
13303 Merge color channel components from several video streams.
13305 The filter accepts up to 4 input streams, and merge selected input
13306 planes to the output video.
13308 This filter accepts the following options:
13311 Set input to output plane mapping. Default is @code{0}.
13313 The mappings is specified as a bitmap. It should be specified as a
13314 hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
13315 mapping for the first plane of the output stream. 'A' sets the number of
13316 the input stream to use (from 0 to 3), and 'a' the plane number of the
13317 corresponding input to use (from 0 to 3). The rest of the mappings is
13318 similar, 'Bb' describes the mapping for the output stream second
13319 plane, 'Cc' describes the mapping for the output stream third plane and
13320 'Dd' describes the mapping for the output stream fourth plane.
13323 Set output pixel format. Default is @code{yuva444p}.
13326 @subsection Examples
13330 Merge three gray video streams of same width and height into single video stream:
13332 [a0][a1][a2]mergeplanes=0x001020:yuv444p
13336 Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
13338 [a0][a1]mergeplanes=0x00010210:yuva444p
13342 Swap Y and A plane in yuva444p stream:
13344 format=yuva444p,mergeplanes=0x03010200:yuva444p
13348 Swap U and V plane in yuv420p stream:
13350 format=yuv420p,mergeplanes=0x000201:yuv420p
13354 Cast a rgb24 clip to yuv444p:
13356 format=rgb24,mergeplanes=0x000102:yuv444p
13362 Estimate and export motion vectors using block matching algorithms.
13363 Motion vectors are stored in frame side data to be used by other filters.
13365 This filter accepts the following options:
13368 Specify the motion estimation method. Accepts one of the following values:
13372 Exhaustive search algorithm.
13374 Three step search algorithm.
13376 Two dimensional logarithmic search algorithm.
13378 New three step search algorithm.
13380 Four step search algorithm.
13382 Diamond search algorithm.
13384 Hexagon-based search algorithm.
13386 Enhanced predictive zonal search algorithm.
13388 Uneven multi-hexagon search algorithm.
13390 Default value is @samp{esa}.
13393 Macroblock size. Default @code{16}.
13396 Search parameter. Default @code{7}.
13399 @section midequalizer
13401 Apply Midway Image Equalization effect using two video streams.
13403 Midway Image Equalization adjusts a pair of images to have the same
13404 histogram, while maintaining their dynamics as much as possible. It's
13405 useful for e.g. matching exposures from a pair of stereo cameras.
13407 This filter has two inputs and one output, which must be of same pixel format, but
13408 may be of different sizes. The output of filter is first input adjusted with
13409 midway histogram of both inputs.
13411 This filter accepts the following option:
13415 Set which planes to process. Default is @code{15}, which is all available planes.
13418 @section minterpolate
13420 Convert the video to specified frame rate using motion interpolation.
13422 This filter accepts the following options:
13425 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}.
13428 Motion interpolation mode. Following values are accepted:
13431 Duplicate previous or next frame for interpolating new ones.
13433 Blend source frames. Interpolated frame is mean of previous and next frames.
13435 Motion compensated interpolation. Following options are effective when this mode is selected:
13439 Motion compensation mode. Following values are accepted:
13442 Overlapped block motion compensation.
13444 Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
13446 Default mode is @samp{obmc}.
13449 Motion estimation mode. Following values are accepted:
13452 Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
13454 Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
13456 Default mode is @samp{bilat}.
13459 The algorithm to be used for motion estimation. Following values are accepted:
13462 Exhaustive search algorithm.
13464 Three step search algorithm.
13466 Two dimensional logarithmic search algorithm.
13468 New three step search algorithm.
13470 Four step search algorithm.
13472 Diamond search algorithm.
13474 Hexagon-based search algorithm.
13476 Enhanced predictive zonal search algorithm.
13478 Uneven multi-hexagon search algorithm.
13480 Default algorithm is @samp{epzs}.
13483 Macroblock size. Default @code{16}.
13486 Motion estimation search parameter. Default @code{32}.
13489 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).
13494 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:
13497 Disable scene change detection.
13499 Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected.
13501 Default method is @samp{fdiff}.
13503 @item scd_threshold
13504 Scene change detection threshold. Default is @code{5.0}.
13509 Mix several video input streams into one video stream.
13511 A description of the accepted options follows.
13515 The number of inputs. If unspecified, it defaults to 2.
13518 Specify weight of each input video stream as sequence.
13519 Each weight is separated by space. If number of weights
13520 is smaller than number of @var{frames} last specified
13521 weight will be used for all remaining unset weights.
13524 Specify scale, if it is set it will be multiplied with sum
13525 of each weight multiplied with pixel values to give final destination
13526 pixel value. By default @var{scale} is auto scaled to sum of weights.
13529 Specify how end of stream is determined.
13532 The duration of the longest input. (default)
13535 The duration of the shortest input.
13538 The duration of the first input.
13542 @section mpdecimate
13544 Drop frames that do not differ greatly from the previous frame in
13545 order to reduce frame rate.
13547 The main use of this filter is for very-low-bitrate encoding
13548 (e.g. streaming over dialup modem), but it could in theory be used for
13549 fixing movies that were inverse-telecined incorrectly.
13551 A description of the accepted options follows.
13555 Set the maximum number of consecutive frames which can be dropped (if
13556 positive), or the minimum interval between dropped frames (if
13557 negative). If the value is 0, the frame is dropped disregarding the
13558 number of previous sequentially dropped frames.
13560 Default value is 0.
13565 Set the dropping threshold values.
13567 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
13568 represent actual pixel value differences, so a threshold of 64
13569 corresponds to 1 unit of difference for each pixel, or the same spread
13570 out differently over the block.
13572 A frame is a candidate for dropping if no 8x8 blocks differ by more
13573 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
13574 meaning the whole image) differ by more than a threshold of @option{lo}.
13576 Default value for @option{hi} is 64*12, default value for @option{lo} is
13577 64*5, and default value for @option{frac} is 0.33.
13583 Negate (invert) the input video.
13585 It accepts the following option:
13590 With value 1, it negates the alpha component, if present. Default value is 0.
13596 Denoise frames using Non-Local Means algorithm.
13598 Each pixel is adjusted by looking for other pixels with similar contexts. This
13599 context similarity is defined by comparing their surrounding patches of size
13600 @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
13603 Note that the research area defines centers for patches, which means some
13604 patches will be made of pixels outside that research area.
13606 The filter accepts the following options.
13610 Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0].
13613 Set patch size. Default is 7. Must be odd number in range [0, 99].
13616 Same as @option{p} but for chroma planes.
13618 The default value is @var{0} and means automatic.
13621 Set research size. Default is 15. Must be odd number in range [0, 99].
13624 Same as @option{r} but for chroma planes.
13626 The default value is @var{0} and means automatic.
13631 Deinterlace video using neural network edge directed interpolation.
13633 This filter accepts the following options:
13637 Mandatory option, without binary file filter can not work.
13638 Currently file can be found here:
13639 https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
13642 Set which frames to deinterlace, by default it is @code{all}.
13643 Can be @code{all} or @code{interlaced}.
13646 Set mode of operation.
13648 Can be one of the following:
13652 Use frame flags, both fields.
13654 Use frame flags, single field.
13656 Use top field only.
13658 Use bottom field only.
13660 Use both fields, top first.
13662 Use both fields, bottom first.
13666 Set which planes to process, by default filter process all frames.
13669 Set size of local neighborhood around each pixel, used by the predictor neural
13672 Can be one of the following:
13685 Set the number of neurons in predictor neural network.
13686 Can be one of the following:
13697 Controls the number of different neural network predictions that are blended
13698 together to compute the final output value. Can be @code{fast}, default or
13702 Set which set of weights to use in the predictor.
13703 Can be one of the following:
13707 weights trained to minimize absolute error
13709 weights trained to minimize squared error
13713 Controls whether or not the prescreener neural network is used to decide
13714 which pixels should be processed by the predictor neural network and which
13715 can be handled by simple cubic interpolation.
13716 The prescreener is trained to know whether cubic interpolation will be
13717 sufficient for a pixel or whether it should be predicted by the predictor nn.
13718 The computational complexity of the prescreener nn is much less than that of
13719 the predictor nn. Since most pixels can be handled by cubic interpolation,
13720 using the prescreener generally results in much faster processing.
13721 The prescreener is pretty accurate, so the difference between using it and not
13722 using it is almost always unnoticeable.
13724 Can be one of the following:
13732 Default is @code{new}.
13735 Set various debugging flags.
13740 Force libavfilter not to use any of the specified pixel formats for the
13741 input to the next filter.
13743 It accepts the following parameters:
13747 A '|'-separated list of pixel format names, such as
13748 pix_fmts=yuv420p|monow|rgb24".
13752 @subsection Examples
13756 Force libavfilter to use a format different from @var{yuv420p} for the
13757 input to the vflip filter:
13759 noformat=pix_fmts=yuv420p,vflip
13763 Convert the input video to any of the formats not contained in the list:
13765 noformat=yuv420p|yuv444p|yuv410p
13771 Add noise on video input frame.
13773 The filter accepts the following options:
13781 Set noise seed for specific pixel component or all pixel components in case
13782 of @var{all_seed}. Default value is @code{123457}.
13784 @item all_strength, alls
13785 @item c0_strength, c0s
13786 @item c1_strength, c1s
13787 @item c2_strength, c2s
13788 @item c3_strength, c3s
13789 Set noise strength for specific pixel component or all pixel components in case
13790 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
13792 @item all_flags, allf
13793 @item c0_flags, c0f
13794 @item c1_flags, c1f
13795 @item c2_flags, c2f
13796 @item c3_flags, c3f
13797 Set pixel component flags or set flags for all components if @var{all_flags}.
13798 Available values for component flags are:
13801 averaged temporal noise (smoother)
13803 mix random noise with a (semi)regular pattern
13805 temporal noise (noise pattern changes between frames)
13807 uniform noise (gaussian otherwise)
13811 @subsection Examples
13813 Add temporal and uniform noise to input video:
13815 noise=alls=20:allf=t+u
13820 Normalize RGB video (aka histogram stretching, contrast stretching).
13821 See: https://en.wikipedia.org/wiki/Normalization_(image_processing)
13823 For each channel of each frame, the filter computes the input range and maps
13824 it linearly to the user-specified output range. The output range defaults
13825 to the full dynamic range from pure black to pure white.
13827 Temporal smoothing can be used on the input range to reduce flickering (rapid
13828 changes in brightness) caused when small dark or bright objects enter or leave
13829 the scene. This is similar to the auto-exposure (automatic gain control) on a
13830 video camera, and, like a video camera, it may cause a period of over- or
13831 under-exposure of the video.
13833 The R,G,B channels can be normalized independently, which may cause some
13834 color shifting, or linked together as a single channel, which prevents
13835 color shifting. Linked normalization preserves hue. Independent normalization
13836 does not, so it can be used to remove some color casts. Independent and linked
13837 normalization can be combined in any ratio.
13839 The normalize filter accepts the following options:
13844 Colors which define the output range. The minimum input value is mapped to
13845 the @var{blackpt}. The maximum input value is mapped to the @var{whitept}.
13846 The defaults are black and white respectively. Specifying white for
13847 @var{blackpt} and black for @var{whitept} will give color-inverted,
13848 normalized video. Shades of grey can be used to reduce the dynamic range
13849 (contrast). Specifying saturated colors here can create some interesting
13853 The number of previous frames to use for temporal smoothing. The input range
13854 of each channel is smoothed using a rolling average over the current frame
13855 and the @var{smoothing} previous frames. The default is 0 (no temporal
13859 Controls the ratio of independent (color shifting) channel normalization to
13860 linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully
13861 independent. Defaults to 1.0 (fully independent).
13864 Overall strength of the filter. 1.0 is full strength. 0.0 is a rather
13865 expensive no-op. Defaults to 1.0 (full strength).
13869 @subsection Commands
13870 This filter supports same @ref{commands} as options, excluding @var{smoothing} option.
13871 The command accepts the same syntax of the corresponding option.
13873 If the specified expression is not valid, it is kept at its current
13876 @subsection Examples
13878 Stretch video contrast to use the full dynamic range, with no temporal
13879 smoothing; may flicker depending on the source content:
13881 normalize=blackpt=black:whitept=white:smoothing=0
13884 As above, but with 50 frames of temporal smoothing; flicker should be
13885 reduced, depending on the source content:
13887 normalize=blackpt=black:whitept=white:smoothing=50
13890 As above, but with hue-preserving linked channel normalization:
13892 normalize=blackpt=black:whitept=white:smoothing=50:independence=0
13895 As above, but with half strength:
13897 normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
13900 Map the darkest input color to red, the brightest input color to cyan:
13902 normalize=blackpt=red:whitept=cyan
13907 Pass the video source unchanged to the output.
13910 Optical Character Recognition
13912 This filter uses Tesseract for optical character recognition. To enable
13913 compilation of this filter, you need to configure FFmpeg with
13914 @code{--enable-libtesseract}.
13916 It accepts the following options:
13920 Set datapath to tesseract data. Default is to use whatever was
13921 set at installation.
13924 Set language, default is "eng".
13927 Set character whitelist.
13930 Set character blacklist.
13933 The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
13934 The filter exports confidence of recognized words as the frame metadata @code{lavfi.ocr.confidence}.
13938 Apply a video transform using libopencv.
13940 To enable this filter, install the libopencv library and headers and
13941 configure FFmpeg with @code{--enable-libopencv}.
13943 It accepts the following parameters:
13948 The name of the libopencv filter to apply.
13950 @item filter_params
13951 The parameters to pass to the libopencv filter. If not specified, the default
13952 values are assumed.
13956 Refer to the official libopencv documentation for more precise
13958 @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
13960 Several libopencv filters are supported; see the following subsections.
13965 Dilate an image by using a specific structuring element.
13966 It corresponds to the libopencv function @code{cvDilate}.
13968 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
13970 @var{struct_el} represents a structuring element, and has the syntax:
13971 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
13973 @var{cols} and @var{rows} represent the number of columns and rows of
13974 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
13975 point, and @var{shape} the shape for the structuring element. @var{shape}
13976 must be "rect", "cross", "ellipse", or "custom".
13978 If the value for @var{shape} is "custom", it must be followed by a
13979 string of the form "=@var{filename}". The file with name
13980 @var{filename} is assumed to represent a binary image, with each
13981 printable character corresponding to a bright pixel. When a custom
13982 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
13983 or columns and rows of the read file are assumed instead.
13985 The default value for @var{struct_el} is "3x3+0x0/rect".
13987 @var{nb_iterations} specifies the number of times the transform is
13988 applied to the image, and defaults to 1.
13992 # Use the default values
13995 # Dilate using a structuring element with a 5x5 cross, iterating two times
13996 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
13998 # Read the shape from the file diamond.shape, iterating two times.
13999 # The file diamond.shape may contain a pattern of characters like this
14005 # The specified columns and rows are ignored
14006 # but the anchor point coordinates are not
14007 ocv=dilate:0x0+2x2/custom=diamond.shape|2
14012 Erode an image by using a specific structuring element.
14013 It corresponds to the libopencv function @code{cvErode}.
14015 It accepts the parameters: @var{struct_el}:@var{nb_iterations},
14016 with the same syntax and semantics as the @ref{dilate} filter.
14020 Smooth the input video.
14022 The filter takes the following parameters:
14023 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
14025 @var{type} is the type of smooth filter to apply, and must be one of
14026 the following values: "blur", "blur_no_scale", "median", "gaussian",
14027 or "bilateral". The default value is "gaussian".
14029 The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
14030 depends on the smooth type. @var{param1} and
14031 @var{param2} accept integer positive values or 0. @var{param3} and
14032 @var{param4} accept floating point values.
14034 The default value for @var{param1} is 3. The default value for the
14035 other parameters is 0.
14037 These parameters correspond to the parameters assigned to the
14038 libopencv function @code{cvSmooth}.
14040 @section oscilloscope
14042 2D Video Oscilloscope.
14044 Useful to measure spatial impulse, step responses, chroma delays, etc.
14046 It accepts the following parameters:
14050 Set scope center x position.
14053 Set scope center y position.
14056 Set scope size, relative to frame diagonal.
14059 Set scope tilt/rotation.
14065 Set trace center x position.
14068 Set trace center y position.
14071 Set trace width, relative to width of frame.
14074 Set trace height, relative to height of frame.
14077 Set which components to trace. By default it traces first three components.
14080 Draw trace grid. By default is enabled.
14083 Draw some statistics. By default is enabled.
14086 Draw scope. By default is enabled.
14089 @subsection Commands
14090 This filter supports same @ref{commands} as options.
14091 The command accepts the same syntax of the corresponding option.
14093 If the specified expression is not valid, it is kept at its current
14096 @subsection Examples
14100 Inspect full first row of video frame.
14102 oscilloscope=x=0.5:y=0:s=1
14106 Inspect full last row of video frame.
14108 oscilloscope=x=0.5:y=1:s=1
14112 Inspect full 5th line of video frame of height 1080.
14114 oscilloscope=x=0.5:y=5/1080:s=1
14118 Inspect full last column of video frame.
14120 oscilloscope=x=1:y=0.5:s=1:t=1
14128 Overlay one video on top of another.
14130 It takes two inputs and has one output. The first input is the "main"
14131 video on which the second input is overlaid.
14133 It accepts the following parameters:
14135 A description of the accepted options follows.
14140 Set the expression for the x and y coordinates of the overlaid video
14141 on the main video. Default value is "0" for both expressions. In case
14142 the expression is invalid, it is set to a huge value (meaning that the
14143 overlay will not be displayed within the output visible area).
14146 See @ref{framesync}.
14149 Set when the expressions for @option{x}, and @option{y} are evaluated.
14151 It accepts the following values:
14154 only evaluate expressions once during the filter initialization or
14155 when a command is processed
14158 evaluate expressions for each incoming frame
14161 Default value is @samp{frame}.
14164 See @ref{framesync}.
14167 Set the format for the output video.
14169 It accepts the following values:
14172 force YUV420 output
14175 force YUV422 output
14178 force YUV444 output
14181 force packed RGB output
14184 force planar RGB output
14187 automatically pick format
14190 Default value is @samp{yuv420}.
14193 See @ref{framesync}.
14196 Set format of alpha of the overlaid video, it can be @var{straight} or
14197 @var{premultiplied}. Default is @var{straight}.
14200 The @option{x}, and @option{y} expressions can contain the following
14206 The main input width and height.
14210 The overlay input width and height.
14214 The computed values for @var{x} and @var{y}. They are evaluated for
14219 horizontal and vertical chroma subsample values of the output
14220 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
14224 the number of input frame, starting from 0
14227 the position in the file of the input frame, NAN if unknown
14230 The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
14234 This filter also supports the @ref{framesync} options.
14236 Note that the @var{n}, @var{pos}, @var{t} variables are available only
14237 when evaluation is done @emph{per frame}, and will evaluate to NAN
14238 when @option{eval} is set to @samp{init}.
14240 Be aware that frames are taken from each input video in timestamp
14241 order, hence, if their initial timestamps differ, it is a good idea
14242 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
14243 have them begin in the same zero timestamp, as the example for
14244 the @var{movie} filter does.
14246 You can chain together more overlays but you should test the
14247 efficiency of such approach.
14249 @subsection Commands
14251 This filter supports the following commands:
14255 Modify the x and y of the overlay input.
14256 The command accepts the same syntax of the corresponding option.
14258 If the specified expression is not valid, it is kept at its current
14262 @subsection Examples
14266 Draw the overlay at 10 pixels from the bottom right corner of the main
14269 overlay=main_w-overlay_w-10:main_h-overlay_h-10
14272 Using named options the example above becomes:
14274 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
14278 Insert a transparent PNG logo in the bottom left corner of the input,
14279 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
14281 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
14285 Insert 2 different transparent PNG logos (second logo on bottom
14286 right corner) using the @command{ffmpeg} tool:
14288 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
14292 Add a transparent color layer on top of the main video; @code{WxH}
14293 must specify the size of the main input to the overlay filter:
14295 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
14299 Play an original video and a filtered version (here with the deshake
14300 filter) side by side using the @command{ffplay} tool:
14302 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
14305 The above command is the same as:
14307 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
14311 Make a sliding overlay appearing from the left to the right top part of the
14312 screen starting since time 2:
14314 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
14318 Compose output by putting two input videos side to side:
14320 ffmpeg -i left.avi -i right.avi -filter_complex "
14321 nullsrc=size=200x100 [background];
14322 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
14323 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
14324 [background][left] overlay=shortest=1 [background+left];
14325 [background+left][right] overlay=shortest=1:x=100 [left+right]
14330 Mask 10-20 seconds of a video by applying the delogo filter to a section
14332 ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
14333 -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]'
14338 Chain several overlays in cascade:
14340 nullsrc=s=200x200 [bg];
14341 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
14342 [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
14343 [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
14344 [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
14345 [in3] null, [mid2] overlay=100:100 [out0]
14352 Apply Overcomplete Wavelet denoiser.
14354 The filter accepts the following options:
14360 Larger depth values will denoise lower frequency components more, but
14361 slow down filtering.
14363 Must be an int in the range 8-16, default is @code{8}.
14365 @item luma_strength, ls
14368 Must be a double value in the range 0-1000, default is @code{1.0}.
14370 @item chroma_strength, cs
14371 Set chroma strength.
14373 Must be a double value in the range 0-1000, default is @code{1.0}.
14379 Add paddings to the input image, and place the original input at the
14380 provided @var{x}, @var{y} coordinates.
14382 It accepts the following parameters:
14387 Specify an expression for the size of the output image with the
14388 paddings added. If the value for @var{width} or @var{height} is 0, the
14389 corresponding input size is used for the output.
14391 The @var{width} expression can reference the value set by the
14392 @var{height} expression, and vice versa.
14394 The default value of @var{width} and @var{height} is 0.
14398 Specify the offsets to place the input image at within the padded area,
14399 with respect to the top/left border of the output image.
14401 The @var{x} expression can reference the value set by the @var{y}
14402 expression, and vice versa.
14404 The default value of @var{x} and @var{y} is 0.
14406 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
14407 so the input image is centered on the padded area.
14410 Specify the color of the padded area. For the syntax of this option,
14411 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
14412 manual,ffmpeg-utils}.
14414 The default value of @var{color} is "black".
14417 Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression.
14419 It accepts the following values:
14423 Only evaluate expressions once during the filter initialization or when
14424 a command is processed.
14427 Evaluate expressions for each incoming frame.
14431 Default value is @samp{init}.
14434 Pad to aspect instead to a resolution.
14438 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
14439 options are expressions containing the following constants:
14444 The input video width and height.
14448 These are the same as @var{in_w} and @var{in_h}.
14452 The output width and height (the size of the padded area), as
14453 specified by the @var{width} and @var{height} expressions.
14457 These are the same as @var{out_w} and @var{out_h}.
14461 The x and y offsets as specified by the @var{x} and @var{y}
14462 expressions, or NAN if not yet specified.
14465 same as @var{iw} / @var{ih}
14468 input sample aspect ratio
14471 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
14475 The horizontal and vertical chroma subsample values. For example for the
14476 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14479 @subsection Examples
14483 Add paddings with the color "violet" to the input video. The output video
14484 size is 640x480, and the top-left corner of the input video is placed at
14487 pad=640:480:0:40:violet
14490 The example above is equivalent to the following command:
14492 pad=width=640:height=480:x=0:y=40:color=violet
14496 Pad the input to get an output with dimensions increased by 3/2,
14497 and put the input video at the center of the padded area:
14499 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
14503 Pad the input to get a squared output with size equal to the maximum
14504 value between the input width and height, and put the input video at
14505 the center of the padded area:
14507 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
14511 Pad the input to get a final w/h ratio of 16:9:
14513 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
14517 In case of anamorphic video, in order to set the output display aspect
14518 correctly, it is necessary to use @var{sar} in the expression,
14519 according to the relation:
14521 (ih * X / ih) * sar = output_dar
14522 X = output_dar / sar
14525 Thus the previous example needs to be modified to:
14527 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
14531 Double the output size and put the input video in the bottom-right
14532 corner of the output padded area:
14534 pad="2*iw:2*ih:ow-iw:oh-ih"
14538 @anchor{palettegen}
14539 @section palettegen
14541 Generate one palette for a whole video stream.
14543 It accepts the following options:
14547 Set the maximum number of colors to quantize in the palette.
14548 Note: the palette will still contain 256 colors; the unused palette entries
14551 @item reserve_transparent
14552 Create a palette of 255 colors maximum and reserve the last one for
14553 transparency. Reserving the transparency color is useful for GIF optimization.
14554 If not set, the maximum of colors in the palette will be 256. You probably want
14555 to disable this option for a standalone image.
14558 @item transparency_color
14559 Set the color that will be used as background for transparency.
14562 Set statistics mode.
14564 It accepts the following values:
14567 Compute full frame histograms.
14569 Compute histograms only for the part that differs from previous frame. This
14570 might be relevant to give more importance to the moving part of your input if
14571 the background is static.
14573 Compute new histogram for each frame.
14576 Default value is @var{full}.
14579 The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
14580 (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
14581 color quantization of the palette. This information is also visible at
14582 @var{info} logging level.
14584 @subsection Examples
14588 Generate a representative palette of a given video using @command{ffmpeg}:
14590 ffmpeg -i input.mkv -vf palettegen palette.png
14594 @section paletteuse
14596 Use a palette to downsample an input video stream.
14598 The filter takes two inputs: one video stream and a palette. The palette must
14599 be a 256 pixels image.
14601 It accepts the following options:
14605 Select dithering mode. Available algorithms are:
14608 Ordered 8x8 bayer dithering (deterministic)
14610 Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
14611 Note: this dithering is sometimes considered "wrong" and is included as a
14613 @item floyd_steinberg
14614 Floyd and Steingberg dithering (error diffusion)
14616 Frankie Sierra dithering v2 (error diffusion)
14618 Frankie Sierra dithering v2 "Lite" (error diffusion)
14621 Default is @var{sierra2_4a}.
14624 When @var{bayer} dithering is selected, this option defines the scale of the
14625 pattern (how much the crosshatch pattern is visible). A low value means more
14626 visible pattern for less banding, and higher value means less visible pattern
14627 at the cost of more banding.
14629 The option must be an integer value in the range [0,5]. Default is @var{2}.
14632 If set, define the zone to process
14636 Only the changing rectangle will be reprocessed. This is similar to GIF
14637 cropping/offsetting compression mechanism. This option can be useful for speed
14638 if only a part of the image is changing, and has use cases such as limiting the
14639 scope of the error diffusal @option{dither} to the rectangle that bounds the
14640 moving scene (it leads to more deterministic output if the scene doesn't change
14641 much, and as a result less moving noise and better GIF compression).
14644 Default is @var{none}.
14647 Take new palette for each output frame.
14649 @item alpha_threshold
14650 Sets the alpha threshold for transparency. Alpha values above this threshold
14651 will be treated as completely opaque, and values below this threshold will be
14652 treated as completely transparent.
14654 The option must be an integer value in the range [0,255]. Default is @var{128}.
14657 @subsection Examples
14661 Use a palette (generated for example with @ref{palettegen}) to encode a GIF
14662 using @command{ffmpeg}:
14664 ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
14668 @section perspective
14670 Correct perspective of video not recorded perpendicular to the screen.
14672 A description of the accepted parameters follows.
14683 Set coordinates expression for top left, top right, bottom left and bottom right corners.
14684 Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
14685 If the @code{sense} option is set to @code{source}, then the specified points will be sent
14686 to the corners of the destination. If the @code{sense} option is set to @code{destination},
14687 then the corners of the source will be sent to the specified coordinates.
14689 The expressions can use the following variables:
14694 the width and height of video frame.
14698 Output frame count.
14701 @item interpolation
14702 Set interpolation for perspective correction.
14704 It accepts the following values:
14710 Default value is @samp{linear}.
14713 Set interpretation of coordinate options.
14715 It accepts the following values:
14719 Send point in the source specified by the given coordinates to
14720 the corners of the destination.
14722 @item 1, destination
14724 Send the corners of the source to the point in the destination specified
14725 by the given coordinates.
14727 Default value is @samp{source}.
14731 Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
14733 It accepts the following values:
14736 only evaluate expressions once during the filter initialization or
14737 when a command is processed
14740 evaluate expressions for each incoming frame
14743 Default value is @samp{init}.
14748 Delay interlaced video by one field time so that the field order changes.
14750 The intended use is to fix PAL movies that have been captured with the
14751 opposite field order to the film-to-video transfer.
14753 A description of the accepted parameters follows.
14759 It accepts the following values:
14762 Capture field order top-first, transfer bottom-first.
14763 Filter will delay the bottom field.
14766 Capture field order bottom-first, transfer top-first.
14767 Filter will delay the top field.
14770 Capture and transfer with the same field order. This mode only exists
14771 for the documentation of the other options to refer to, but if you
14772 actually select it, the filter will faithfully do nothing.
14775 Capture field order determined automatically by field flags, transfer
14777 Filter selects among @samp{t} and @samp{b} modes on a frame by frame
14778 basis using field flags. If no field information is available,
14779 then this works just like @samp{u}.
14782 Capture unknown or varying, transfer opposite.
14783 Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
14784 analyzing the images and selecting the alternative that produces best
14785 match between the fields.
14788 Capture top-first, transfer unknown or varying.
14789 Filter selects among @samp{t} and @samp{p} using image analysis.
14792 Capture bottom-first, transfer unknown or varying.
14793 Filter selects among @samp{b} and @samp{p} using image analysis.
14796 Capture determined by field flags, transfer unknown or varying.
14797 Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
14798 image analysis. If no field information is available, then this works just
14799 like @samp{U}. This is the default mode.
14802 Both capture and transfer unknown or varying.
14803 Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
14807 @section photosensitivity
14808 Reduce various flashes in video, so to help users with epilepsy.
14810 It accepts the following options:
14813 Set how many frames to use when filtering. Default is 30.
14816 Set detection threshold factor. Default is 1.
14820 Set how many pixels to skip when sampling frames. Default is 1.
14821 Allowed range is from 1 to 1024.
14824 Leave frames unchanged. Default is disabled.
14827 @section pixdesctest
14829 Pixel format descriptor test filter, mainly useful for internal
14830 testing. The output video should be equal to the input video.
14834 format=monow, pixdesctest
14837 can be used to test the monowhite pixel format descriptor definition.
14841 Display sample values of color channels. Mainly useful for checking color
14842 and levels. Minimum supported resolution is 640x480.
14844 The filters accept the following options:
14848 Set scope X position, relative offset on X axis.
14851 Set scope Y position, relative offset on Y axis.
14860 Set window opacity. This window also holds statistics about pixel area.
14863 Set window X position, relative offset on X axis.
14866 Set window Y position, relative offset on Y axis.
14871 Enable the specified chain of postprocessing subfilters using libpostproc. This
14872 library should be automatically selected with a GPL build (@code{--enable-gpl}).
14873 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
14874 Each subfilter and some options have a short and a long name that can be used
14875 interchangeably, i.e. dr/dering are the same.
14877 The filters accept the following options:
14881 Set postprocessing subfilters string.
14884 All subfilters share common options to determine their scope:
14888 Honor the quality commands for this subfilter.
14891 Do chrominance filtering, too (default).
14894 Do luminance filtering only (no chrominance).
14897 Do chrominance filtering only (no luminance).
14900 These options can be appended after the subfilter name, separated by a '|'.
14902 Available subfilters are:
14905 @item hb/hdeblock[|difference[|flatness]]
14906 Horizontal deblocking filter
14909 Difference factor where higher values mean more deblocking (default: @code{32}).
14911 Flatness threshold where lower values mean more deblocking (default: @code{39}).
14914 @item vb/vdeblock[|difference[|flatness]]
14915 Vertical deblocking filter
14918 Difference factor where higher values mean more deblocking (default: @code{32}).
14920 Flatness threshold where lower values mean more deblocking (default: @code{39}).
14923 @item ha/hadeblock[|difference[|flatness]]
14924 Accurate horizontal deblocking filter
14927 Difference factor where higher values mean more deblocking (default: @code{32}).
14929 Flatness threshold where lower values mean more deblocking (default: @code{39}).
14932 @item va/vadeblock[|difference[|flatness]]
14933 Accurate vertical deblocking filter
14936 Difference factor where higher values mean more deblocking (default: @code{32}).
14938 Flatness threshold where lower values mean more deblocking (default: @code{39}).
14942 The horizontal and vertical deblocking filters share the difference and
14943 flatness values so you cannot set different horizontal and vertical
14947 @item h1/x1hdeblock
14948 Experimental horizontal deblocking filter
14950 @item v1/x1vdeblock
14951 Experimental vertical deblocking filter
14956 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
14959 larger -> stronger filtering
14961 larger -> stronger filtering
14963 larger -> stronger filtering
14966 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
14969 Stretch luminance to @code{0-255}.
14972 @item lb/linblenddeint
14973 Linear blend deinterlacing filter that deinterlaces the given block by
14974 filtering all lines with a @code{(1 2 1)} filter.
14976 @item li/linipoldeint
14977 Linear interpolating deinterlacing filter that deinterlaces the given block by
14978 linearly interpolating every second line.
14980 @item ci/cubicipoldeint
14981 Cubic interpolating deinterlacing filter deinterlaces the given block by
14982 cubically interpolating every second line.
14984 @item md/mediandeint
14985 Median deinterlacing filter that deinterlaces the given block by applying a
14986 median filter to every second line.
14988 @item fd/ffmpegdeint
14989 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
14990 second line with a @code{(-1 4 2 4 -1)} filter.
14993 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
14994 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
14996 @item fq/forceQuant[|quantizer]
14997 Overrides the quantizer table from the input with the constant quantizer you
15005 Default pp filter combination (@code{hb|a,vb|a,dr|a})
15008 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
15011 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
15014 @subsection Examples
15018 Apply horizontal and vertical deblocking, deringing and automatic
15019 brightness/contrast:
15025 Apply default filters without brightness/contrast correction:
15031 Apply default filters and temporal denoiser:
15033 pp=default/tmpnoise|1|2|3
15037 Apply deblocking on luminance only, and switch vertical deblocking on or off
15038 automatically depending on available CPU time:
15045 Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
15046 similar to spp = 6 with 7 point DCT, where only the center sample is
15049 The filter accepts the following options:
15053 Force a constant quantization parameter. It accepts an integer in range
15054 0 to 63. If not set, the filter will use the QP from the video stream
15058 Set thresholding mode. Available modes are:
15062 Set hard thresholding.
15064 Set soft thresholding (better de-ringing effect, but likely blurrier).
15066 Set medium thresholding (good results, default).
15070 @section premultiply
15071 Apply alpha premultiply effect to input video stream using first plane
15072 of second stream as alpha.
15074 Both streams must have same dimensions and same pixel format.
15076 The filter accepts the following option:
15080 Set which planes will be processed, unprocessed planes will be copied.
15081 By default value 0xf, all planes will be processed.
15084 Do not require 2nd input for processing, instead use alpha plane from input stream.
15088 Apply prewitt operator to input video stream.
15090 The filter accepts the following option:
15094 Set which planes will be processed, unprocessed planes will be copied.
15095 By default value 0xf, all planes will be processed.
15098 Set value which will be multiplied with filtered result.
15101 Set value which will be added to filtered result.
15104 @section pseudocolor
15106 Alter frame colors in video with pseudocolors.
15108 This filter accepts the following options:
15112 set pixel first component expression
15115 set pixel second component expression
15118 set pixel third component expression
15121 set pixel fourth component expression, corresponds to the alpha component
15124 set component to use as base for altering colors
15127 Each of them specifies the expression to use for computing the lookup table for
15128 the corresponding pixel component values.
15130 The expressions can contain the following constants and functions:
15135 The input width and height.
15138 The input value for the pixel component.
15140 @item ymin, umin, vmin, amin
15141 The minimum allowed component value.
15143 @item ymax, umax, vmax, amax
15144 The maximum allowed component value.
15147 All expressions default to "val".
15149 @subsection Examples
15153 Change too high luma values to gradient:
15155 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'"
15161 Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
15162 Ratio) between two input videos.
15164 This filter takes in input two input videos, the first input is
15165 considered the "main" source and is passed unchanged to the
15166 output. The second input is used as a "reference" video for computing
15169 Both video inputs must have the same resolution and pixel format for
15170 this filter to work correctly. Also it assumes that both inputs
15171 have the same number of frames, which are compared one by one.
15173 The obtained average PSNR is printed through the logging system.
15175 The filter stores the accumulated MSE (mean squared error) of each
15176 frame, and at the end of the processing it is averaged across all frames
15177 equally, and the following formula is applied to obtain the PSNR:
15180 PSNR = 10*log10(MAX^2/MSE)
15183 Where MAX is the average of the maximum values of each component of the
15186 The description of the accepted parameters follows.
15189 @item stats_file, f
15190 If specified the filter will use the named file to save the PSNR of
15191 each individual frame. When filename equals "-" the data is sent to
15194 @item stats_version
15195 Specifies which version of the stats file format to use. Details of
15196 each format are written below.
15197 Default value is 1.
15199 @item stats_add_max
15200 Determines whether the max value is output to the stats log.
15201 Default value is 0.
15202 Requires stats_version >= 2. If this is set and stats_version < 2,
15203 the filter will return an error.
15206 This filter also supports the @ref{framesync} options.
15208 The file printed if @var{stats_file} is selected, contains a sequence of
15209 key/value pairs of the form @var{key}:@var{value} for each compared
15212 If a @var{stats_version} greater than 1 is specified, a header line precedes
15213 the list of per-frame-pair stats, with key value pairs following the frame
15214 format with the following parameters:
15217 @item psnr_log_version
15218 The version of the log file format. Will match @var{stats_version}.
15221 A comma separated list of the per-frame-pair parameters included in
15225 A description of each shown per-frame-pair parameter follows:
15229 sequential number of the input frame, starting from 1
15232 Mean Square Error pixel-by-pixel average difference of the compared
15233 frames, averaged over all the image components.
15235 @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
15236 Mean Square Error pixel-by-pixel average difference of the compared
15237 frames for the component specified by the suffix.
15239 @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
15240 Peak Signal to Noise ratio of the compared frames for the component
15241 specified by the suffix.
15243 @item max_avg, max_y, max_u, max_v
15244 Maximum allowed value for each channel, and average over all
15248 @subsection Examples
15253 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
15254 [main][ref] psnr="stats_file=stats.log" [out]
15257 On this example the input file being processed is compared with the
15258 reference file @file{ref_movie.mpg}. The PSNR of each individual frame
15259 is stored in @file{stats.log}.
15262 Another example with different containers:
15264 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 -
15271 Pulldown reversal (inverse telecine) filter, capable of handling mixed
15272 hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
15275 The pullup filter is designed to take advantage of future context in making
15276 its decisions. This filter is stateless in the sense that it does not lock
15277 onto a pattern to follow, but it instead looks forward to the following
15278 fields in order to identify matches and rebuild progressive frames.
15280 To produce content with an even framerate, insert the fps filter after
15281 pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
15282 @code{fps=24} for 30fps and the (rare) telecined 25fps input.
15284 The filter accepts the following options:
15291 These options set the amount of "junk" to ignore at the left, right, top, and
15292 bottom of the image, respectively. Left and right are in units of 8 pixels,
15293 while top and bottom are in units of 2 lines.
15294 The default is 8 pixels on each side.
15297 Set the strict breaks. Setting this option to 1 will reduce the chances of
15298 filter generating an occasional mismatched frame, but it may also cause an
15299 excessive number of frames to be dropped during high motion sequences.
15300 Conversely, setting it to -1 will make filter match fields more easily.
15301 This may help processing of video where there is slight blurring between
15302 the fields, but may also cause there to be interlaced frames in the output.
15303 Default value is @code{0}.
15306 Set the metric plane to use. It accepts the following values:
15312 Use chroma blue plane.
15315 Use chroma red plane.
15318 This option may be set to use chroma plane instead of the default luma plane
15319 for doing filter's computations. This may improve accuracy on very clean
15320 source material, but more likely will decrease accuracy, especially if there
15321 is chroma noise (rainbow effect) or any grayscale video.
15322 The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
15323 load and make pullup usable in realtime on slow machines.
15326 For best results (without duplicated frames in the output file) it is
15327 necessary to change the output frame rate. For example, to inverse
15328 telecine NTSC input:
15330 ffmpeg -i input -vf pullup -r 24000/1001 ...
15335 Change video quantization parameters (QP).
15337 The filter accepts the following option:
15341 Set expression for quantization parameter.
15344 The expression is evaluated through the eval API and can contain, among others,
15345 the following constants:
15349 1 if index is not 129, 0 otherwise.
15352 Sequential index starting from -129 to 128.
15355 @subsection Examples
15359 Some equation like:
15367 Flush video frames from internal cache of frames into a random order.
15368 No frame is discarded.
15369 Inspired by @ref{frei0r} nervous filter.
15373 Set size in number of frames of internal cache, in range from @code{2} to
15374 @code{512}. Default is @code{30}.
15377 Set seed for random number generator, must be an integer included between
15378 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
15379 less than @code{0}, the filter will try to use a good random seed on a
15383 @section readeia608
15385 Read closed captioning (EIA-608) information from the top lines of a video frame.
15387 This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and
15388 @code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line
15389 with EIA-608 data (starting from 0). A description of each metadata value follows:
15392 @item lavfi.readeia608.X.cc
15393 The two bytes stored as EIA-608 data (printed in hexadecimal).
15395 @item lavfi.readeia608.X.line
15396 The number of the line on which the EIA-608 data was identified and read.
15399 This filter accepts the following options:
15403 Set the line to start scanning for EIA-608 data. Default is @code{0}.
15406 Set the line to end scanning for EIA-608 data. Default is @code{29}.
15409 Set the ratio of width reserved for sync code detection.
15410 Default is @code{0.27}. Allowed range is @code{[0.1 - 0.7]}.
15413 Enable checking the parity bit. In the event of a parity error, the filter will output
15414 @code{0x00} for that character. Default is false.
15417 Lowpass lines prior to further processing. Default is enabled.
15420 @subsection Examples
15424 Output a csv with presentation time and the first two lines of identified EIA-608 captioning data.
15426 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
15432 Read vertical interval timecode (VITC) information from the top lines of a
15435 The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
15436 timecode value, if a valid timecode has been detected. Further metadata key
15437 @code{lavfi.readvitc.found} is set to 0/1 depending on whether
15438 timecode data has been found or not.
15440 This filter accepts the following options:
15444 Set the maximum number of lines to scan for VITC data. If the value is set to
15445 @code{-1} the full video frame is scanned. Default is @code{45}.
15448 Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
15449 default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
15452 Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
15453 default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
15456 @subsection Examples
15460 Detect and draw VITC data onto the video frame; if no valid VITC is detected,
15461 draw @code{--:--:--:--} as a placeholder:
15463 ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
15469 Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
15471 Destination pixel at position (X, Y) will be picked from source (x, y) position
15472 where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
15473 value for pixel will be used for destination pixel.
15475 Xmap and Ymap input video streams must be of same dimensions. Output video stream
15476 will have Xmap/Ymap video stream dimensions.
15477 Xmap and Ymap input video streams are 16bit depth, single channel.
15481 Specify pixel format of output from this filter. Can be @code{color} or @code{gray}.
15482 Default is @code{color}.
15485 @section removegrain
15487 The removegrain filter is a spatial denoiser for progressive video.
15491 Set mode for the first plane.
15494 Set mode for the second plane.
15497 Set mode for the third plane.
15500 Set mode for the fourth plane.
15503 Range of mode is from 0 to 24. Description of each mode follows:
15507 Leave input plane unchanged. Default.
15510 Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
15513 Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
15516 Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
15519 Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
15520 This is equivalent to a median filter.
15523 Line-sensitive clipping giving the minimal change.
15526 Line-sensitive clipping, intermediate.
15529 Line-sensitive clipping, intermediate.
15532 Line-sensitive clipping, intermediate.
15535 Line-sensitive clipping on a line where the neighbours pixels are the closest.
15538 Replaces the target pixel with the closest neighbour.
15541 [1 2 1] horizontal and vertical kernel blur.
15547 Bob mode, interpolates top field from the line where the neighbours
15548 pixels are the closest.
15551 Bob mode, interpolates bottom field from the line where the neighbours
15552 pixels are the closest.
15555 Bob mode, interpolates top field. Same as 13 but with a more complicated
15556 interpolation formula.
15559 Bob mode, interpolates bottom field. Same as 14 but with a more complicated
15560 interpolation formula.
15563 Clips the pixel with the minimum and maximum of respectively the maximum and
15564 minimum of each pair of opposite neighbour pixels.
15567 Line-sensitive clipping using opposite neighbours whose greatest distance from
15568 the current pixel is minimal.
15571 Replaces the pixel with the average of its 8 neighbours.
15574 Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
15577 Clips pixels using the averages of opposite neighbour.
15580 Same as mode 21 but simpler and faster.
15583 Small edge and halo removal, but reputed useless.
15589 @section removelogo
15591 Suppress a TV station logo, using an image file to determine which
15592 pixels comprise the logo. It works by filling in the pixels that
15593 comprise the logo with neighboring pixels.
15595 The filter accepts the following options:
15599 Set the filter bitmap file, which can be any image format supported by
15600 libavformat. The width and height of the image file must match those of the
15601 video stream being processed.
15604 Pixels in the provided bitmap image with a value of zero are not
15605 considered part of the logo, non-zero pixels are considered part of
15606 the logo. If you use white (255) for the logo and black (0) for the
15607 rest, you will be safe. For making the filter bitmap, it is
15608 recommended to take a screen capture of a black frame with the logo
15609 visible, and then using a threshold filter followed by the erode
15610 filter once or twice.
15612 If needed, little splotches can be fixed manually. Remember that if
15613 logo pixels are not covered, the filter quality will be much
15614 reduced. Marking too many pixels as part of the logo does not hurt as
15615 much, but it will increase the amount of blurring needed to cover over
15616 the image and will destroy more information than necessary, and extra
15617 pixels will slow things down on a large logo.
15619 @section repeatfields
15621 This filter uses the repeat_field flag from the Video ES headers and hard repeats
15622 fields based on its value.
15626 Reverse a video clip.
15628 Warning: This filter requires memory to buffer the entire clip, so trimming
15631 @subsection Examples
15635 Take the first 5 seconds of a clip, and reverse it.
15642 Shift R/G/B/A pixels horizontally and/or vertically.
15644 The filter accepts the following options:
15647 Set amount to shift red horizontally.
15649 Set amount to shift red vertically.
15651 Set amount to shift green horizontally.
15653 Set amount to shift green vertically.
15655 Set amount to shift blue horizontally.
15657 Set amount to shift blue vertically.
15659 Set amount to shift alpha horizontally.
15661 Set amount to shift alpha vertically.
15663 Set edge mode, can be @var{smear}, default, or @var{warp}.
15666 @subsection Commands
15668 This filter supports the all above options as @ref{commands}.
15671 Apply roberts cross operator to input video stream.
15673 The filter accepts the following option:
15677 Set which planes will be processed, unprocessed planes will be copied.
15678 By default value 0xf, all planes will be processed.
15681 Set value which will be multiplied with filtered result.
15684 Set value which will be added to filtered result.
15689 Rotate video by an arbitrary angle expressed in radians.
15691 The filter accepts the following options:
15693 A description of the optional parameters follows.
15696 Set an expression for the angle by which to rotate the input video
15697 clockwise, expressed as a number of radians. A negative value will
15698 result in a counter-clockwise rotation. By default it is set to "0".
15700 This expression is evaluated for each frame.
15703 Set the output width expression, default value is "iw".
15704 This expression is evaluated just once during configuration.
15707 Set the output height expression, default value is "ih".
15708 This expression is evaluated just once during configuration.
15711 Enable bilinear interpolation if set to 1, a value of 0 disables
15712 it. Default value is 1.
15715 Set the color used to fill the output area not covered by the rotated
15716 image. For the general syntax of this option, check the
15717 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
15718 If the special value "none" is selected then no
15719 background is printed (useful for example if the background is never shown).
15721 Default value is "black".
15724 The expressions for the angle and the output size can contain the
15725 following constants and functions:
15729 sequential number of the input frame, starting from 0. It is always NAN
15730 before the first frame is filtered.
15733 time in seconds of the input frame, it is set to 0 when the filter is
15734 configured. It is always NAN before the first frame is filtered.
15738 horizontal and vertical chroma subsample values. For example for the
15739 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
15743 the input video width and height
15747 the output width and height, that is the size of the padded area as
15748 specified by the @var{width} and @var{height} expressions
15752 the minimal width/height required for completely containing the input
15753 video rotated by @var{a} radians.
15755 These are only available when computing the @option{out_w} and
15756 @option{out_h} expressions.
15759 @subsection Examples
15763 Rotate the input by PI/6 radians clockwise:
15769 Rotate the input by PI/6 radians counter-clockwise:
15775 Rotate the input by 45 degrees clockwise:
15781 Apply a constant rotation with period T, starting from an angle of PI/3:
15783 rotate=PI/3+2*PI*t/T
15787 Make the input video rotation oscillating with a period of T
15788 seconds and an amplitude of A radians:
15790 rotate=A*sin(2*PI/T*t)
15794 Rotate the video, output size is chosen so that the whole rotating
15795 input video is always completely contained in the output:
15797 rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
15801 Rotate the video, reduce the output size so that no background is ever
15804 rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
15808 @subsection Commands
15810 The filter supports the following commands:
15814 Set the angle expression.
15815 The command accepts the same syntax of the corresponding option.
15817 If the specified expression is not valid, it is kept at its current
15823 Apply Shape Adaptive Blur.
15825 The filter accepts the following options:
15828 @item luma_radius, lr
15829 Set luma blur filter strength, must be a value in range 0.1-4.0, default
15830 value is 1.0. A greater value will result in a more blurred image, and
15831 in slower processing.
15833 @item luma_pre_filter_radius, lpfr
15834 Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
15837 @item luma_strength, ls
15838 Set luma maximum difference between pixels to still be considered, must
15839 be a value in the 0.1-100.0 range, default value is 1.0.
15841 @item chroma_radius, cr
15842 Set chroma blur filter strength, must be a value in range -0.9-4.0. A
15843 greater value will result in a more blurred image, and in slower
15846 @item chroma_pre_filter_radius, cpfr
15847 Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
15849 @item chroma_strength, cs
15850 Set chroma maximum difference between pixels to still be considered,
15851 must be a value in the -0.9-100.0 range.
15854 Each chroma option value, if not explicitly specified, is set to the
15855 corresponding luma option value.
15860 Scale (resize) the input video, using the libswscale library.
15862 The scale filter forces the output display aspect ratio to be the same
15863 of the input, by changing the output sample aspect ratio.
15865 If the input image format is different from the format requested by
15866 the next filter, the scale filter will convert the input to the
15869 @subsection Options
15870 The filter accepts the following options, or any of the options
15871 supported by the libswscale scaler.
15873 See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
15874 the complete list of scaler options.
15879 Set the output video dimension expression. Default value is the input
15882 If the @var{width} or @var{w} value is 0, the input width is used for
15883 the output. If the @var{height} or @var{h} value is 0, the input height
15884 is used for the output.
15886 If one and only one of the values is -n with n >= 1, the scale filter
15887 will use a value that maintains the aspect ratio of the input image,
15888 calculated from the other specified dimension. After that it will,
15889 however, make sure that the calculated dimension is divisible by n and
15890 adjust the value if necessary.
15892 If both values are -n with n >= 1, the behavior will be identical to
15893 both values being set to 0 as previously detailed.
15895 See below for the list of accepted constants for use in the dimension
15899 Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
15903 Only evaluate expressions once during the filter initialization or when a command is processed.
15906 Evaluate expressions for each incoming frame.
15910 Default value is @samp{init}.
15914 Set the interlacing mode. It accepts the following values:
15918 Force interlaced aware scaling.
15921 Do not apply interlaced scaling.
15924 Select interlaced aware scaling depending on whether the source frames
15925 are flagged as interlaced or not.
15928 Default value is @samp{0}.
15931 Set libswscale scaling flags. See
15932 @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
15933 complete list of values. If not explicitly specified the filter applies
15937 @item param0, param1
15938 Set libswscale input parameters for scaling algorithms that need them. See
15939 @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
15940 complete documentation. If not explicitly specified the filter applies
15946 Set the video size. For the syntax of this option, check the
15947 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15949 @item in_color_matrix
15950 @item out_color_matrix
15951 Set in/output YCbCr color space type.
15953 This allows the autodetected value to be overridden as well as allows forcing
15954 a specific value used for the output and encoder.
15956 If not specified, the color space type depends on the pixel format.
15962 Choose automatically.
15965 Format conforming to International Telecommunication Union (ITU)
15966 Recommendation BT.709.
15969 Set color space conforming to the United States Federal Communications
15970 Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
15975 Set color space conforming to:
15979 ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
15982 ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
15985 Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
15990 Set color space conforming to SMPTE ST 240:1999.
15993 Set color space conforming to ITU-R BT.2020 non-constant luminance system.
15998 Set in/output YCbCr sample range.
16000 This allows the autodetected value to be overridden as well as allows forcing
16001 a specific value used for the output and encoder. If not specified, the
16002 range depends on the pixel format. Possible values:
16006 Choose automatically.
16009 Set full range (0-255 in case of 8-bit luma).
16011 @item mpeg/limited/tv
16012 Set "MPEG" range (16-235 in case of 8-bit luma).
16015 @item force_original_aspect_ratio
16016 Enable decreasing or increasing output video width or height if necessary to
16017 keep the original aspect ratio. Possible values:
16021 Scale the video as specified and disable this feature.
16024 The output video dimensions will automatically be decreased if needed.
16027 The output video dimensions will automatically be increased if needed.
16031 One useful instance of this option is that when you know a specific device's
16032 maximum allowed resolution, you can use this to limit the output video to
16033 that, while retaining the aspect ratio. For example, device A allows
16034 1280x720 playback, and your video is 1920x800. Using this option (set it to
16035 decrease) and specifying 1280x720 to the command line makes the output
16038 Please note that this is a different thing than specifying -1 for @option{w}
16039 or @option{h}, you still need to specify the output resolution for this option
16042 @item force_divisible_by
16043 Ensures that both the output dimensions, width and height, are divisible by the
16044 given integer when used together with @option{force_original_aspect_ratio}. This
16045 works similar to using @code{-n} in the @option{w} and @option{h} options.
16047 This option respects the value set for @option{force_original_aspect_ratio},
16048 increasing or decreasing the resolution accordingly. The video's aspect ratio
16049 may be slightly modified.
16051 This option can be handy if you need to have a video fit within or exceed
16052 a defined resolution using @option{force_original_aspect_ratio} but also have
16053 encoder restrictions on width or height divisibility.
16057 The values of the @option{w} and @option{h} options are expressions
16058 containing the following constants:
16063 The input width and height
16067 These are the same as @var{in_w} and @var{in_h}.
16071 The output (scaled) width and height
16075 These are the same as @var{out_w} and @var{out_h}
16078 The same as @var{iw} / @var{ih}
16081 input sample aspect ratio
16084 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
16088 horizontal and vertical input chroma subsample values. For example for the
16089 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16093 horizontal and vertical output chroma subsample values. For example for the
16094 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16097 The (sequential) number of the input frame, starting from 0.
16098 Only available with @code{eval=frame}.
16101 The presentation timestamp of the input frame, expressed as a number of
16102 seconds. Only available with @code{eval=frame}.
16105 The position (byte offset) of the frame in the input stream, or NaN if
16106 this information is unavailable and/or meaningless (for example in case of synthetic video).
16107 Only available with @code{eval=frame}.
16110 @subsection Examples
16114 Scale the input video to a size of 200x100
16119 This is equivalent to:
16130 Specify a size abbreviation for the output size:
16135 which can also be written as:
16141 Scale the input to 2x:
16143 scale=w=2*iw:h=2*ih
16147 The above is the same as:
16149 scale=2*in_w:2*in_h
16153 Scale the input to 2x with forced interlaced scaling:
16155 scale=2*iw:2*ih:interl=1
16159 Scale the input to half size:
16161 scale=w=iw/2:h=ih/2
16165 Increase the width, and set the height to the same size:
16171 Seek Greek harmony:
16178 Increase the height, and set the width to 3/2 of the height:
16180 scale=w=3/2*oh:h=3/5*ih
16184 Increase the size, making the size a multiple of the chroma
16187 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
16191 Increase the width to a maximum of 500 pixels,
16192 keeping the same aspect ratio as the input:
16194 scale=w='min(500\, iw*3/2):h=-1'
16198 Make pixels square by combining scale and setsar:
16200 scale='trunc(ih*dar):ih',setsar=1/1
16204 Make pixels square by combining scale and setsar,
16205 making sure the resulting resolution is even (required by some codecs):
16207 scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1
16211 @subsection Commands
16213 This filter supports the following commands:
16217 Set the output video dimension expression.
16218 The command accepts the same syntax of the corresponding option.
16220 If the specified expression is not valid, it is kept at its current
16226 Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
16227 format conversion on CUDA video frames. Setting the output width and height
16228 works in the same way as for the @var{scale} filter.
16230 The following additional options are accepted:
16233 The pixel format of the output CUDA frames. If set to the string "same" (the
16234 default), the input format will be kept. Note that automatic format negotiation
16235 and conversion is not yet supported for hardware frames
16238 The interpolation algorithm used for resizing. One of the following:
16245 @item cubic2p_bspline
16246 2-parameter cubic (B=1, C=0)
16248 @item cubic2p_catmullrom
16249 2-parameter cubic (B=0, C=1/2)
16251 @item cubic2p_b05c03
16252 2-parameter cubic (B=1/2, C=3/10)
16260 @item force_original_aspect_ratio
16261 Enable decreasing or increasing output video width or height if necessary to
16262 keep the original aspect ratio. Possible values:
16266 Scale the video as specified and disable this feature.
16269 The output video dimensions will automatically be decreased if needed.
16272 The output video dimensions will automatically be increased if needed.
16276 One useful instance of this option is that when you know a specific device's
16277 maximum allowed resolution, you can use this to limit the output video to
16278 that, while retaining the aspect ratio. For example, device A allows
16279 1280x720 playback, and your video is 1920x800. Using this option (set it to
16280 decrease) and specifying 1280x720 to the command line makes the output
16283 Please note that this is a different thing than specifying -1 for @option{w}
16284 or @option{h}, you still need to specify the output resolution for this option
16287 @item force_divisible_by
16288 Ensures that both the output dimensions, width and height, are divisible by the
16289 given integer when used together with @option{force_original_aspect_ratio}. This
16290 works similar to using @code{-n} in the @option{w} and @option{h} options.
16292 This option respects the value set for @option{force_original_aspect_ratio},
16293 increasing or decreasing the resolution accordingly. The video's aspect ratio
16294 may be slightly modified.
16296 This option can be handy if you need to have a video fit within or exceed
16297 a defined resolution using @option{force_original_aspect_ratio} but also have
16298 encoder restrictions on width or height divisibility.
16304 Scale (resize) the input video, based on a reference video.
16306 See the scale filter for available options, scale2ref supports the same but
16307 uses the reference video instead of the main input as basis. scale2ref also
16308 supports the following additional constants for the @option{w} and
16309 @option{h} options:
16314 The main input video's width and height
16317 The same as @var{main_w} / @var{main_h}
16320 The main input video's sample aspect ratio
16322 @item main_dar, mdar
16323 The main input video's display aspect ratio. Calculated from
16324 @code{(main_w / main_h) * main_sar}.
16328 The main input video's horizontal and vertical chroma subsample values.
16329 For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub}
16333 The (sequential) number of the main input frame, starting from 0.
16334 Only available with @code{eval=frame}.
16337 The presentation timestamp of the main input frame, expressed as a number of
16338 seconds. Only available with @code{eval=frame}.
16341 The position (byte offset) of the frame in the main input stream, or NaN if
16342 this information is unavailable and/or meaningless (for example in case of synthetic video).
16343 Only available with @code{eval=frame}.
16346 @subsection Examples
16350 Scale a subtitle stream (b) to match the main video (a) in size before overlaying
16352 'scale2ref[b][a];[a][b]overlay'
16356 Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio.
16358 [logo-in][video-in]scale2ref=w=oh*mdar:h=ih/10[logo-out][video-out]
16362 @subsection Commands
16364 This filter supports the following commands:
16368 Set the output video dimension expression.
16369 The command accepts the same syntax of the corresponding option.
16371 If the specified expression is not valid, it is kept at its current
16376 Scroll input video horizontally and/or vertically by constant speed.
16378 The filter accepts the following options:
16380 @item horizontal, h
16381 Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1.
16382 Negative values changes scrolling direction.
16385 Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1.
16386 Negative values changes scrolling direction.
16389 Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1.
16392 Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1.
16395 @subsection Commands
16397 This filter supports the following @ref{commands}:
16399 @item horizontal, h
16400 Set the horizontal scrolling speed.
16402 Set the vertical scrolling speed.
16405 @anchor{selectivecolor}
16406 @section selectivecolor
16408 Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
16409 as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
16410 by the "purity" of the color (that is, how saturated it already is).
16412 This filter is similar to the Adobe Photoshop Selective Color tool.
16414 The filter accepts the following options:
16417 @item correction_method
16418 Select color correction method.
16420 Available values are:
16423 Specified adjustments are applied "as-is" (added/subtracted to original pixel
16426 Specified adjustments are relative to the original component value.
16428 Default is @code{absolute}.
16430 Adjustments for red pixels (pixels where the red component is the maximum)
16432 Adjustments for yellow pixels (pixels where the blue component is the minimum)
16434 Adjustments for green pixels (pixels where the green component is the maximum)
16436 Adjustments for cyan pixels (pixels where the red component is the minimum)
16438 Adjustments for blue pixels (pixels where the blue component is the maximum)
16440 Adjustments for magenta pixels (pixels where the green component is the minimum)
16442 Adjustments for white pixels (pixels where all components are greater than 128)
16444 Adjustments for all pixels except pure black and pure white
16446 Adjustments for black pixels (pixels where all components are lesser than 128)
16448 Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
16451 All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
16452 4 space separated floating point adjustment values in the [-1,1] range,
16453 respectively to adjust the amount of cyan, magenta, yellow and black for the
16454 pixels of its range.
16456 @subsection Examples
16460 Increase cyan by 50% and reduce yellow by 33% in every green areas, and
16461 increase magenta by 27% in blue areas:
16463 selectivecolor=greens=.5 0 -.33 0:blues=0 .27
16467 Use a Photoshop selective color preset:
16469 selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
16473 @anchor{separatefields}
16474 @section separatefields
16476 The @code{separatefields} takes a frame-based video input and splits
16477 each frame into its components fields, producing a new half height clip
16478 with twice the frame rate and twice the frame count.
16480 This filter use field-dominance information in frame to decide which
16481 of each pair of fields to place first in the output.
16482 If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
16484 @section setdar, setsar
16486 The @code{setdar} filter sets the Display Aspect Ratio for the filter
16489 This is done by changing the specified Sample (aka Pixel) Aspect
16490 Ratio, according to the following equation:
16492 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
16495 Keep in mind that the @code{setdar} filter does not modify the pixel
16496 dimensions of the video frame. Also, the display aspect ratio set by
16497 this filter may be changed by later filters in the filterchain,
16498 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
16501 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
16502 the filter output video.
16504 Note that as a consequence of the application of this filter, the
16505 output display aspect ratio will change according to the equation
16508 Keep in mind that the sample aspect ratio set by the @code{setsar}
16509 filter may be changed by later filters in the filterchain, e.g. if
16510 another "setsar" or a "setdar" filter is applied.
16512 It accepts the following parameters:
16515 @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
16516 Set the aspect ratio used by the filter.
16518 The parameter can be a floating point number string, an expression, or
16519 a string of the form @var{num}:@var{den}, where @var{num} and
16520 @var{den} are the numerator and denominator of the aspect ratio. If
16521 the parameter is not specified, it is assumed the value "0".
16522 In case the form "@var{num}:@var{den}" is used, the @code{:} character
16526 Set the maximum integer value to use for expressing numerator and
16527 denominator when reducing the expressed aspect ratio to a rational.
16528 Default value is @code{100}.
16532 The parameter @var{sar} is an expression containing
16533 the following constants:
16537 These are approximated values for the mathematical constants e
16538 (Euler's number), pi (Greek pi), and phi (the golden ratio).
16541 The input width and height.
16544 These are the same as @var{w} / @var{h}.
16547 The input sample aspect ratio.
16550 The input display aspect ratio. It is the same as
16551 (@var{w} / @var{h}) * @var{sar}.
16554 Horizontal and vertical chroma subsample values. For example, for the
16555 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16558 @subsection Examples
16563 To change the display aspect ratio to 16:9, specify one of the following:
16570 To change the sample aspect ratio to 10:11, specify:
16576 To set a display aspect ratio of 16:9, and specify a maximum integer value of
16577 1000 in the aspect ratio reduction, use the command:
16579 setdar=ratio=16/9:max=1000
16587 Force field for the output video frame.
16589 The @code{setfield} filter marks the interlace type field for the
16590 output frames. It does not change the input frame, but only sets the
16591 corresponding property, which affects how the frame is treated by
16592 following filters (e.g. @code{fieldorder} or @code{yadif}).
16594 The filter accepts the following options:
16599 Available values are:
16603 Keep the same field property.
16606 Mark the frame as bottom-field-first.
16609 Mark the frame as top-field-first.
16612 Mark the frame as progressive.
16619 Force frame parameter for the output video frame.
16621 The @code{setparams} filter marks interlace and color range for the
16622 output frames. It does not change the input frame, but only sets the
16623 corresponding property, which affects how the frame is treated by
16628 Available values are:
16632 Keep the same field property (default).
16635 Mark the frame as bottom-field-first.
16638 Mark the frame as top-field-first.
16641 Mark the frame as progressive.
16645 Available values are:
16649 Keep the same color range property (default).
16651 @item unspecified, unknown
16652 Mark the frame as unspecified color range.
16654 @item limited, tv, mpeg
16655 Mark the frame as limited range.
16657 @item full, pc, jpeg
16658 Mark the frame as full range.
16661 @item color_primaries
16662 Set the color primaries.
16663 Available values are:
16667 Keep the same color primaries property (default).
16684 Set the color transfer.
16685 Available values are:
16689 Keep the same color trc property (default).
16711 Set the colorspace.
16712 Available values are:
16716 Keep the same colorspace property (default).
16729 @item chroma-derived-nc
16730 @item chroma-derived-c
16737 Show a line containing various information for each input video frame.
16738 The input video is not modified.
16740 This filter supports the following options:
16744 Calculate checksums of each plane. By default enabled.
16747 The shown line contains a sequence of key/value pairs of the form
16748 @var{key}:@var{value}.
16750 The following values are shown in the output:
16754 The (sequential) number of the input frame, starting from 0.
16757 The Presentation TimeStamp of the input frame, expressed as a number of
16758 time base units. The time base unit depends on the filter input pad.
16761 The Presentation TimeStamp of the input frame, expressed as a number of
16765 The position of the frame in the input stream, or -1 if this information is
16766 unavailable and/or meaningless (for example in case of synthetic video).
16769 The pixel format name.
16772 The sample aspect ratio of the input frame, expressed in the form
16773 @var{num}/@var{den}.
16776 The size of the input frame. For the syntax of this option, check the
16777 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16780 The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
16781 for bottom field first).
16784 This is 1 if the frame is a key frame, 0 otherwise.
16787 The picture type of the input frame ("I" for an I-frame, "P" for a
16788 P-frame, "B" for a B-frame, or "?" for an unknown type).
16789 Also refer to the documentation of the @code{AVPictureType} enum and of
16790 the @code{av_get_picture_type_char} function defined in
16791 @file{libavutil/avutil.h}.
16794 The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
16796 @item plane_checksum
16797 The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
16798 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
16801 The mean value of pixels in each plane of the input frame, expressed in the form
16802 "[@var{mean0} @var{mean1} @var{mean2} @var{mean3}]".
16805 The standard deviation of pixel values in each plane of the input frame, expressed
16806 in the form "[@var{stdev0} @var{stdev1} @var{stdev2} @var{stdev3}]".
16810 @section showpalette
16812 Displays the 256 colors palette of each frame. This filter is only relevant for
16813 @var{pal8} pixel format frames.
16815 It accepts the following option:
16819 Set the size of the box used to represent one palette color entry. Default is
16820 @code{30} (for a @code{30x30} pixel box).
16823 @section shuffleframes
16825 Reorder and/or duplicate and/or drop video frames.
16827 It accepts the following parameters:
16831 Set the destination indexes of input frames.
16832 This is space or '|' separated list of indexes that maps input frames to output
16833 frames. Number of indexes also sets maximal value that each index may have.
16834 '-1' index have special meaning and that is to drop frame.
16837 The first frame has the index 0. The default is to keep the input unchanged.
16839 @subsection Examples
16843 Swap second and third frame of every three frames of the input:
16845 ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
16849 Swap 10th and 1st frame of every ten frames of the input:
16851 ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
16855 @section shuffleplanes
16857 Reorder and/or duplicate video planes.
16859 It accepts the following parameters:
16864 The index of the input plane to be used as the first output plane.
16867 The index of the input plane to be used as the second output plane.
16870 The index of the input plane to be used as the third output plane.
16873 The index of the input plane to be used as the fourth output plane.
16877 The first plane has the index 0. The default is to keep the input unchanged.
16879 @subsection Examples
16883 Swap the second and third planes of the input:
16885 ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
16889 @anchor{signalstats}
16890 @section signalstats
16891 Evaluate various visual metrics that assist in determining issues associated
16892 with the digitization of analog video media.
16894 By default the filter will log these metadata values:
16898 Display the minimal Y value contained within the input frame. Expressed in
16902 Display the Y value at the 10% percentile within the input frame. Expressed in
16906 Display the average Y value within the input frame. Expressed in range of
16910 Display the Y value at the 90% percentile within the input frame. Expressed in
16914 Display the maximum Y value contained within the input frame. Expressed in
16918 Display the minimal U value contained within the input frame. Expressed in
16922 Display the U value at the 10% percentile within the input frame. Expressed in
16926 Display the average U value within the input frame. Expressed in range of
16930 Display the U value at the 90% percentile within the input frame. Expressed in
16934 Display the maximum U value contained within the input frame. Expressed in
16938 Display the minimal V value contained within the input frame. Expressed in
16942 Display the V value at the 10% percentile within the input frame. Expressed in
16946 Display the average V value within the input frame. Expressed in range of
16950 Display the V value at the 90% percentile within the input frame. Expressed in
16954 Display the maximum V value contained within the input frame. Expressed in
16958 Display the minimal saturation value contained within the input frame.
16959 Expressed in range of [0-~181.02].
16962 Display the saturation value at the 10% percentile within the input frame.
16963 Expressed in range of [0-~181.02].
16966 Display the average saturation value within the input frame. Expressed in range
16970 Display the saturation value at the 90% percentile within the input frame.
16971 Expressed in range of [0-~181.02].
16974 Display the maximum saturation value contained within the input frame.
16975 Expressed in range of [0-~181.02].
16978 Display the median value for hue within the input frame. Expressed in range of
16982 Display the average value for hue within the input frame. Expressed in range of
16986 Display the average of sample value difference between all values of the Y
16987 plane in the current frame and corresponding values of the previous input frame.
16988 Expressed in range of [0-255].
16991 Display the average of sample value difference between all values of the U
16992 plane in the current frame and corresponding values of the previous input frame.
16993 Expressed in range of [0-255].
16996 Display the average of sample value difference between all values of the V
16997 plane in the current frame and corresponding values of the previous input frame.
16998 Expressed in range of [0-255].
17001 Display bit depth of Y plane in current frame.
17002 Expressed in range of [0-16].
17005 Display bit depth of U plane in current frame.
17006 Expressed in range of [0-16].
17009 Display bit depth of V plane in current frame.
17010 Expressed in range of [0-16].
17013 The filter accepts the following options:
17019 @option{stat} specify an additional form of image analysis.
17020 @option{out} output video with the specified type of pixel highlighted.
17022 Both options accept the following values:
17026 Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
17027 unlike the neighboring pixels of the same field. Examples of temporal outliers
17028 include the results of video dropouts, head clogs, or tape tracking issues.
17031 Identify @var{vertical line repetition}. Vertical line repetition includes
17032 similar rows of pixels within a frame. In born-digital video vertical line
17033 repetition is common, but this pattern is uncommon in video digitized from an
17034 analog source. When it occurs in video that results from the digitization of an
17035 analog source it can indicate concealment from a dropout compensator.
17038 Identify pixels that fall outside of legal broadcast range.
17042 Set the highlight color for the @option{out} option. The default color is
17046 @subsection Examples
17050 Output data of various video metrics:
17052 ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
17056 Output specific data about the minimum and maximum values of the Y plane per frame:
17058 ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
17062 Playback video while highlighting pixels that are outside of broadcast range in red.
17064 ffplay example.mov -vf signalstats="out=brng:color=red"
17068 Playback video with signalstats metadata drawn over the frame.
17070 ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
17073 The contents of signalstat_drawtext.txt used in the command are:
17076 Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
17077 U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
17078 V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
17079 saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
17087 Calculates the MPEG-7 Video Signature. The filter can handle more than one
17088 input. In this case the matching between the inputs can be calculated additionally.
17089 The filter always passes through the first input. The signature of each stream can
17090 be written into a file.
17092 It accepts the following options:
17096 Enable or disable the matching process.
17098 Available values are:
17102 Disable the calculation of a matching (default).
17104 Calculate the matching for the whole video and output whether the whole video
17105 matches or only parts.
17107 Calculate only until a matching is found or the video ends. Should be faster in
17112 Set the number of inputs. The option value must be a non negative integer.
17113 Default value is 1.
17116 Set the path to which the output is written. If there is more than one input,
17117 the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive
17118 integer), that will be replaced with the input number. If no filename is
17119 specified, no output will be written. This is the default.
17122 Choose the output format.
17124 Available values are:
17128 Use the specified binary representation (default).
17130 Use the specified xml representation.
17134 Set threshold to detect one word as similar. The option value must be an integer
17135 greater than zero. The default value is 9000.
17138 Set threshold to detect all words as similar. The option value must be an integer
17139 greater than zero. The default value is 60000.
17142 Set threshold to detect frames as similar. The option value must be an integer
17143 greater than zero. The default value is 116.
17146 Set the minimum length of a sequence in frames to recognize it as matching
17147 sequence. The option value must be a non negative integer value.
17148 The default value is 0.
17151 Set the minimum relation, that matching frames to all frames must have.
17152 The option value must be a double value between 0 and 1. The default value is 0.5.
17155 @subsection Examples
17159 To calculate the signature of an input video and store it in signature.bin:
17161 ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
17165 To detect whether two videos match and store the signatures in XML format in
17166 signature0.xml and signature1.xml:
17168 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 -
17176 Blur the input video without impacting the outlines.
17178 It accepts the following options:
17181 @item luma_radius, lr
17182 Set the luma radius. The option value must be a float number in
17183 the range [0.1,5.0] that specifies the variance of the gaussian filter
17184 used to blur the image (slower if larger). Default value is 1.0.
17186 @item luma_strength, ls
17187 Set the luma strength. The option value must be a float number
17188 in the range [-1.0,1.0] that configures the blurring. A value included
17189 in [0.0,1.0] will blur the image whereas a value included in
17190 [-1.0,0.0] will sharpen the image. Default value is 1.0.
17192 @item luma_threshold, lt
17193 Set the luma threshold used as a coefficient to determine
17194 whether a pixel should be blurred or not. The option value must be an
17195 integer in the range [-30,30]. A value of 0 will filter all the image,
17196 a value included in [0,30] will filter flat areas and a value included
17197 in [-30,0] will filter edges. Default value is 0.
17199 @item chroma_radius, cr
17200 Set the chroma radius. The option value must be a float number in
17201 the range [0.1,5.0] that specifies the variance of the gaussian filter
17202 used to blur the image (slower if larger). Default value is @option{luma_radius}.
17204 @item chroma_strength, cs
17205 Set the chroma strength. The option value must be a float number
17206 in the range [-1.0,1.0] that configures the blurring. A value included
17207 in [0.0,1.0] will blur the image whereas a value included in
17208 [-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}.
17210 @item chroma_threshold, ct
17211 Set the chroma threshold used as a coefficient to determine
17212 whether a pixel should be blurred or not. The option value must be an
17213 integer in the range [-30,30]. A value of 0 will filter all the image,
17214 a value included in [0,30] will filter flat areas and a value included
17215 in [-30,0] will filter edges. Default value is @option{luma_threshold}.
17218 If a chroma option is not explicitly set, the corresponding luma value
17222 Apply sobel operator to input video stream.
17224 The filter accepts the following option:
17228 Set which planes will be processed, unprocessed planes will be copied.
17229 By default value 0xf, all planes will be processed.
17232 Set value which will be multiplied with filtered result.
17235 Set value which will be added to filtered result.
17241 Apply a simple postprocessing filter that compresses and decompresses the image
17242 at several (or - in the case of @option{quality} level @code{6} - all) shifts
17243 and average the results.
17245 The filter accepts the following options:
17249 Set quality. This option defines the number of levels for averaging. It accepts
17250 an integer in the range 0-6. If set to @code{0}, the filter will have no
17251 effect. A value of @code{6} means the higher quality. For each increment of
17252 that value the speed drops by a factor of approximately 2. Default value is
17256 Force a constant quantization parameter. If not set, the filter will use the QP
17257 from the video stream (if available).
17260 Set thresholding mode. Available modes are:
17264 Set hard thresholding (default).
17266 Set soft thresholding (better de-ringing effect, but likely blurrier).
17269 @item use_bframe_qp
17270 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
17271 option may cause flicker since the B-Frames have often larger QP. Default is
17272 @code{0} (not enabled).
17275 @subsection Commands
17277 This filter supports the following commands:
17279 @item quality, level
17280 Set quality level. The value @code{max} can be used to set the maximum level,
17281 currently @code{6}.
17286 Scale the input by applying one of the super-resolution methods based on
17287 convolutional neural networks. Supported models:
17291 Super-Resolution Convolutional Neural Network model (SRCNN).
17292 See @url{https://arxiv.org/abs/1501.00092}.
17295 Efficient Sub-Pixel Convolutional Neural Network model (ESPCN).
17296 See @url{https://arxiv.org/abs/1609.05158}.
17299 Training scripts as well as scripts for model file (.pb) saving can be found at
17300 @url{https://github.com/XueweiMeng/sr/tree/sr_dnn_native}. Original repository
17301 is at @url{https://github.com/HighVoltageRocknRoll/sr.git}.
17303 Native model files (.model) can be generated from TensorFlow model
17304 files (.pb) by using tools/python/convert.py
17306 The filter accepts the following options:
17310 Specify which DNN backend to use for model loading and execution. This option accepts
17311 the following values:
17315 Native implementation of DNN loading and execution.
17318 TensorFlow backend. To enable this backend you
17319 need to install the TensorFlow for C library (see
17320 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
17321 @code{--enable-libtensorflow}
17324 Default value is @samp{native}.
17327 Set path to model file specifying network architecture and its parameters.
17328 Note that different backends use different file formats. TensorFlow backend
17329 can load files for both formats, while native backend can load files for only
17333 Set scale factor for SRCNN model. Allowed values are @code{2}, @code{3} and @code{4}.
17334 Default value is @code{2}. Scale factor is necessary for SRCNN model, because it accepts
17335 input upscaled using bicubic upscaling with proper scale factor.
17340 Obtain the SSIM (Structural SImilarity Metric) between two input videos.
17342 This filter takes in input two input videos, the first input is
17343 considered the "main" source and is passed unchanged to the
17344 output. The second input is used as a "reference" video for computing
17347 Both video inputs must have the same resolution and pixel format for
17348 this filter to work correctly. Also it assumes that both inputs
17349 have the same number of frames, which are compared one by one.
17351 The filter stores the calculated SSIM of each frame.
17353 The description of the accepted parameters follows.
17356 @item stats_file, f
17357 If specified the filter will use the named file to save the SSIM of
17358 each individual frame. When filename equals "-" the data is sent to
17362 The file printed if @var{stats_file} is selected, contains a sequence of
17363 key/value pairs of the form @var{key}:@var{value} for each compared
17366 A description of each shown parameter follows:
17370 sequential number of the input frame, starting from 1
17372 @item Y, U, V, R, G, B
17373 SSIM of the compared frames for the component specified by the suffix.
17376 SSIM of the compared frames for the whole frame.
17379 Same as above but in dB representation.
17382 This filter also supports the @ref{framesync} options.
17384 @subsection Examples
17389 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
17390 [main][ref] ssim="stats_file=stats.log" [out]
17393 On this example the input file being processed is compared with the
17394 reference file @file{ref_movie.mpg}. The SSIM of each individual frame
17395 is stored in @file{stats.log}.
17398 Another example with both psnr and ssim at same time:
17400 ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
17404 Another example with different containers:
17406 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 -
17412 Convert between different stereoscopic image formats.
17414 The filters accept the following options:
17418 Set stereoscopic image format of input.
17420 Available values for input image formats are:
17423 side by side parallel (left eye left, right eye right)
17426 side by side crosseye (right eye left, left eye right)
17429 side by side parallel with half width resolution
17430 (left eye left, right eye right)
17433 side by side crosseye with half width resolution
17434 (right eye left, left eye right)
17438 above-below (left eye above, right eye below)
17442 above-below (right eye above, left eye below)
17446 above-below with half height resolution
17447 (left eye above, right eye below)
17451 above-below with half height resolution
17452 (right eye above, left eye below)
17455 alternating frames (left eye first, right eye second)
17458 alternating frames (right eye first, left eye second)
17461 interleaved rows (left eye has top row, right eye starts on next row)
17464 interleaved rows (right eye has top row, left eye starts on next row)
17467 interleaved columns, left eye first
17470 interleaved columns, right eye first
17472 Default value is @samp{sbsl}.
17476 Set stereoscopic image format of output.
17480 side by side parallel (left eye left, right eye right)
17483 side by side crosseye (right eye left, left eye right)
17486 side by side parallel with half width resolution
17487 (left eye left, right eye right)
17490 side by side crosseye with half width resolution
17491 (right eye left, left eye right)
17495 above-below (left eye above, right eye below)
17499 above-below (right eye above, left eye below)
17503 above-below with half height resolution
17504 (left eye above, right eye below)
17508 above-below with half height resolution
17509 (right eye above, left eye below)
17512 alternating frames (left eye first, right eye second)
17515 alternating frames (right eye first, left eye second)
17518 interleaved rows (left eye has top row, right eye starts on next row)
17521 interleaved rows (right eye has top row, left eye starts on next row)
17524 anaglyph red/blue gray
17525 (red filter on left eye, blue filter on right eye)
17528 anaglyph red/green gray
17529 (red filter on left eye, green filter on right eye)
17532 anaglyph red/cyan gray
17533 (red filter on left eye, cyan filter on right eye)
17536 anaglyph red/cyan half colored
17537 (red filter on left eye, cyan filter on right eye)
17540 anaglyph red/cyan color
17541 (red filter on left eye, cyan filter on right eye)
17544 anaglyph red/cyan color optimized with the least squares projection of dubois
17545 (red filter on left eye, cyan filter on right eye)
17548 anaglyph green/magenta gray
17549 (green filter on left eye, magenta filter on right eye)
17552 anaglyph green/magenta half colored
17553 (green filter on left eye, magenta filter on right eye)
17556 anaglyph green/magenta colored
17557 (green filter on left eye, magenta filter on right eye)
17560 anaglyph green/magenta color optimized with the least squares projection of dubois
17561 (green filter on left eye, magenta filter on right eye)
17564 anaglyph yellow/blue gray
17565 (yellow filter on left eye, blue filter on right eye)
17568 anaglyph yellow/blue half colored
17569 (yellow filter on left eye, blue filter on right eye)
17572 anaglyph yellow/blue colored
17573 (yellow filter on left eye, blue filter on right eye)
17576 anaglyph yellow/blue color optimized with the least squares projection of dubois
17577 (yellow filter on left eye, blue filter on right eye)
17580 mono output (left eye only)
17583 mono output (right eye only)
17586 checkerboard, left eye first
17589 checkerboard, right eye first
17592 interleaved columns, left eye first
17595 interleaved columns, right eye first
17601 Default value is @samp{arcd}.
17604 @subsection Examples
17608 Convert input video from side by side parallel to anaglyph yellow/blue dubois:
17614 Convert input video from above below (left eye above, right eye below) to side by side crosseye.
17620 @section streamselect, astreamselect
17621 Select video or audio streams.
17623 The filter accepts the following options:
17627 Set number of inputs. Default is 2.
17630 Set input indexes to remap to outputs.
17633 @subsection Commands
17635 The @code{streamselect} and @code{astreamselect} filter supports the following
17640 Set input indexes to remap to outputs.
17643 @subsection Examples
17647 Select first 5 seconds 1st stream and rest of time 2nd stream:
17649 sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
17653 Same as above, but for audio:
17655 asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
17662 Draw subtitles on top of input video using the libass library.
17664 To enable compilation of this filter you need to configure FFmpeg with
17665 @code{--enable-libass}. This filter also requires a build with libavcodec and
17666 libavformat to convert the passed subtitles file to ASS (Advanced Substation
17667 Alpha) subtitles format.
17669 The filter accepts the following options:
17673 Set the filename of the subtitle file to read. It must be specified.
17675 @item original_size
17676 Specify the size of the original video, the video for which the ASS file
17677 was composed. For the syntax of this option, check the
17678 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17679 Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
17680 correctly scale the fonts if the aspect ratio has been changed.
17683 Set a directory path containing fonts that can be used by the filter.
17684 These fonts will be used in addition to whatever the font provider uses.
17687 Process alpha channel, by default alpha channel is untouched.
17690 Set subtitles input character encoding. @code{subtitles} filter only. Only
17691 useful if not UTF-8.
17693 @item stream_index, si
17694 Set subtitles stream index. @code{subtitles} filter only.
17697 Override default style or script info parameters of the subtitles. It accepts a
17698 string containing ASS style format @code{KEY=VALUE} couples separated by ",".
17701 If the first key is not specified, it is assumed that the first value
17702 specifies the @option{filename}.
17704 For example, to render the file @file{sub.srt} on top of the input
17705 video, use the command:
17710 which is equivalent to:
17712 subtitles=filename=sub.srt
17715 To render the default subtitles stream from file @file{video.mkv}, use:
17717 subtitles=video.mkv
17720 To render the second subtitles stream from that file, use:
17722 subtitles=video.mkv:si=1
17725 To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue
17726 @code{DejaVu Serif}, use:
17728 subtitles=sub.srt:force_style='FontName=DejaVu Serif,PrimaryColour=&HCCFF0000'
17731 @section super2xsai
17733 Scale the input by 2x and smooth using the Super2xSaI (Scale and
17734 Interpolate) pixel art scaling algorithm.
17736 Useful for enlarging pixel art images without reducing sharpness.
17740 Swap two rectangular objects in video.
17742 This filter accepts the following options:
17752 Set 1st rect x coordinate.
17755 Set 1st rect y coordinate.
17758 Set 2nd rect x coordinate.
17761 Set 2nd rect y coordinate.
17763 All expressions are evaluated once for each frame.
17766 The all options are expressions containing the following constants:
17771 The input width and height.
17774 same as @var{w} / @var{h}
17777 input sample aspect ratio
17780 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
17783 The number of the input frame, starting from 0.
17786 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
17789 the position in the file of the input frame, NAN if unknown
17797 Apply telecine process to the video.
17799 This filter accepts the following options:
17808 The default value is @code{top}.
17812 A string of numbers representing the pulldown pattern you wish to apply.
17813 The default value is @code{23}.
17817 Some typical patterns:
17822 24p: 2332 (preferred)
17829 24p: 222222222223 ("Euro pulldown")
17834 @section thistogram
17836 Compute and draw a color distribution histogram for the input video across time.
17838 Unlike @ref{histogram} video filter which only shows histogram of single input frame
17839 at certain time, this filter shows also past histograms of number of frames defined
17840 by @code{width} option.
17842 The computed histogram is a representation of the color component
17843 distribution in an image.
17845 The filter accepts the following options:
17849 Set width of single color component output. Default value is @code{0}.
17850 Value of @code{0} means width will be picked from input video.
17851 This also set number of passed histograms to keep.
17852 Allowed range is [0, 8192].
17854 @item display_mode, d
17856 It accepts the following values:
17859 Per color component graphs are placed below each other.
17862 Per color component graphs are placed side by side.
17865 Presents information identical to that in the @code{parade}, except
17866 that the graphs representing color components are superimposed directly
17869 Default is @code{stack}.
17871 @item levels_mode, m
17872 Set mode. Can be either @code{linear}, or @code{logarithmic}.
17873 Default is @code{linear}.
17875 @item components, c
17876 Set what color components to display.
17877 Default is @code{7}.
17880 Set background opacity. Default is @code{0.9}.
17883 Show envelope. Default is disabled.
17886 Set envelope color. Default is @code{gold}.
17891 Apply threshold effect to video stream.
17893 This filter needs four video streams to perform thresholding.
17894 First stream is stream we are filtering.
17895 Second stream is holding threshold values, third stream is holding min values,
17896 and last, fourth stream is holding max values.
17898 The filter accepts the following option:
17902 Set which planes will be processed, unprocessed planes will be copied.
17903 By default value 0xf, all planes will be processed.
17906 For example if first stream pixel's component value is less then threshold value
17907 of pixel component from 2nd threshold stream, third stream value will picked,
17908 otherwise fourth stream pixel component value will be picked.
17910 Using color source filter one can perform various types of thresholding:
17912 @subsection Examples
17916 Binary threshold, using gray color as threshold:
17918 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
17922 Inverted binary threshold, using gray color as threshold:
17924 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
17928 Truncate binary threshold, using gray color as threshold:
17930 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
17934 Threshold to zero, using gray color as threshold:
17936 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
17940 Inverted threshold to zero, using gray color as threshold:
17942 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
17947 Select the most representative frame in a given sequence of consecutive frames.
17949 The filter accepts the following options:
17953 Set the frames batch size to analyze; in a set of @var{n} frames, the filter
17954 will pick one of them, and then handle the next batch of @var{n} frames until
17955 the end. Default is @code{100}.
17958 Since the filter keeps track of the whole frames sequence, a bigger @var{n}
17959 value will result in a higher memory usage, so a high value is not recommended.
17961 @subsection Examples
17965 Extract one picture each 50 frames:
17971 Complete example of a thumbnail creation with @command{ffmpeg}:
17973 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
17979 Tile several successive frames together.
17981 The filter accepts the following options:
17986 Set the grid size (i.e. the number of lines and columns). For the syntax of
17987 this option, check the
17988 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17991 Set the maximum number of frames to render in the given area. It must be less
17992 than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
17993 the area will be used.
17996 Set the outer border margin in pixels.
17999 Set the inner border thickness (i.e. the number of pixels between frames). For
18000 more advanced padding options (such as having different values for the edges),
18001 refer to the pad video filter.
18004 Specify the color of the unused area. For the syntax of this option, check the
18005 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
18006 The default value of @var{color} is "black".
18009 Set the number of frames to overlap when tiling several successive frames together.
18010 The value must be between @code{0} and @var{nb_frames - 1}.
18013 Set the number of frames to initially be empty before displaying first output frame.
18014 This controls how soon will one get first output frame.
18015 The value must be between @code{0} and @var{nb_frames - 1}.
18018 @subsection Examples
18022 Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
18024 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
18026 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
18027 duplicating each output frame to accommodate the originally detected frame
18031 Display @code{5} pictures in an area of @code{3x2} frames,
18032 with @code{7} pixels between them, and @code{2} pixels of initial margin, using
18033 mixed flat and named options:
18035 tile=3x2:nb_frames=5:padding=7:margin=2
18039 @section tinterlace
18041 Perform various types of temporal field interlacing.
18043 Frames are counted starting from 1, so the first input frame is
18046 The filter accepts the following options:
18051 Specify the mode of the interlacing. This option can also be specified
18052 as a value alone. See below for a list of values for this option.
18054 Available values are:
18058 Move odd frames into the upper field, even into the lower field,
18059 generating a double height frame at half frame rate.
18063 Frame 1 Frame 2 Frame 3 Frame 4
18065 11111 22222 33333 44444
18066 11111 22222 33333 44444
18067 11111 22222 33333 44444
18068 11111 22222 33333 44444
18082 Only output odd frames, even frames are dropped, generating a frame with
18083 unchanged height at half frame rate.
18088 Frame 1 Frame 2 Frame 3 Frame 4
18090 11111 22222 33333 44444
18091 11111 22222 33333 44444
18092 11111 22222 33333 44444
18093 11111 22222 33333 44444
18103 Only output even frames, odd frames are dropped, generating a frame with
18104 unchanged height at half frame rate.
18109 Frame 1 Frame 2 Frame 3 Frame 4
18111 11111 22222 33333 44444
18112 11111 22222 33333 44444
18113 11111 22222 33333 44444
18114 11111 22222 33333 44444
18124 Expand each frame to full height, but pad alternate lines with black,
18125 generating a frame with double height at the same input frame rate.
18130 Frame 1 Frame 2 Frame 3 Frame 4
18132 11111 22222 33333 44444
18133 11111 22222 33333 44444
18134 11111 22222 33333 44444
18135 11111 22222 33333 44444
18138 11111 ..... 33333 .....
18139 ..... 22222 ..... 44444
18140 11111 ..... 33333 .....
18141 ..... 22222 ..... 44444
18142 11111 ..... 33333 .....
18143 ..... 22222 ..... 44444
18144 11111 ..... 33333 .....
18145 ..... 22222 ..... 44444
18149 @item interleave_top, 4
18150 Interleave the upper field from odd frames with the lower field from
18151 even frames, generating a frame with unchanged height at half frame rate.
18156 Frame 1 Frame 2 Frame 3 Frame 4
18158 11111<- 22222 33333<- 44444
18159 11111 22222<- 33333 44444<-
18160 11111<- 22222 33333<- 44444
18161 11111 22222<- 33333 44444<-
18171 @item interleave_bottom, 5
18172 Interleave the lower field from odd frames with the upper field from
18173 even frames, generating a frame with unchanged height at half frame rate.
18178 Frame 1 Frame 2 Frame 3 Frame 4
18180 11111 22222<- 33333 44444<-
18181 11111<- 22222 33333<- 44444
18182 11111 22222<- 33333 44444<-
18183 11111<- 22222 33333<- 44444
18193 @item interlacex2, 6
18194 Double frame rate with unchanged height. Frames are inserted each
18195 containing the second temporal field from the previous input frame and
18196 the first temporal field from the next input frame. This mode relies on
18197 the top_field_first flag. Useful for interlaced video displays with no
18198 field synchronisation.
18203 Frame 1 Frame 2 Frame 3 Frame 4
18205 11111 22222 33333 44444
18206 11111 22222 33333 44444
18207 11111 22222 33333 44444
18208 11111 22222 33333 44444
18211 11111 22222 22222 33333 33333 44444 44444
18212 11111 11111 22222 22222 33333 33333 44444
18213 11111 22222 22222 33333 33333 44444 44444
18214 11111 11111 22222 22222 33333 33333 44444
18219 Move odd frames into the upper field, even into the lower field,
18220 generating a double height frame at same frame rate.
18225 Frame 1 Frame 2 Frame 3 Frame 4
18227 11111 22222 33333 44444
18228 11111 22222 33333 44444
18229 11111 22222 33333 44444
18230 11111 22222 33333 44444
18233 11111 33333 33333 55555
18234 22222 22222 44444 44444
18235 11111 33333 33333 55555
18236 22222 22222 44444 44444
18237 11111 33333 33333 55555
18238 22222 22222 44444 44444
18239 11111 33333 33333 55555
18240 22222 22222 44444 44444
18245 Numeric values are deprecated but are accepted for backward
18246 compatibility reasons.
18248 Default mode is @code{merge}.
18251 Specify flags influencing the filter process.
18253 Available value for @var{flags} is:
18256 @item low_pass_filter, vlpf
18257 Enable linear vertical low-pass filtering in the filter.
18258 Vertical low-pass filtering is required when creating an interlaced
18259 destination from a progressive source which contains high-frequency
18260 vertical detail. Filtering will reduce interlace 'twitter' and Moire
18263 @item complex_filter, cvlpf
18264 Enable complex vertical low-pass filtering.
18265 This will slightly less reduce interlace 'twitter' and Moire
18266 patterning but better retain detail and subjective sharpness impression.
18269 Bypass already interlaced frames, only adjust the frame rate.
18272 Vertical low-pass filtering and bypassing already interlaced frames can only be
18273 enabled for @option{mode} @var{interleave_top} and @var{interleave_bottom}.
18279 Mix successive video frames.
18281 A description of the accepted options follows.
18285 The number of successive frames to mix. If unspecified, it defaults to 3.
18288 Specify weight of each input video frame.
18289 Each weight is separated by space. If number of weights is smaller than
18290 number of @var{frames} last specified weight will be used for all remaining
18294 Specify scale, if it is set it will be multiplied with sum
18295 of each weight multiplied with pixel values to give final destination
18296 pixel value. By default @var{scale} is auto scaled to sum of weights.
18299 @subsection Examples
18303 Average 7 successive frames:
18305 tmix=frames=7:weights="1 1 1 1 1 1 1"
18309 Apply simple temporal convolution:
18311 tmix=frames=3:weights="-1 3 -1"
18315 Similar as above but only showing temporal differences:
18317 tmix=frames=3:weights="-1 2 -1":scale=1
18323 Tone map colors from different dynamic ranges.
18325 This filter expects data in single precision floating point, as it needs to
18326 operate on (and can output) out-of-range values. Another filter, such as
18327 @ref{zscale}, is needed to convert the resulting frame to a usable format.
18329 The tonemapping algorithms implemented only work on linear light, so input
18330 data should be linearized beforehand (and possibly correctly tagged).
18333 ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
18336 @subsection Options
18337 The filter accepts the following options.
18341 Set the tone map algorithm to use.
18343 Possible values are:
18346 Do not apply any tone map, only desaturate overbright pixels.
18349 Hard-clip any out-of-range values. Use it for perfect color accuracy for
18350 in-range values, while distorting out-of-range values.
18353 Stretch the entire reference gamut to a linear multiple of the display.
18356 Fit a logarithmic transfer between the tone curves.
18359 Preserve overall image brightness with a simple curve, using nonlinear
18360 contrast, which results in flattening details and degrading color accuracy.
18363 Preserve both dark and bright details better than @var{reinhard}, at the cost
18364 of slightly darkening everything. Use it when detail preservation is more
18365 important than color and brightness accuracy.
18368 Smoothly map out-of-range values, while retaining contrast and colors for
18369 in-range material as much as possible. Use it when color accuracy is more
18370 important than detail preservation.
18376 Tune the tone mapping algorithm.
18378 This affects the following algorithms:
18384 Specifies the scale factor to use while stretching.
18388 Specifies the exponent of the function.
18392 Specify an extra linear coefficient to multiply into the signal before clipping.
18396 Specify the local contrast coefficient at the display peak.
18397 Default to 0.5, which means that in-gamut values will be about half as bright
18404 Specify the transition point from linear to mobius transform. Every value
18405 below this point is guaranteed to be mapped 1:1. The higher the value, the
18406 more accurate the result will be, at the cost of losing bright details.
18407 Default to 0.3, which due to the steep initial slope still preserves in-range
18408 colors fairly accurately.
18412 Apply desaturation for highlights that exceed this level of brightness. The
18413 higher the parameter, the more color information will be preserved. This
18414 setting helps prevent unnaturally blown-out colors for super-highlights, by
18415 (smoothly) turning into white instead. This makes images feel more natural,
18416 at the cost of reducing information about out-of-range colors.
18418 The default of 2.0 is somewhat conservative and will mostly just apply to
18419 skies or directly sunlit surfaces. A setting of 0.0 disables this option.
18421 This option works only if the input frame has a supported color tag.
18424 Override signal/nominal/reference peak with this value. Useful when the
18425 embedded peak information in display metadata is not reliable or when tone
18426 mapping from a lower range to a higher range.
18431 Temporarily pad video frames.
18433 The filter accepts the following options:
18437 Specify number of delay frames before input video stream.
18440 Specify number of padding frames after input video stream.
18441 Set to -1 to pad indefinitely.
18444 Set kind of frames added to beginning of stream.
18445 Can be either @var{add} or @var{clone}.
18446 With @var{add} frames of solid-color are added.
18447 With @var{clone} frames are clones of first frame.
18450 Set kind of frames added to end of stream.
18451 Can be either @var{add} or @var{clone}.
18452 With @var{add} frames of solid-color are added.
18453 With @var{clone} frames are clones of last frame.
18455 @item start_duration, stop_duration
18456 Specify the duration of the start/stop delay. See
18457 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
18458 for the accepted syntax.
18459 These options override @var{start} and @var{stop}.
18462 Specify the color of the padded area. For the syntax of this option,
18463 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
18464 manual,ffmpeg-utils}.
18466 The default value of @var{color} is "black".
18472 Transpose rows with columns in the input video and optionally flip it.
18474 It accepts the following parameters:
18479 Specify the transposition direction.
18481 Can assume the following values:
18483 @item 0, 4, cclock_flip
18484 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
18492 Rotate by 90 degrees clockwise, that is:
18500 Rotate by 90 degrees counterclockwise, that is:
18507 @item 3, 7, clock_flip
18508 Rotate by 90 degrees clockwise and vertically flip, that is:
18516 For values between 4-7, the transposition is only done if the input
18517 video geometry is portrait and not landscape. These values are
18518 deprecated, the @code{passthrough} option should be used instead.
18520 Numerical values are deprecated, and should be dropped in favor of
18521 symbolic constants.
18524 Do not apply the transposition if the input geometry matches the one
18525 specified by the specified value. It accepts the following values:
18528 Always apply transposition.
18530 Preserve portrait geometry (when @var{height} >= @var{width}).
18532 Preserve landscape geometry (when @var{width} >= @var{height}).
18535 Default value is @code{none}.
18538 For example to rotate by 90 degrees clockwise and preserve portrait
18541 transpose=dir=1:passthrough=portrait
18544 The command above can also be specified as:
18546 transpose=1:portrait
18549 @section transpose_npp
18551 Transpose rows with columns in the input video and optionally flip it.
18552 For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options.
18554 It accepts the following parameters:
18559 Specify the transposition direction.
18561 Can assume the following values:
18564 Rotate by 90 degrees counterclockwise and vertically flip. (default)
18567 Rotate by 90 degrees clockwise.
18570 Rotate by 90 degrees counterclockwise.
18573 Rotate by 90 degrees clockwise and vertically flip.
18577 Do not apply the transposition if the input geometry matches the one
18578 specified by the specified value. It accepts the following values:
18581 Always apply transposition. (default)
18583 Preserve portrait geometry (when @var{height} >= @var{width}).
18585 Preserve landscape geometry (when @var{width} >= @var{height}).
18591 Trim the input so that the output contains one continuous subpart of the input.
18593 It accepts the following parameters:
18596 Specify the time of the start of the kept section, i.e. the frame with the
18597 timestamp @var{start} will be the first frame in the output.
18600 Specify the time of the first frame that will be dropped, i.e. the frame
18601 immediately preceding the one with the timestamp @var{end} will be the last
18602 frame in the output.
18605 This is the same as @var{start}, except this option sets the start timestamp
18606 in timebase units instead of seconds.
18609 This is the same as @var{end}, except this option sets the end timestamp
18610 in timebase units instead of seconds.
18613 The maximum duration of the output in seconds.
18616 The number of the first frame that should be passed to the output.
18619 The number of the first frame that should be dropped.
18622 @option{start}, @option{end}, and @option{duration} are expressed as time
18623 duration specifications; see
18624 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
18625 for the accepted syntax.
18627 Note that the first two sets of the start/end options and the @option{duration}
18628 option look at the frame timestamp, while the _frame variants simply count the
18629 frames that pass through the filter. Also note that this filter does not modify
18630 the timestamps. If you wish for the output timestamps to start at zero, insert a
18631 setpts filter after the trim filter.
18633 If multiple start or end options are set, this filter tries to be greedy and
18634 keep all the frames that match at least one of the specified constraints. To keep
18635 only the part that matches all the constraints at once, chain multiple trim
18638 The defaults are such that all the input is kept. So it is possible to set e.g.
18639 just the end values to keep everything before the specified time.
18644 Drop everything except the second minute of input:
18646 ffmpeg -i INPUT -vf trim=60:120
18650 Keep only the first second:
18652 ffmpeg -i INPUT -vf trim=duration=1
18657 @section unpremultiply
18658 Apply alpha unpremultiply effect to input video stream using first plane
18659 of second stream as alpha.
18661 Both streams must have same dimensions and same pixel format.
18663 The filter accepts the following option:
18667 Set which planes will be processed, unprocessed planes will be copied.
18668 By default value 0xf, all planes will be processed.
18670 If the format has 1 or 2 components, then luma is bit 0.
18671 If the format has 3 or 4 components:
18672 for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red;
18673 for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V.
18674 If present, the alpha channel is always the last bit.
18677 Do not require 2nd input for processing, instead use alpha plane from input stream.
18683 Sharpen or blur the input video.
18685 It accepts the following parameters:
18688 @item luma_msize_x, lx
18689 Set the luma matrix horizontal size. It must be an odd integer between
18690 3 and 23. The default value is 5.
18692 @item luma_msize_y, ly
18693 Set the luma matrix vertical size. It must be an odd integer between 3
18694 and 23. The default value is 5.
18696 @item luma_amount, la
18697 Set the luma effect strength. It must be a floating point number, reasonable
18698 values lay between -1.5 and 1.5.
18700 Negative values will blur the input video, while positive values will
18701 sharpen it, a value of zero will disable the effect.
18703 Default value is 1.0.
18705 @item chroma_msize_x, cx
18706 Set the chroma matrix horizontal size. It must be an odd integer
18707 between 3 and 23. The default value is 5.
18709 @item chroma_msize_y, cy
18710 Set the chroma matrix vertical size. It must be an odd integer
18711 between 3 and 23. The default value is 5.
18713 @item chroma_amount, ca
18714 Set the chroma effect strength. It must be a floating point number, reasonable
18715 values lay between -1.5 and 1.5.
18717 Negative values will blur the input video, while positive values will
18718 sharpen it, a value of zero will disable the effect.
18720 Default value is 0.0.
18724 All parameters are optional and default to the equivalent of the
18725 string '5:5:1.0:5:5:0.0'.
18727 @subsection Examples
18731 Apply strong luma sharpen effect:
18733 unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
18737 Apply a strong blur of both luma and chroma parameters:
18739 unsharp=7:7:-2:7:7:-2
18745 Apply ultra slow/simple postprocessing filter that compresses and decompresses
18746 the image at several (or - in the case of @option{quality} level @code{8} - all)
18747 shifts and average the results.
18749 The way this differs from the behavior of spp is that uspp actually encodes &
18750 decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
18751 DCT similar to MJPEG.
18753 The filter accepts the following options:
18757 Set quality. This option defines the number of levels for averaging. It accepts
18758 an integer in the range 0-8. If set to @code{0}, the filter will have no
18759 effect. A value of @code{8} means the higher quality. For each increment of
18760 that value the speed drops by a factor of approximately 2. Default value is
18764 Force a constant quantization parameter. If not set, the filter will use the QP
18765 from the video stream (if available).
18770 Convert 360 videos between various formats.
18772 The filter accepts the following options:
18778 Set format of the input/output video.
18786 Equirectangular projection.
18791 Cubemap with 3x2/6x1/1x6 layout.
18793 Format specific options:
18798 Set padding proportion for the input/output cubemap. Values in decimals.
18805 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)
18808 Default value is @b{@samp{0}}.
18812 Set fixed padding for the input/output cubemap. Values in pixels.
18814 Default value is @b{@samp{0}}. If greater than zero it overrides other padding options.
18818 Set order of faces for the input/output cubemap. Choose one direction for each position.
18820 Designation of directions:
18836 Default value is @b{@samp{rludfb}}.
18840 Set rotation of faces for the input/output cubemap. Choose one angle for each position.
18842 Designation of angles:
18845 0 degrees clockwise
18847 90 degrees clockwise
18849 180 degrees clockwise
18851 270 degrees clockwise
18854 Default value is @b{@samp{000000}}.
18858 Equi-Angular Cubemap.
18865 Format specific options:
18870 Set output horizontal/vertical/diagonal field of view. Values in degrees.
18872 If diagonal field of view is set it overrides horizontal and vertical field of view.
18877 Set input horizontal/vertical/diagonal field of view. Values in degrees.
18879 If diagonal field of view is set it overrides horizontal and vertical field of view.
18885 Format specific options:
18889 Set padding proportion. Values in decimals.
18899 Default value is @b{@samp{0}}.
18904 Facebook's 360 format.
18907 Stereographic format.
18909 Format specific options:
18914 Set output horizontal/vertical/diagonal field of view. Values in degrees.
18916 If diagonal field of view is set it overrides horizontal and vertical field of view.
18921 Set input horizontal/vertical/diagonal field of view. Values in degrees.
18923 If diagonal field of view is set it overrides horizontal and vertical field of view.
18930 Ball format, gives significant distortion toward the back.
18933 Hammer-Aitoff map projection format.
18936 Sinusoidal map projection format.
18939 Fisheye projection.
18941 Format specific options:
18946 Set output horizontal/vertical/diagonal field of view. Values in degrees.
18948 If diagonal field of view is set it overrides horizontal and vertical field of view.
18953 Set input horizontal/vertical/diagonal field of view. Values in degrees.
18955 If diagonal field of view is set it overrides horizontal and vertical field of view.
18959 Pannini projection. @i{(output only)}
18961 Format specific options:
18964 Set pannini parameter.
18968 Cylindrical projection.
18970 Format specific options:
18975 Set output horizontal/vertical/diagonal field of view. Values in degrees.
18977 If diagonal field of view is set it overrides horizontal and vertical field of view.
18982 Set input horizontal/vertical/diagonal field of view. Values in degrees.
18984 If diagonal field of view is set it overrides horizontal and vertical field of view.
18988 Perspective projection. @i{(output only)}
18990 Format specific options:
18993 Set perspective parameter.
18997 Tetrahedron projection.
19001 Set interpolation method.@*
19002 @i{Note: more complex interpolation methods require much more memory to run.}
19012 Bilinear interpolation.
19015 Bicubic interpolation.
19018 Lanczos interpolation.
19021 Spline16 interpolation.
19024 Gaussian interpolation.
19027 Default value is @b{@samp{line}}.
19031 Set the output video resolution.
19033 Default resolution depends on formats.
19037 Set the input/output stereo format.
19048 Default value is @b{@samp{2d}} for input and output format.
19053 Set rotation for the output video. Values in degrees.
19056 Set rotation order for the output video. Choose one item for each position.
19067 Default value is @b{@samp{ypr}}.
19072 Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values.
19076 Set if input video is flipped horizontally/vertically. Boolean values.
19079 Set if input video is transposed. Boolean value, by default disabled.
19082 Set if output video needs to be transposed. Boolean value, by default disabled.
19085 Build mask in alpha plane for all unmapped pixels by marking them fully transparent. Boolean value, by default disabled.
19088 @subsection Examples
19092 Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation:
19094 ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv
19097 Extract back view of Equi-Angular Cubemap:
19099 ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv
19102 Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format:
19104 v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb
19108 @section vaguedenoiser
19110 Apply a wavelet based denoiser.
19112 It transforms each frame from the video input into the wavelet domain,
19113 using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
19114 the obtained coefficients. It does an inverse wavelet transform after.
19115 Due to wavelet properties, it should give a nice smoothed result, and
19116 reduced noise, without blurring picture features.
19118 This filter accepts the following options:
19122 The filtering strength. The higher, the more filtered the video will be.
19123 Hard thresholding can use a higher threshold than soft thresholding
19124 before the video looks overfiltered. Default value is 2.
19127 The filtering method the filter will use.
19129 It accepts the following values:
19132 All values under the threshold will be zeroed.
19135 All values under the threshold will be zeroed. All values above will be
19136 reduced by the threshold.
19139 Scales or nullifies coefficients - intermediary between (more) soft and
19140 (less) hard thresholding.
19143 Default is garrote.
19146 Number of times, the wavelet will decompose the picture. Picture can't
19147 be decomposed beyond a particular point (typically, 8 for a 640x480
19148 frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6.
19151 Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85.
19154 A list of the planes to process. By default all planes are processed.
19157 @section vectorscope
19159 Display 2 color component values in the two dimensional graph (which is called
19162 This filter accepts the following options:
19166 Set vectorscope mode.
19168 It accepts the following values:
19172 Gray values are displayed on graph, higher brightness means more pixels have
19173 same component color value on location in graph. This is the default mode.
19176 Gray values are displayed on graph. Surrounding pixels values which are not
19177 present in video frame are drawn in gradient of 2 color components which are
19178 set by option @code{x} and @code{y}. The 3rd color component is static.
19181 Actual color components values present in video frame are displayed on graph.
19184 Similar as color2 but higher frequency of same values @code{x} and @code{y}
19185 on graph increases value of another color component, which is luminance by
19186 default values of @code{x} and @code{y}.
19189 Actual colors present in video frame are displayed on graph. If two different
19190 colors map to same position on graph then color with higher value of component
19191 not present in graph is picked.
19194 Gray values are displayed on graph. Similar to @code{color} but with 3rd color
19195 component picked from radial gradient.
19199 Set which color component will be represented on X-axis. Default is @code{1}.
19202 Set which color component will be represented on Y-axis. Default is @code{2}.
19205 Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
19206 of color component which represents frequency of (X, Y) location in graph.
19211 No envelope, this is default.
19214 Instant envelope, even darkest single pixel will be clearly highlighted.
19217 Hold maximum and minimum values presented in graph over time. This way you
19218 can still spot out of range values without constantly looking at vectorscope.
19221 Peak and instant envelope combined together.
19225 Set what kind of graticule to draw.
19234 Set graticule opacity.
19237 Set graticule flags.
19241 Draw graticule for white point.
19244 Draw graticule for black point.
19247 Draw color points short names.
19251 Set background opacity.
19253 @item lthreshold, l
19254 Set low threshold for color component not represented on X or Y axis.
19255 Values lower than this value will be ignored. Default is 0.
19256 Note this value is multiplied with actual max possible value one pixel component
19257 can have. So for 8-bit input and low threshold value of 0.1 actual threshold
19260 @item hthreshold, h
19261 Set high threshold for color component not represented on X or Y axis.
19262 Values higher than this value will be ignored. Default is 1.
19263 Note this value is multiplied with actual max possible value one pixel component
19264 can have. So for 8-bit input and high threshold value of 0.9 actual threshold
19265 is 0.9 * 255 = 230.
19267 @item colorspace, c
19268 Set what kind of colorspace to use when drawing graticule.
19278 Set color tint for gray/tint vectorscope mode. By default both options are zero.
19279 This means no tint, and output will remain gray.
19282 @anchor{vidstabdetect}
19283 @section vidstabdetect
19285 Analyze video stabilization/deshaking. Perform pass 1 of 2, see
19286 @ref{vidstabtransform} for pass 2.
19288 This filter generates a file with relative translation and rotation
19289 transform information about subsequent frames, which is then used by
19290 the @ref{vidstabtransform} filter.
19292 To enable compilation of this filter you need to configure FFmpeg with
19293 @code{--enable-libvidstab}.
19295 This filter accepts the following options:
19299 Set the path to the file used to write the transforms information.
19300 Default value is @file{transforms.trf}.
19303 Set how shaky the video is and how quick the camera is. It accepts an
19304 integer in the range 1-10, a value of 1 means little shakiness, a
19305 value of 10 means strong shakiness. Default value is 5.
19308 Set the accuracy of the detection process. It must be a value in the
19309 range 1-15. A value of 1 means low accuracy, a value of 15 means high
19310 accuracy. Default value is 15.
19313 Set stepsize of the search process. The region around minimum is
19314 scanned with 1 pixel resolution. Default value is 6.
19317 Set minimum contrast. Below this value a local measurement field is
19318 discarded. Must be a floating point value in the range 0-1. Default
19322 Set reference frame number for tripod mode.
19324 If enabled, the motion of the frames is compared to a reference frame
19325 in the filtered stream, identified by the specified number. The idea
19326 is to compensate all movements in a more-or-less static scene and keep
19327 the camera view absolutely still.
19329 If set to 0, it is disabled. The frames are counted starting from 1.
19332 Show fields and transforms in the resulting frames. It accepts an
19333 integer in the range 0-2. Default value is 0, which disables any
19337 @subsection Examples
19341 Use default values:
19347 Analyze strongly shaky movie and put the results in file
19348 @file{mytransforms.trf}:
19350 vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
19354 Visualize the result of internal transformations in the resulting
19357 vidstabdetect=show=1
19361 Analyze a video with medium shakiness using @command{ffmpeg}:
19363 ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
19367 @anchor{vidstabtransform}
19368 @section vidstabtransform
19370 Video stabilization/deshaking: pass 2 of 2,
19371 see @ref{vidstabdetect} for pass 1.
19373 Read a file with transform information for each frame and
19374 apply/compensate them. Together with the @ref{vidstabdetect}
19375 filter this can be used to deshake videos. See also
19376 @url{http://public.hronopik.de/vid.stab}. It is important to also use
19377 the @ref{unsharp} filter, see below.
19379 To enable compilation of this filter you need to configure FFmpeg with
19380 @code{--enable-libvidstab}.
19382 @subsection Options
19386 Set path to the file used to read the transforms. Default value is
19387 @file{transforms.trf}.
19390 Set the number of frames (value*2 + 1) used for lowpass filtering the
19391 camera movements. Default value is 10.
19393 For example a number of 10 means that 21 frames are used (10 in the
19394 past and 10 in the future) to smoothen the motion in the video. A
19395 larger value leads to a smoother video, but limits the acceleration of
19396 the camera (pan/tilt movements). 0 is a special case where a static
19397 camera is simulated.
19400 Set the camera path optimization algorithm.
19402 Accepted values are:
19405 gaussian kernel low-pass filter on camera motion (default)
19407 averaging on transformations
19411 Set maximal number of pixels to translate frames. Default value is -1,
19415 Set maximal angle in radians (degree*PI/180) to rotate frames. Default
19416 value is -1, meaning no limit.
19419 Specify how to deal with borders that may be visible due to movement
19422 Available values are:
19425 keep image information from previous frame (default)
19427 fill the border black
19431 Invert transforms if set to 1. Default value is 0.
19434 Consider transforms as relative to previous frame if set to 1,
19435 absolute if set to 0. Default value is 0.
19438 Set percentage to zoom. A positive value will result in a zoom-in
19439 effect, a negative value in a zoom-out effect. Default value is 0 (no
19443 Set optimal zooming to avoid borders.
19445 Accepted values are:
19450 optimal static zoom value is determined (only very strong movements
19451 will lead to visible borders) (default)
19453 optimal adaptive zoom value is determined (no borders will be
19454 visible), see @option{zoomspeed}
19457 Note that the value given at zoom is added to the one calculated here.
19460 Set percent to zoom maximally each frame (enabled when
19461 @option{optzoom} is set to 2). Range is from 0 to 5, default value is
19465 Specify type of interpolation.
19467 Available values are:
19472 linear only horizontal
19474 linear in both directions (default)
19476 cubic in both directions (slow)
19480 Enable virtual tripod mode if set to 1, which is equivalent to
19481 @code{relative=0:smoothing=0}. Default value is 0.
19483 Use also @code{tripod} option of @ref{vidstabdetect}.
19486 Increase log verbosity if set to 1. Also the detected global motions
19487 are written to the temporary file @file{global_motions.trf}. Default
19491 @subsection Examples
19495 Use @command{ffmpeg} for a typical stabilization with default values:
19497 ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
19500 Note the use of the @ref{unsharp} filter which is always recommended.
19503 Zoom in a bit more and load transform data from a given file:
19505 vidstabtransform=zoom=5:input="mytransforms.trf"
19509 Smoothen the video even more:
19511 vidstabtransform=smoothing=30
19517 Flip the input video vertically.
19519 For example, to vertically flip a video with @command{ffmpeg}:
19521 ffmpeg -i in.avi -vf "vflip" out.avi
19526 Detect variable frame rate video.
19528 This filter tries to detect if the input is variable or constant frame rate.
19530 At end it will output number of frames detected as having variable delta pts,
19531 and ones with constant delta pts.
19532 If there was frames with variable delta, than it will also show min, max and
19533 average delta encountered.
19537 Boost or alter saturation.
19539 The filter accepts the following options:
19542 Set strength of boost if positive value or strength of alter if negative value.
19543 Default is 0. Allowed range is from -2 to 2.
19546 Set the red balance. Default is 1. Allowed range is from -10 to 10.
19549 Set the green balance. Default is 1. Allowed range is from -10 to 10.
19552 Set the blue balance. Default is 1. Allowed range is from -10 to 10.
19555 Set the red luma coefficient.
19558 Set the green luma coefficient.
19561 Set the blue luma coefficient.
19564 If @code{intensity} is negative and this is set to 1, colors will change,
19565 otherwise colors will be less saturated, more towards gray.
19568 @subsection Commands
19570 This filter supports the all above options as @ref{commands}.
19575 Make or reverse a natural vignetting effect.
19577 The filter accepts the following options:
19581 Set lens angle expression as a number of radians.
19583 The value is clipped in the @code{[0,PI/2]} range.
19585 Default value: @code{"PI/5"}
19589 Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
19593 Set forward/backward mode.
19595 Available modes are:
19598 The larger the distance from the central point, the darker the image becomes.
19601 The larger the distance from the central point, the brighter the image becomes.
19602 This can be used to reverse a vignette effect, though there is no automatic
19603 detection to extract the lens @option{angle} and other settings (yet). It can
19604 also be used to create a burning effect.
19607 Default value is @samp{forward}.
19610 Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
19612 It accepts the following values:
19615 Evaluate expressions only once during the filter initialization.
19618 Evaluate expressions for each incoming frame. This is way slower than the
19619 @samp{init} mode since it requires all the scalers to be re-computed, but it
19620 allows advanced dynamic expressions.
19623 Default value is @samp{init}.
19626 Set dithering to reduce the circular banding effects. Default is @code{1}
19630 Set vignette aspect. This setting allows one to adjust the shape of the vignette.
19631 Setting this value to the SAR of the input will make a rectangular vignetting
19632 following the dimensions of the video.
19634 Default is @code{1/1}.
19637 @subsection Expressions
19639 The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
19640 following parameters.
19645 input width and height
19648 the number of input frame, starting from 0
19651 the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
19652 @var{TB} units, NAN if undefined
19655 frame rate of the input video, NAN if the input frame rate is unknown
19658 the PTS (Presentation TimeStamp) of the filtered video frame,
19659 expressed in seconds, NAN if undefined
19662 time base of the input video
19666 @subsection Examples
19670 Apply simple strong vignetting effect:
19676 Make a flickering vignetting:
19678 vignette='PI/4+random(1)*PI/50':eval=frame
19683 @section vmafmotion
19685 Obtain the average VMAF motion score of a video.
19686 It is one of the component metrics of VMAF.
19688 The obtained average motion score is printed through the logging system.
19690 The filter accepts the following options:
19694 If specified, the filter will use the named file to save the motion score of
19695 each frame with respect to the previous frame.
19696 When filename equals "-" the data is sent to standard output.
19701 ffmpeg -i ref.mpg -vf vmafmotion -f null -
19705 Stack input videos vertically.
19707 All streams must be of same pixel format and of same width.
19709 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
19710 to create same output.
19712 The filter accepts the following options:
19716 Set number of input streams. Default is 2.
19719 If set to 1, force the output to terminate when the shortest input
19720 terminates. Default value is 0.
19725 Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
19726 Deinterlacing Filter").
19728 Based on the process described by Martin Weston for BBC R&D, and
19729 implemented based on the de-interlace algorithm written by Jim
19730 Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
19731 uses filter coefficients calculated by BBC R&D.
19733 This filter uses field-dominance information in frame to decide which
19734 of each pair of fields to place first in the output.
19735 If it gets it wrong use @ref{setfield} filter before @code{w3fdif} filter.
19737 There are two sets of filter coefficients, so called "simple"
19738 and "complex". Which set of filter coefficients is used can
19739 be set by passing an optional parameter:
19743 Set the interlacing filter coefficients. Accepts one of the following values:
19747 Simple filter coefficient set.
19749 More-complex filter coefficient set.
19751 Default value is @samp{complex}.
19754 Specify which frames to deinterlace. Accepts one of the following values:
19758 Deinterlace all frames,
19760 Only deinterlace frames marked as interlaced.
19763 Default value is @samp{all}.
19767 Video waveform monitor.
19769 The waveform monitor plots color component intensity. By default luminance
19770 only. Each column of the waveform corresponds to a column of pixels in the
19773 It accepts the following options:
19777 Can be either @code{row}, or @code{column}. Default is @code{column}.
19778 In row mode, the graph on the left side represents color component value 0 and
19779 the right side represents value = 255. In column mode, the top side represents
19780 color component value = 0 and bottom side represents value = 255.
19783 Set intensity. Smaller values are useful to find out how many values of the same
19784 luminance are distributed across input rows/columns.
19785 Default value is @code{0.04}. Allowed range is [0, 1].
19788 Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
19789 In mirrored mode, higher values will be represented on the left
19790 side for @code{row} mode and at the top for @code{column} mode. Default is
19791 @code{1} (mirrored).
19795 It accepts the following values:
19798 Presents information identical to that in the @code{parade}, except
19799 that the graphs representing color components are superimposed directly
19802 This display mode makes it easier to spot relative differences or similarities
19803 in overlapping areas of the color components that are supposed to be identical,
19804 such as neutral whites, grays, or blacks.
19807 Display separate graph for the color components side by side in
19808 @code{row} mode or one below the other in @code{column} mode.
19811 Display separate graph for the color components side by side in
19812 @code{column} mode or one below the other in @code{row} mode.
19814 Using this display mode makes it easy to spot color casts in the highlights
19815 and shadows of an image, by comparing the contours of the top and the bottom
19816 graphs of each waveform. Since whites, grays, and blacks are characterized
19817 by exactly equal amounts of red, green, and blue, neutral areas of the picture
19818 should display three waveforms of roughly equal width/height. If not, the
19819 correction is easy to perform by making level adjustments the three waveforms.
19821 Default is @code{stack}.
19823 @item components, c
19824 Set which color components to display. Default is 1, which means only luminance
19825 or red color component if input is in RGB colorspace. If is set for example to
19826 7 it will display all 3 (if) available color components.
19831 No envelope, this is default.
19834 Instant envelope, minimum and maximum values presented in graph will be easily
19835 visible even with small @code{step} value.
19838 Hold minimum and maximum values presented in graph across time. This way you
19839 can still spot out of range values without constantly looking at waveforms.
19842 Peak and instant envelope combined together.
19848 No filtering, this is default.
19851 Luma and chroma combined together.
19854 Similar as above, but shows difference between blue and red chroma.
19857 Similar as above, but use different colors.
19860 Similar as above, but again with different colors.
19863 Displays only chroma.
19866 Displays actual color value on waveform.
19869 Similar as above, but with luma showing frequency of chroma values.
19873 Set which graticule to display.
19877 Do not display graticule.
19880 Display green graticule showing legal broadcast ranges.
19883 Display orange graticule showing legal broadcast ranges.
19886 Display invert graticule showing legal broadcast ranges.
19890 Set graticule opacity.
19893 Set graticule flags.
19897 Draw numbers above lines. By default enabled.
19900 Draw dots instead of lines.
19904 Set scale used for displaying graticule.
19911 Default is digital.
19914 Set background opacity.
19918 Set tint for output.
19919 Only used with lowpass filter and when display is not overlay and input
19920 pixel formats are not RGB.
19923 @section weave, doubleweave
19925 The @code{weave} takes a field-based video input and join
19926 each two sequential fields into single frame, producing a new double
19927 height clip with half the frame rate and half the frame count.
19929 The @code{doubleweave} works same as @code{weave} but without
19930 halving frame rate and frame count.
19932 It accepts the following option:
19936 Set first field. Available values are:
19940 Set the frame as top-field-first.
19943 Set the frame as bottom-field-first.
19947 @subsection Examples
19951 Interlace video using @ref{select} and @ref{separatefields} filter:
19953 separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
19958 Apply the xBR high-quality magnification filter which is designed for pixel
19959 art. It follows a set of edge-detection rules, see
19960 @url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}.
19962 It accepts the following option:
19966 Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
19967 @code{3xBR} and @code{4} for @code{4xBR}.
19968 Default is @code{3}.
19973 Apply cross fade from one input video stream to another input video stream.
19974 The cross fade is applied for specified duration.
19976 The filter accepts the following options:
19980 Set one of available transition effects:
20016 Default transition effect is fade.
20019 Set cross fade duration in seconds.
20020 Default duration is 1 second.
20023 Set cross fade start relative to first input stream in seconds.
20024 Default offset is 0.
20027 Set expression for custom transition effect.
20029 The expressions can use the following variables and functions:
20034 The coordinates of the current sample.
20038 The width and height of the image.
20041 Progress of transition effect.
20044 Currently processed plane.
20047 Return value of first input at current location and plane.
20050 Return value of second input at current location and plane.
20056 Return the value of the pixel at location (@var{x},@var{y}) of the
20057 first/second/third/fourth component of first input.
20063 Return the value of the pixel at location (@var{x},@var{y}) of the
20064 first/second/third/fourth component of second input.
20068 @subsection Examples
20072 Cross fade from one input video to another input video, with fade transition and duration of transition
20073 of 2 seconds starting at offset of 5 seconds:
20075 ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4
20080 Pick median pixels from several input videos.
20082 The filter accepts the following options:
20086 Set number of inputs.
20087 Default is 3. Allowed range is from 3 to 255.
20088 If number of inputs is even number, than result will be mean value between two median values.
20091 Set which planes to filter. Default value is @code{15}, by which all planes are processed.
20095 Stack video inputs into custom layout.
20097 All streams must be of same pixel format.
20099 The filter accepts the following options:
20103 Set number of input streams. Default is 2.
20106 Specify layout of inputs.
20107 This option requires the desired layout configuration to be explicitly set by the user.
20108 This sets position of each video input in output. Each input
20109 is separated by '|'.
20110 The first number represents the column, and the second number represents the row.
20111 Numbers start at 0 and are separated by '_'. Optionally one can use wX and hX,
20112 where X is video input from which to take width or height.
20113 Multiple values can be used when separated by '+'. In such
20114 case values are summed together.
20116 Note that if inputs are of different sizes gaps may appear, as not all of
20117 the output video frame will be filled. Similarly, videos can overlap each
20118 other if their position doesn't leave enough space for the full frame of
20121 For 2 inputs, a default layout of @code{0_0|w0_0} is set. In all other cases,
20122 a layout must be set by the user.
20125 If set to 1, force the output to terminate when the shortest input
20126 terminates. Default value is 0.
20129 If set to valid color, all unused pixels will be filled with that color.
20130 By default fill is set to none, so it is disabled.
20133 @subsection Examples
20137 Display 4 inputs into 2x2 grid.
20141 input1(0, 0) | input3(w0, 0)
20142 input2(0, h0) | input4(w0, h0)
20146 xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
20149 Note that if inputs are of different sizes, gaps or overlaps may occur.
20152 Display 4 inputs into 1x4 grid.
20159 input4(0, h0+h1+h2)
20163 xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
20166 Note that if inputs are of different widths, unused space will appear.
20169 Display 9 inputs into 3x3 grid.
20173 input1(0, 0) | input4(w0, 0) | input7(w0+w3, 0)
20174 input2(0, h0) | input5(w0, h0) | input8(w0+w3, h0)
20175 input3(0, h0+h1) | input6(w0, h0+h1) | input9(w0+w3, h0+h1)
20179 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
20182 Note that if inputs are of different sizes, gaps or overlaps may occur.
20185 Display 16 inputs into 4x4 grid.
20189 input1(0, 0) | input5(w0, 0) | input9 (w0+w4, 0) | input13(w0+w4+w8, 0)
20190 input2(0, h0) | input6(w0, h0) | input10(w0+w4, h0) | input14(w0+w4+w8, h0)
20191 input3(0, h0+h1) | input7(w0, h0+h1) | input11(w0+w4, h0+h1) | input15(w0+w4+w8, h0+h1)
20192 input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2)
20196 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|
20197 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
20200 Note that if inputs are of different sizes, gaps or overlaps may occur.
20207 Deinterlace the input video ("yadif" means "yet another deinterlacing
20210 It accepts the following parameters:
20216 The interlacing mode to adopt. It accepts one of the following values:
20219 @item 0, send_frame
20220 Output one frame for each frame.
20221 @item 1, send_field
20222 Output one frame for each field.
20223 @item 2, send_frame_nospatial
20224 Like @code{send_frame}, but it skips the spatial interlacing check.
20225 @item 3, send_field_nospatial
20226 Like @code{send_field}, but it skips the spatial interlacing check.
20229 The default value is @code{send_frame}.
20232 The picture field parity assumed for the input interlaced video. It accepts one
20233 of the following values:
20237 Assume the top field is first.
20239 Assume the bottom field is first.
20241 Enable automatic detection of field parity.
20244 The default value is @code{auto}.
20245 If the interlacing is unknown or the decoder does not export this information,
20246 top field first will be assumed.
20249 Specify which frames to deinterlace. Accepts one of the following
20254 Deinterlace all frames.
20255 @item 1, interlaced
20256 Only deinterlace frames marked as interlaced.
20259 The default value is @code{all}.
20262 @section yadif_cuda
20264 Deinterlace the input video using the @ref{yadif} algorithm, but implemented
20265 in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec
20268 It accepts the following parameters:
20274 The interlacing mode to adopt. It accepts one of the following values:
20277 @item 0, send_frame
20278 Output one frame for each frame.
20279 @item 1, send_field
20280 Output one frame for each field.
20281 @item 2, send_frame_nospatial
20282 Like @code{send_frame}, but it skips the spatial interlacing check.
20283 @item 3, send_field_nospatial
20284 Like @code{send_field}, but it skips the spatial interlacing check.
20287 The default value is @code{send_frame}.
20290 The picture field parity assumed for the input interlaced video. It accepts one
20291 of the following values:
20295 Assume the top field is first.
20297 Assume the bottom field is first.
20299 Enable automatic detection of field parity.
20302 The default value is @code{auto}.
20303 If the interlacing is unknown or the decoder does not export this information,
20304 top field first will be assumed.
20307 Specify which frames to deinterlace. Accepts one of the following
20312 Deinterlace all frames.
20313 @item 1, interlaced
20314 Only deinterlace frames marked as interlaced.
20317 The default value is @code{all}.
20322 Apply blur filter while preserving edges ("yaepblur" means "yet another edge preserving blur filter").
20323 The algorithm is described in
20324 "J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980."
20326 It accepts the following parameters:
20330 Set the window radius. Default value is 3.
20333 Set which planes to filter. Default is only the first plane.
20336 Set blur strength. Default value is 128.
20339 @subsection Commands
20340 This filter supports same @ref{commands} as options.
20344 Apply Zoom & Pan effect.
20346 This filter accepts the following options:
20350 Set the zoom expression. Range is 1-10. Default is 1.
20354 Set the x and y expression. Default is 0.
20357 Set the duration expression in number of frames.
20358 This sets for how many number of frames effect will last for
20359 single input image.
20362 Set the output image size, default is 'hd720'.
20365 Set the output frame rate, default is '25'.
20368 Each expression can contain the following constants:
20387 Output frame count.
20391 Last calculated 'x' and 'y' position from 'x' and 'y' expression
20392 for current input frame.
20396 'x' and 'y' of last output frame of previous input frame or 0 when there was
20397 not yet such frame (first input frame).
20400 Last calculated zoom from 'z' expression for current input frame.
20403 Last calculated zoom of last output frame of previous input frame.
20406 Number of output frames for current input frame. Calculated from 'd' expression
20407 for each input frame.
20410 number of output frames created for previous input frame
20413 Rational number: input width / input height
20416 sample aspect ratio
20419 display aspect ratio
20423 @subsection Examples
20427 Zoom-in up to 1.5 and pan at same time to some spot near center of picture:
20429 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
20433 Zoom-in up to 1.5 and pan always at center of picture:
20435 zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
20439 Same as above but without pausing:
20441 zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
20447 Scale (resize) the input video, using the z.lib library:
20448 @url{https://github.com/sekrit-twc/zimg}. To enable compilation of this
20449 filter, you need to configure FFmpeg with @code{--enable-libzimg}.
20451 The zscale filter forces the output display aspect ratio to be the same
20452 as the input, by changing the output sample aspect ratio.
20454 If the input image format is different from the format requested by
20455 the next filter, the zscale filter will convert the input to the
20458 @subsection Options
20459 The filter accepts the following options.
20464 Set the output video dimension expression. Default value is the input
20467 If the @var{width} or @var{w} value is 0, the input width is used for
20468 the output. If the @var{height} or @var{h} value is 0, the input height
20469 is used for the output.
20471 If one and only one of the values is -n with n >= 1, the zscale filter
20472 will use a value that maintains the aspect ratio of the input image,
20473 calculated from the other specified dimension. After that it will,
20474 however, make sure that the calculated dimension is divisible by n and
20475 adjust the value if necessary.
20477 If both values are -n with n >= 1, the behavior will be identical to
20478 both values being set to 0 as previously detailed.
20480 See below for the list of accepted constants for use in the dimension
20484 Set the video size. For the syntax of this option, check the
20485 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20488 Set the dither type.
20490 Possible values are:
20495 @item error_diffusion
20501 Set the resize filter type.
20503 Possible values are:
20513 Default is bilinear.
20516 Set the color range.
20518 Possible values are:
20525 Default is same as input.
20528 Set the color primaries.
20530 Possible values are:
20540 Default is same as input.
20543 Set the transfer characteristics.
20545 Possible values are:
20559 Default is same as input.
20562 Set the colorspace matrix.
20564 Possible value are:
20575 Default is same as input.
20578 Set the input color range.
20580 Possible values are:
20587 Default is same as input.
20589 @item primariesin, pin
20590 Set the input color primaries.
20592 Possible values are:
20602 Default is same as input.
20604 @item transferin, tin
20605 Set the input transfer characteristics.
20607 Possible values are:
20618 Default is same as input.
20620 @item matrixin, min
20621 Set the input colorspace matrix.
20623 Possible value are:
20635 Set the output chroma location.
20637 Possible values are:
20648 @item chromalin, cin
20649 Set the input chroma location.
20651 Possible values are:
20663 Set the nominal peak luminance.
20666 The values of the @option{w} and @option{h} options are expressions
20667 containing the following constants:
20672 The input width and height
20676 These are the same as @var{in_w} and @var{in_h}.
20680 The output (scaled) width and height
20684 These are the same as @var{out_w} and @var{out_h}
20687 The same as @var{iw} / @var{ih}
20690 input sample aspect ratio
20693 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
20697 horizontal and vertical input chroma subsample values. For example for the
20698 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
20702 horizontal and vertical output chroma subsample values. For example for the
20703 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
20706 @subsection Commands
20708 This filter supports the following commands:
20712 Set the output video dimension expression.
20713 The command accepts the same syntax of the corresponding option.
20715 If the specified expression is not valid, it is kept at its current
20719 @c man end VIDEO FILTERS
20721 @chapter OpenCL Video Filters
20722 @c man begin OPENCL VIDEO FILTERS
20724 Below is a description of the currently available OpenCL video filters.
20726 To enable compilation of these filters you need to configure FFmpeg with
20727 @code{--enable-opencl}.
20729 Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph.
20732 @item -init_hw_device opencl[=@var{name}][:@var{device}[,@var{key=value}...]]
20733 Initialise a new hardware device of type @var{opencl} called @var{name}, using the
20734 given device parameters.
20736 @item -filter_hw_device @var{name}
20737 Pass the hardware device called @var{name} to all filters in any filter graph.
20741 For more detailed information see @url{https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options}
20745 Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it.
20747 -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
20751 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.
20753 @section avgblur_opencl
20755 Apply average blur filter.
20757 The filter accepts the following options:
20761 Set horizontal radius size.
20762 Range is @code{[1, 1024]} and default value is @code{1}.
20765 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
20768 Set vertical radius size. Range is @code{[1, 1024]} and default value is @code{0}. If zero, @code{sizeX} value will be used.
20771 @subsection Example
20775 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.
20777 -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
20781 @section boxblur_opencl
20783 Apply a boxblur algorithm to the input video.
20785 It accepts the following parameters:
20789 @item luma_radius, lr
20790 @item luma_power, lp
20791 @item chroma_radius, cr
20792 @item chroma_power, cp
20793 @item alpha_radius, ar
20794 @item alpha_power, ap
20798 A description of the accepted options follows.
20801 @item luma_radius, lr
20802 @item chroma_radius, cr
20803 @item alpha_radius, ar
20804 Set an expression for the box radius in pixels used for blurring the
20805 corresponding input plane.
20807 The radius value must be a non-negative number, and must not be
20808 greater than the value of the expression @code{min(w,h)/2} for the
20809 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
20812 Default value for @option{luma_radius} is "2". If not specified,
20813 @option{chroma_radius} and @option{alpha_radius} default to the
20814 corresponding value set for @option{luma_radius}.
20816 The expressions can contain the following constants:
20820 The input width and height in pixels.
20824 The input chroma image width and height in pixels.
20828 The horizontal and vertical chroma subsample values. For example, for the
20829 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
20832 @item luma_power, lp
20833 @item chroma_power, cp
20834 @item alpha_power, ap
20835 Specify how many times the boxblur filter is applied to the
20836 corresponding plane.
20838 Default value for @option{luma_power} is 2. If not specified,
20839 @option{chroma_power} and @option{alpha_power} default to the
20840 corresponding value set for @option{luma_power}.
20842 A value of 0 will disable the effect.
20845 @subsection Examples
20847 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.
20851 Apply a boxblur filter with the luma, chroma, and alpha radius
20852 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.
20854 -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
20855 -i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
20859 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.
20861 For the luma plane, a 2x2 box radius will be run once.
20863 For the chroma plane, a 4x4 box radius will be run 5 times.
20865 For the alpha plane, a 3x3 box radius will be run 7 times.
20867 -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
20871 @section colorkey_opencl
20872 RGB colorspace color keying.
20874 The filter accepts the following options:
20878 The color which will be replaced with transparency.
20881 Similarity percentage with the key color.
20883 0.01 matches only the exact key color, while 1.0 matches everything.
20888 0.0 makes pixels either fully transparent, or not transparent at all.
20890 Higher values result in semi-transparent pixels, with a higher transparency
20891 the more similar the pixels color is to the key color.
20894 @subsection Examples
20898 Make every semi-green pixel in the input transparent with some slight blending:
20900 -i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
20904 @section convolution_opencl
20906 Apply convolution of 3x3, 5x5, 7x7 matrix.
20908 The filter accepts the following options:
20915 Set matrix for each plane.
20916 Matrix is sequence of 9, 25 or 49 signed numbers.
20917 Default value for each plane is @code{0 0 0 0 1 0 0 0 0}.
20923 Set multiplier for calculated value for each plane.
20924 If unset or 0, it will be sum of all matrix elements.
20925 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{1.0}.
20931 Set bias for each plane. This value is added to the result of the multiplication.
20932 Useful for making the overall image brighter or darker.
20933 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{0.0}.
20937 @subsection Examples
20943 -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
20949 -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
20953 Apply edge enhance:
20955 -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
20961 -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
20965 Apply laplacian edge detector which includes diagonals:
20967 -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
20973 -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
20977 @section erosion_opencl
20979 Apply erosion effect to the video.
20981 This filter replaces the pixel by the local(3x3) minimum.
20983 It accepts the following options:
20990 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
20991 If @code{0}, plane will remain unchanged.
20994 Flag which specifies the pixel to refer to.
20995 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
20997 Flags to local 3x3 coordinates region centered on @code{x}:
21006 @subsection Example
21010 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.
21012 -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
21016 @section deshake_opencl
21017 Feature-point based video stabilization filter.
21019 The filter accepts the following options:
21023 Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to @code{0}.
21026 Whether or not additional debug info should be displayed, both in the processed output and in the console.
21028 Note that in order to see console debug output you will also need to pass @code{-v verbose} to ffmpeg.
21030 Viewing point matches in the output video is only supported for RGB input.
21032 Defaults to @code{0}.
21034 @item adaptive_crop
21035 Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels.
21037 Defaults to @code{1}.
21039 @item refine_features
21040 Whether or not feature points should be refined at a sub-pixel level.
21042 This can be turned off for a slight performance gain at the cost of precision.
21044 Defaults to @code{1}.
21046 @item smooth_strength
21047 The strength of the smoothing applied to the camera path from @code{0.0} to @code{1.0}.
21049 @code{1.0} is the maximum smoothing strength while values less than that result in less smoothing.
21051 @code{0.0} causes the filter to adaptively choose a smoothing strength on a per-frame basis.
21053 Defaults to @code{0.0}.
21055 @item smooth_window_multiplier
21056 Controls the size of the smoothing window (the number of frames buffered to determine motion information from).
21058 The size of the smoothing window is determined by multiplying the framerate of the video by this number.
21060 Acceptable values range from @code{0.1} to @code{10.0}.
21062 Larger values increase the amount of motion data available for determining how to smooth the camera path,
21063 potentially improving smoothness, but also increase latency and memory usage.
21065 Defaults to @code{2.0}.
21069 @subsection Examples
21073 Stabilize a video with a fixed, medium smoothing strength:
21075 -i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT
21079 Stabilize a video with debugging (both in console and in rendered video):
21081 -i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT
21085 @section dilation_opencl
21087 Apply dilation effect to the video.
21089 This filter replaces the pixel by the local(3x3) maximum.
21091 It accepts the following options:
21098 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
21099 If @code{0}, plane will remain unchanged.
21102 Flag which specifies the pixel to refer to.
21103 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
21105 Flags to local 3x3 coordinates region centered on @code{x}:
21114 @subsection Example
21118 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.
21120 -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
21124 @section nlmeans_opencl
21126 Non-local Means denoise filter through OpenCL, this filter accepts same options as @ref{nlmeans}.
21128 @section overlay_opencl
21130 Overlay one video on top of another.
21132 It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid.
21133 This filter requires same memory layout for all the inputs. So, format conversion may be needed.
21135 The filter accepts the following options:
21140 Set the x coordinate of the overlaid video on the main video.
21141 Default value is @code{0}.
21144 Set the y coordinate of the overlaid video on the main video.
21145 Default value is @code{0}.
21149 @subsection Examples
21153 Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format.
21155 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
21158 The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p.
21160 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
21165 @section prewitt_opencl
21167 Apply the Prewitt operator (@url{https://en.wikipedia.org/wiki/Prewitt_operator}) to input video stream.
21169 The filter accepts the following option:
21173 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
21176 Set value which will be multiplied with filtered result.
21177 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
21180 Set value which will be added to filtered result.
21181 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
21184 @subsection Example
21188 Apply the Prewitt operator with scale set to 2 and delta set to 10.
21190 -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
21194 @anchor{program_opencl}
21195 @section program_opencl
21197 Filter video using an OpenCL program.
21202 OpenCL program source file.
21205 Kernel name in program.
21208 Number of inputs to the filter. Defaults to 1.
21211 Size of output frames. Defaults to the same as the first input.
21215 The program source file must contain a kernel function with the given name,
21216 which will be run once for each plane of the output. Each run on a plane
21217 gets enqueued as a separate 2D global NDRange with one work-item for each
21218 pixel to be generated. The global ID offset for each work-item is therefore
21219 the coordinates of a pixel in the destination image.
21221 The kernel function needs to take the following arguments:
21224 Destination image, @var{__write_only image2d_t}.
21226 This image will become the output; the kernel should write all of it.
21228 Frame index, @var{unsigned int}.
21230 This is a counter starting from zero and increasing by one for each frame.
21232 Source images, @var{__read_only image2d_t}.
21234 These are the most recent images on each input. The kernel may read from
21235 them to generate the output, but they can't be written to.
21242 Copy the input to the output (output must be the same size as the input).
21244 __kernel void copy(__write_only image2d_t destination,
21245 unsigned int index,
21246 __read_only image2d_t source)
21248 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
21250 int2 location = (int2)(get_global_id(0), get_global_id(1));
21252 float4 value = read_imagef(source, sampler, location);
21254 write_imagef(destination, location, value);
21259 Apply a simple transformation, rotating the input by an amount increasing
21260 with the index counter. Pixel values are linearly interpolated by the
21261 sampler, and the output need not have the same dimensions as the input.
21263 __kernel void rotate_image(__write_only image2d_t dst,
21264 unsigned int index,
21265 __read_only image2d_t src)
21267 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
21268 CLK_FILTER_LINEAR);
21270 float angle = (float)index / 100.0f;
21272 float2 dst_dim = convert_float2(get_image_dim(dst));
21273 float2 src_dim = convert_float2(get_image_dim(src));
21275 float2 dst_cen = dst_dim / 2.0f;
21276 float2 src_cen = src_dim / 2.0f;
21278 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
21280 float2 dst_pos = convert_float2(dst_loc) - dst_cen;
21282 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
21283 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
21285 src_pos = src_pos * src_dim / dst_dim;
21287 float2 src_loc = src_pos + src_cen;
21289 if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
21290 src_loc.x > src_dim.x || src_loc.y > src_dim.y)
21291 write_imagef(dst, dst_loc, 0.5f);
21293 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
21298 Blend two inputs together, with the amount of each input used varying
21299 with the index counter.
21301 __kernel void blend_images(__write_only image2d_t dst,
21302 unsigned int index,
21303 __read_only image2d_t src1,
21304 __read_only image2d_t src2)
21306 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
21307 CLK_FILTER_LINEAR);
21309 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
21311 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
21312 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
21313 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
21315 float4 val1 = read_imagef(src1, sampler, src1_loc);
21316 float4 val2 = read_imagef(src2, sampler, src2_loc);
21318 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
21324 @section roberts_opencl
21325 Apply the Roberts cross operator (@url{https://en.wikipedia.org/wiki/Roberts_cross}) to input video stream.
21327 The filter accepts the following option:
21331 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
21334 Set value which will be multiplied with filtered result.
21335 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
21338 Set value which will be added to filtered result.
21339 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
21342 @subsection Example
21346 Apply the Roberts cross operator with scale set to 2 and delta set to 10
21348 -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
21352 @section sobel_opencl
21354 Apply the Sobel operator (@url{https://en.wikipedia.org/wiki/Sobel_operator}) to input video stream.
21356 The filter accepts the following option:
21360 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
21363 Set value which will be multiplied with filtered result.
21364 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
21367 Set value which will be added to filtered result.
21368 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
21371 @subsection Example
21375 Apply sobel operator with scale set to 2 and delta set to 10
21377 -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
21381 @section tonemap_opencl
21383 Perform HDR(PQ/HLG) to SDR conversion with tone-mapping.
21385 It accepts the following parameters:
21389 Specify the tone-mapping operator to be used. Same as tonemap option in @ref{tonemap}.
21392 Tune the tone mapping algorithm. same as param option in @ref{tonemap}.
21395 Apply desaturation for highlights that exceed this level of brightness. The
21396 higher the parameter, the more color information will be preserved. This
21397 setting helps prevent unnaturally blown-out colors for super-highlights, by
21398 (smoothly) turning into white instead. This makes images feel more natural,
21399 at the cost of reducing information about out-of-range colors.
21401 The default value is 0.5, and the algorithm here is a little different from
21402 the cpu version tonemap currently. A setting of 0.0 disables this option.
21405 The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold
21406 is used to detect whether the scene has changed or not. If the distance between
21407 the current frame average brightness and the current running average exceeds
21408 a threshold value, we would re-calculate scene average and peak brightness.
21409 The default value is 0.2.
21412 Specify the output pixel format.
21414 Currently supported formats are:
21421 Set the output color range.
21423 Possible values are:
21429 Default is same as input.
21432 Set the output color primaries.
21434 Possible values are:
21440 Default is same as input.
21443 Set the output transfer characteristics.
21445 Possible values are:
21454 Set the output colorspace matrix.
21456 Possible value are:
21462 Default is same as input.
21466 @subsection Example
21470 Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator.
21472 -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
21476 @section unsharp_opencl
21478 Sharpen or blur the input video.
21480 It accepts the following parameters:
21483 @item luma_msize_x, lx
21484 Set the luma matrix horizontal size.
21485 Range is @code{[1, 23]} and default value is @code{5}.
21487 @item luma_msize_y, ly
21488 Set the luma matrix vertical size.
21489 Range is @code{[1, 23]} and default value is @code{5}.
21491 @item luma_amount, la
21492 Set the luma effect strength.
21493 Range is @code{[-10, 10]} and default value is @code{1.0}.
21495 Negative values will blur the input video, while positive values will
21496 sharpen it, a value of zero will disable the effect.
21498 @item chroma_msize_x, cx
21499 Set the chroma matrix horizontal size.
21500 Range is @code{[1, 23]} and default value is @code{5}.
21502 @item chroma_msize_y, cy
21503 Set the chroma matrix vertical size.
21504 Range is @code{[1, 23]} and default value is @code{5}.
21506 @item chroma_amount, ca
21507 Set the chroma effect strength.
21508 Range is @code{[-10, 10]} and default value is @code{0.0}.
21510 Negative values will blur the input video, while positive values will
21511 sharpen it, a value of zero will disable the effect.
21515 All parameters are optional and default to the equivalent of the
21516 string '5:5:1.0:5:5:0.0'.
21518 @subsection Examples
21522 Apply strong luma sharpen effect:
21524 -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
21528 Apply a strong blur of both luma and chroma parameters:
21530 -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
21534 @section xfade_opencl
21536 Cross fade two videos with custom transition effect by using OpenCL.
21538 It accepts the following options:
21542 Set one of possible transition effects.
21546 Select custom transition effect, the actual transition description
21547 will be picked from source and kernel options.
21559 Default transition is fade.
21563 OpenCL program source file for custom transition.
21566 Set name of kernel to use for custom transition from program source file.
21569 Set duration of video transition.
21572 Set time of start of transition relative to first video.
21575 The program source file must contain a kernel function with the given name,
21576 which will be run once for each plane of the output. Each run on a plane
21577 gets enqueued as a separate 2D global NDRange with one work-item for each
21578 pixel to be generated. The global ID offset for each work-item is therefore
21579 the coordinates of a pixel in the destination image.
21581 The kernel function needs to take the following arguments:
21584 Destination image, @var{__write_only image2d_t}.
21586 This image will become the output; the kernel should write all of it.
21589 First Source image, @var{__read_only image2d_t}.
21590 Second Source image, @var{__read_only image2d_t}.
21592 These are the most recent images on each input. The kernel may read from
21593 them to generate the output, but they can't be written to.
21596 Transition progress, @var{float}. This value is always between 0 and 1 inclusive.
21603 Apply dots curtain transition effect:
21605 __kernel void blend_images(__write_only image2d_t dst,
21606 __read_only image2d_t src1,
21607 __read_only image2d_t src2,
21610 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
21611 CLK_FILTER_LINEAR);
21612 int2 p = (int2)(get_global_id(0), get_global_id(1));
21613 float2 rp = (float2)(get_global_id(0), get_global_id(1));
21614 float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y);
21617 float2 dots = (float2)(20.0, 20.0);
21618 float2 center = (float2)(0,0);
21621 float4 val1 = read_imagef(src1, sampler, p);
21622 float4 val2 = read_imagef(src2, sampler, p);
21623 bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center));
21625 write_imagef(dst, p, next ? val1 : val2);
21631 @c man end OPENCL VIDEO FILTERS
21633 @chapter VAAPI Video Filters
21634 @c man begin VAAPI VIDEO FILTERS
21636 VAAPI Video filters are usually used with VAAPI decoder and VAAPI encoder. Below is a description of VAAPI video filters.
21638 To enable compilation of these filters you need to configure FFmpeg with
21639 @code{--enable-vaapi}.
21641 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}
21643 @section tonemap_vaapi
21645 Perform HDR(High Dynamic Range) to SDR(Standard Dynamic Range) conversion with tone-mapping.
21646 It maps the dynamic range of HDR10 content to the SDR content.
21647 It currently only accepts HDR10 as input.
21649 It accepts the following parameters:
21653 Specify the output pixel format.
21655 Currently supported formats are:
21664 Set the output color primaries.
21666 Default is same as input.
21669 Set the output transfer characteristics.
21674 Set the output colorspace matrix.
21676 Default is same as input.
21680 @subsection Example
21684 Convert HDR(HDR10) video to bt2020-transfer-characteristic p010 format
21686 tonemap_vaapi=format=p010:t=bt2020-10
21690 @c man end VAAPI VIDEO FILTERS
21692 @chapter Video Sources
21693 @c man begin VIDEO SOURCES
21695 Below is a description of the currently available video sources.
21699 Buffer video frames, and make them available to the filter chain.
21701 This source is mainly intended for a programmatic use, in particular
21702 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
21704 It accepts the following parameters:
21709 Specify the size (width and height) of the buffered video frames. For the
21710 syntax of this option, check the
21711 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21714 The input video width.
21717 The input video height.
21720 A string representing the pixel format of the buffered video frames.
21721 It may be a number corresponding to a pixel format, or a pixel format
21725 Specify the timebase assumed by the timestamps of the buffered frames.
21728 Specify the frame rate expected for the video stream.
21730 @item pixel_aspect, sar
21731 The sample (pixel) aspect ratio of the input video.
21734 This option is deprecated and ignored. Prepend @code{sws_flags=@var{flags};}
21735 to the filtergraph description to specify swscale flags for automatically
21736 inserted scalers. See @ref{Filtergraph syntax}.
21738 @item hw_frames_ctx
21739 When using a hardware pixel format, this should be a reference to an
21740 AVHWFramesContext describing input frames.
21745 buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
21748 will instruct the source to accept video frames with size 320x240 and
21749 with format "yuv410p", assuming 1/24 as the timestamps timebase and
21750 square pixels (1:1 sample aspect ratio).
21751 Since the pixel format with name "yuv410p" corresponds to the number 6
21752 (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
21753 this example corresponds to:
21755 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
21758 Alternatively, the options can be specified as a flat string, but this
21759 syntax is deprecated:
21761 @var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den}
21765 Create a pattern generated by an elementary cellular automaton.
21767 The initial state of the cellular automaton can be defined through the
21768 @option{filename} and @option{pattern} options. If such options are
21769 not specified an initial state is created randomly.
21771 At each new frame a new row in the video is filled with the result of
21772 the cellular automaton next generation. The behavior when the whole
21773 frame is filled is defined by the @option{scroll} option.
21775 This source accepts the following options:
21779 Read the initial cellular automaton state, i.e. the starting row, from
21780 the specified file.
21781 In the file, each non-whitespace character is considered an alive
21782 cell, a newline will terminate the row, and further characters in the
21783 file will be ignored.
21786 Read the initial cellular automaton state, i.e. the starting row, from
21787 the specified string.
21789 Each non-whitespace character in the string is considered an alive
21790 cell, a newline will terminate the row, and further characters in the
21791 string will be ignored.
21794 Set the video rate, that is the number of frames generated per second.
21797 @item random_fill_ratio, ratio
21798 Set the random fill ratio for the initial cellular automaton row. It
21799 is a floating point number value ranging from 0 to 1, defaults to
21802 This option is ignored when a file or a pattern is specified.
21804 @item random_seed, seed
21805 Set the seed for filling randomly the initial row, must be an integer
21806 included between 0 and UINT32_MAX. If not specified, or if explicitly
21807 set to -1, the filter will try to use a good random seed on a best
21811 Set the cellular automaton rule, it is a number ranging from 0 to 255.
21812 Default value is 110.
21815 Set the size of the output video. For the syntax of this option, check the
21816 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21818 If @option{filename} or @option{pattern} is specified, the size is set
21819 by default to the width of the specified initial state row, and the
21820 height is set to @var{width} * PHI.
21822 If @option{size} is set, it must contain the width of the specified
21823 pattern string, and the specified pattern will be centered in the
21826 If a filename or a pattern string is not specified, the size value
21827 defaults to "320x518" (used for a randomly generated initial state).
21830 If set to 1, scroll the output upward when all the rows in the output
21831 have been already filled. If set to 0, the new generated row will be
21832 written over the top row just after the bottom row is filled.
21835 @item start_full, full
21836 If set to 1, completely fill the output with generated rows before
21837 outputting the first frame.
21838 This is the default behavior, for disabling set the value to 0.
21841 If set to 1, stitch the left and right row edges together.
21842 This is the default behavior, for disabling set the value to 0.
21845 @subsection Examples
21849 Read the initial state from @file{pattern}, and specify an output of
21852 cellauto=f=pattern:s=200x400
21856 Generate a random initial row with a width of 200 cells, with a fill
21859 cellauto=ratio=2/3:s=200x200
21863 Create a pattern generated by rule 18 starting by a single alive cell
21864 centered on an initial row with width 100:
21866 cellauto=p=@@:s=100x400:full=0:rule=18
21870 Specify a more elaborated initial pattern:
21872 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
21877 @anchor{coreimagesrc}
21878 @section coreimagesrc
21879 Video source generated on GPU using Apple's CoreImage API on OSX.
21881 This video source is a specialized version of the @ref{coreimage} video filter.
21882 Use a core image generator at the beginning of the applied filterchain to
21883 generate the content.
21885 The coreimagesrc video source accepts the following options:
21887 @item list_generators
21888 List all available generators along with all their respective options as well as
21889 possible minimum and maximum values along with the default values.
21891 list_generators=true
21895 Specify the size of the sourced video. For the syntax of this option, check the
21896 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21897 The default value is @code{320x240}.
21900 Specify the frame rate of the sourced video, as the number of frames
21901 generated per second. It has to be a string in the format
21902 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
21903 number or a valid video frame rate abbreviation. The default value is
21907 Set the sample aspect ratio of the sourced video.
21910 Set the duration of the sourced video. See
21911 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
21912 for the accepted syntax.
21914 If not specified, or the expressed duration is negative, the video is
21915 supposed to be generated forever.
21918 Additionally, all options of the @ref{coreimage} video filter are accepted.
21919 A complete filterchain can be used for further processing of the
21920 generated input without CPU-HOST transfer. See @ref{coreimage} documentation
21921 and examples for details.
21923 @subsection Examples
21928 Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
21929 given as complete and escaped command-line for Apple's standard bash shell:
21931 ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
21933 This example is equivalent to the QRCode example of @ref{coreimage} without the
21934 need for a nullsrc video source.
21938 @section mandelbrot
21940 Generate a Mandelbrot set fractal, and progressively zoom towards the
21941 point specified with @var{start_x} and @var{start_y}.
21943 This source accepts the following options:
21948 Set the terminal pts value. Default value is 400.
21951 Set the terminal scale value.
21952 Must be a floating point value. Default value is 0.3.
21955 Set the inner coloring mode, that is the algorithm used to draw the
21956 Mandelbrot fractal internal region.
21958 It shall assume one of the following values:
21963 Show time until convergence.
21965 Set color based on point closest to the origin of the iterations.
21970 Default value is @var{mincol}.
21973 Set the bailout value. Default value is 10.0.
21976 Set the maximum of iterations performed by the rendering
21977 algorithm. Default value is 7189.
21980 Set outer coloring mode.
21981 It shall assume one of following values:
21983 @item iteration_count
21984 Set iteration count mode.
21985 @item normalized_iteration_count
21986 set normalized iteration count mode.
21988 Default value is @var{normalized_iteration_count}.
21991 Set frame rate, expressed as number of frames per second. Default
21995 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
21996 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
21999 Set the initial scale value. Default value is 3.0.
22002 Set the initial x position. Must be a floating point value between
22003 -100 and 100. Default value is -0.743643887037158704752191506114774.
22006 Set the initial y position. Must be a floating point value between
22007 -100 and 100. Default value is -0.131825904205311970493132056385139.
22012 Generate various test patterns, as generated by the MPlayer test filter.
22014 The size of the generated video is fixed, and is 256x256.
22015 This source is useful in particular for testing encoding features.
22017 This source accepts the following options:
22022 Specify the frame rate of the sourced video, as the number of frames
22023 generated per second. It has to be a string in the format
22024 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
22025 number or a valid video frame rate abbreviation. The default value is
22029 Set the duration of the sourced video. See
22030 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
22031 for the accepted syntax.
22033 If not specified, or the expressed duration is negative, the video is
22034 supposed to be generated forever.
22038 Set the number or the name of the test to perform. Supported tests are:
22052 @item max_frames, m
22053 Set the maximum number of frames generated for each test, default value is 30.
22057 Default value is "all", which will cycle through the list of all tests.
22062 mptestsrc=t=dc_luma
22065 will generate a "dc_luma" test pattern.
22067 @section frei0r_src
22069 Provide a frei0r source.
22071 To enable compilation of this filter you need to install the frei0r
22072 header and configure FFmpeg with @code{--enable-frei0r}.
22074 This source accepts the following parameters:
22079 The size of the video to generate. For the syntax of this option, check the
22080 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22083 The framerate of the generated video. It may be a string of the form
22084 @var{num}/@var{den} or a frame rate abbreviation.
22087 The name to the frei0r source to load. For more information regarding frei0r and
22088 how to set the parameters, read the @ref{frei0r} section in the video filters
22091 @item filter_params
22092 A '|'-separated list of parameters to pass to the frei0r source.
22096 For example, to generate a frei0r partik0l source with size 200x200
22097 and frame rate 10 which is overlaid on the overlay filter main input:
22099 frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
22104 Generate a life pattern.
22106 This source is based on a generalization of John Conway's life game.
22108 The sourced input represents a life grid, each pixel represents a cell
22109 which can be in one of two possible states, alive or dead. Every cell
22110 interacts with its eight neighbours, which are the cells that are
22111 horizontally, vertically, or diagonally adjacent.
22113 At each interaction the grid evolves according to the adopted rule,
22114 which specifies the number of neighbor alive cells which will make a
22115 cell stay alive or born. The @option{rule} option allows one to specify
22118 This source accepts the following options:
22122 Set the file from which to read the initial grid state. In the file,
22123 each non-whitespace character is considered an alive cell, and newline
22124 is used to delimit the end of each row.
22126 If this option is not specified, the initial grid is generated
22130 Set the video rate, that is the number of frames generated per second.
22133 @item random_fill_ratio, ratio
22134 Set the random fill ratio for the initial random grid. It is a
22135 floating point number value ranging from 0 to 1, defaults to 1/PHI.
22136 It is ignored when a file is specified.
22138 @item random_seed, seed
22139 Set the seed for filling the initial random grid, must be an integer
22140 included between 0 and UINT32_MAX. If not specified, or if explicitly
22141 set to -1, the filter will try to use a good random seed on a best
22147 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
22148 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
22149 @var{NS} specifies the number of alive neighbor cells which make a
22150 live cell stay alive, and @var{NB} the number of alive neighbor cells
22151 which make a dead cell to become alive (i.e. to "born").
22152 "s" and "b" can be used in place of "S" and "B", respectively.
22154 Alternatively a rule can be specified by an 18-bits integer. The 9
22155 high order bits are used to encode the next cell state if it is alive
22156 for each number of neighbor alive cells, the low order bits specify
22157 the rule for "borning" new cells. Higher order bits encode for an
22158 higher number of neighbor cells.
22159 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
22160 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
22162 Default value is "S23/B3", which is the original Conway's game of life
22163 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
22164 cells, and will born a new cell if there are three alive cells around
22168 Set the size of the output video. For the syntax of this option, check the
22169 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22171 If @option{filename} is specified, the size is set by default to the
22172 same size of the input file. If @option{size} is set, it must contain
22173 the size specified in the input file, and the initial grid defined in
22174 that file is centered in the larger resulting area.
22176 If a filename is not specified, the size value defaults to "320x240"
22177 (used for a randomly generated initial grid).
22180 If set to 1, stitch the left and right grid edges together, and the
22181 top and bottom edges also. Defaults to 1.
22184 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
22185 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
22186 value from 0 to 255.
22189 Set the color of living (or new born) cells.
22192 Set the color of dead cells. If @option{mold} is set, this is the first color
22193 used to represent a dead cell.
22196 Set mold color, for definitely dead and moldy cells.
22198 For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the
22199 ffmpeg-utils manual,ffmpeg-utils}.
22202 @subsection Examples
22206 Read a grid from @file{pattern}, and center it on a grid of size
22209 life=f=pattern:s=300x300
22213 Generate a random grid of size 200x200, with a fill ratio of 2/3:
22215 life=ratio=2/3:s=200x200
22219 Specify a custom rule for evolving a randomly generated grid:
22225 Full example with slow death effect (mold) using @command{ffplay}:
22227 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
22234 @anchor{haldclutsrc}
22237 @anchor{pal100bars}
22238 @anchor{rgbtestsrc}
22240 @anchor{smptehdbars}
22243 @anchor{yuvtestsrc}
22244 @section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
22246 The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
22248 The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
22250 The @code{color} source provides an uniformly colored input.
22252 The @code{haldclutsrc} source provides an identity Hald CLUT. See also
22253 @ref{haldclut} filter.
22255 The @code{nullsrc} source returns unprocessed video frames. It is
22256 mainly useful to be employed in analysis / debugging tools, or as the
22257 source for filters which ignore the input data.
22259 The @code{pal75bars} source generates a color bars pattern, based on
22260 EBU PAL recommendations with 75% color levels.
22262 The @code{pal100bars} source generates a color bars pattern, based on
22263 EBU PAL recommendations with 100% color levels.
22265 The @code{rgbtestsrc} source generates an RGB test pattern useful for
22266 detecting RGB vs BGR issues. You should see a red, green and blue
22267 stripe from top to bottom.
22269 The @code{smptebars} source generates a color bars pattern, based on
22270 the SMPTE Engineering Guideline EG 1-1990.
22272 The @code{smptehdbars} source generates a color bars pattern, based on
22273 the SMPTE RP 219-2002.
22275 The @code{testsrc} source generates a test video pattern, showing a
22276 color pattern, a scrolling gradient and a timestamp. This is mainly
22277 intended for testing purposes.
22279 The @code{testsrc2} source is similar to testsrc, but supports more
22280 pixel formats instead of just @code{rgb24}. This allows using it as an
22281 input for other tests without requiring a format conversion.
22283 The @code{yuvtestsrc} source generates an YUV test pattern. You should
22284 see a y, cb and cr stripe from top to bottom.
22286 The sources accept the following parameters:
22291 Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
22292 source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
22293 pixels to be used as identity matrix for 3D lookup tables. Each component is
22294 coded on a @code{1/(N*N)} scale.
22297 Specify the color of the source, only available in the @code{color}
22298 source. For the syntax of this option, check the
22299 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
22302 Specify the size of the sourced video. For the syntax of this option, check the
22303 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22304 The default value is @code{320x240}.
22306 This option is not available with the @code{allrgb}, @code{allyuv}, and
22307 @code{haldclutsrc} filters.
22310 Specify the frame rate of the sourced video, as the number of frames
22311 generated per second. It has to be a string in the format
22312 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
22313 number or a valid video frame rate abbreviation. The default value is
22317 Set the duration of the sourced video. See
22318 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
22319 for the accepted syntax.
22321 If not specified, or the expressed duration is negative, the video is
22322 supposed to be generated forever.
22325 Set the sample aspect ratio of the sourced video.
22328 Specify the alpha (opacity) of the background, only available in the
22329 @code{testsrc2} source. The value must be between 0 (fully transparent) and
22330 255 (fully opaque, the default).
22333 Set the number of decimals to show in the timestamp, only available in the
22334 @code{testsrc} source.
22336 The displayed timestamp value will correspond to the original
22337 timestamp value multiplied by the power of 10 of the specified
22338 value. Default value is 0.
22341 @subsection Examples
22345 Generate a video with a duration of 5.3 seconds, with size
22346 176x144 and a frame rate of 10 frames per second:
22348 testsrc=duration=5.3:size=qcif:rate=10
22352 The following graph description will generate a red source
22353 with an opacity of 0.2, with size "qcif" and a frame rate of 10
22356 color=c=red@@0.2:s=qcif:r=10
22360 If the input content is to be ignored, @code{nullsrc} can be used. The
22361 following command generates noise in the luminance plane by employing
22362 the @code{geq} filter:
22364 nullsrc=s=256x256, geq=random(1)*255:128:128
22368 @subsection Commands
22370 The @code{color} source supports the following commands:
22374 Set the color of the created image. Accepts the same syntax of the
22375 corresponding @option{color} option.
22380 Generate video using an OpenCL program.
22385 OpenCL program source file.
22388 Kernel name in program.
22391 Size of frames to generate. This must be set.
22394 Pixel format to use for the generated frames. This must be set.
22397 Number of frames generated every second. Default value is '25'.
22401 For details of how the program loading works, see the @ref{program_opencl}
22408 Generate a colour ramp by setting pixel values from the position of the pixel
22409 in the output image. (Note that this will work with all pixel formats, but
22410 the generated output will not be the same.)
22412 __kernel void ramp(__write_only image2d_t dst,
22413 unsigned int index)
22415 int2 loc = (int2)(get_global_id(0), get_global_id(1));
22418 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
22420 write_imagef(dst, loc, val);
22425 Generate a Sierpinski carpet pattern, panning by a single pixel each frame.
22427 __kernel void sierpinski_carpet(__write_only image2d_t dst,
22428 unsigned int index)
22430 int2 loc = (int2)(get_global_id(0), get_global_id(1));
22432 float4 value = 0.0f;
22433 int x = loc.x + index;
22434 int y = loc.y + index;
22435 while (x > 0 || y > 0) {
22436 if (x % 3 == 1 && y % 3 == 1) {
22444 write_imagef(dst, loc, value);
22450 @section sierpinski
22452 Generate a Sierpinski carpet/triangle fractal, and randomly pan around.
22454 This source accepts the following options:
22458 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
22459 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
22462 Set frame rate, expressed as number of frames per second. Default
22466 Set seed which is used for random panning.
22469 Set max jump for single pan destination. Allowed range is from 1 to 10000.
22472 Set fractal type, can be default @code{carpet} or @code{triangle}.
22475 @c man end VIDEO SOURCES
22477 @chapter Video Sinks
22478 @c man begin VIDEO SINKS
22480 Below is a description of the currently available video sinks.
22482 @section buffersink
22484 Buffer video frames, and make them available to the end of the filter
22487 This sink is mainly intended for programmatic use, in particular
22488 through the interface defined in @file{libavfilter/buffersink.h}
22489 or the options system.
22491 It accepts a pointer to an AVBufferSinkContext structure, which
22492 defines the incoming buffers' formats, to be passed as the opaque
22493 parameter to @code{avfilter_init_filter} for initialization.
22497 Null video sink: do absolutely nothing with the input video. It is
22498 mainly useful as a template and for use in analysis / debugging
22501 @c man end VIDEO SINKS
22503 @chapter Multimedia Filters
22504 @c man begin MULTIMEDIA FILTERS
22506 Below is a description of the currently available multimedia filters.
22510 Convert input audio to a video output, displaying the audio bit scope.
22512 The filter accepts the following options:
22516 Set frame rate, expressed as number of frames per second. Default
22520 Specify the video size for the output. For the syntax of this option, check the
22521 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22522 Default value is @code{1024x256}.
22525 Specify list of colors separated by space or by '|' which will be used to
22526 draw channels. Unrecognized or missing colors will be replaced
22530 @section adrawgraph
22531 Draw a graph using input audio metadata.
22533 See @ref{drawgraph}
22535 @section agraphmonitor
22537 See @ref{graphmonitor}.
22539 @section ahistogram
22541 Convert input audio to a video output, displaying the volume histogram.
22543 The filter accepts the following options:
22547 Specify how histogram is calculated.
22549 It accepts the following values:
22552 Use single histogram for all channels.
22554 Use separate histogram for each channel.
22556 Default is @code{single}.
22559 Set frame rate, expressed as number of frames per second. Default
22563 Specify the video size for the output. For the syntax of this option, check the
22564 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22565 Default value is @code{hd720}.
22570 It accepts the following values:
22581 reverse logarithmic
22583 Default is @code{log}.
22586 Set amplitude scale.
22588 It accepts the following values:
22595 Default is @code{log}.
22598 Set how much frames to accumulate in histogram.
22599 Default is 1. Setting this to -1 accumulates all frames.
22602 Set histogram ratio of window height.
22605 Set sonogram sliding.
22607 It accepts the following values:
22610 replace old rows with new ones.
22612 scroll from top to bottom.
22614 Default is @code{replace}.
22617 @section aphasemeter
22619 Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase},
22620 representing mean phase of current audio frame. A video output can also be produced and is
22621 enabled by default. The audio is passed through as first output.
22623 Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in
22624 range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase
22625 and @code{1} means channels are in phase.
22627 The filter accepts the following options, all related to its video output:
22631 Set the output frame rate. Default value is @code{25}.
22634 Set the video size for the output. For the syntax of this option, check the
22635 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22636 Default value is @code{800x400}.
22641 Specify the red, green, blue contrast. Default values are @code{2},
22642 @code{7} and @code{1}.
22643 Allowed range is @code{[0, 255]}.
22646 Set color which will be used for drawing median phase. If color is
22647 @code{none} which is default, no median phase value will be drawn.
22650 Enable video output. Default is enabled.
22653 @section avectorscope
22655 Convert input audio to a video output, representing the audio vector
22658 The filter is used to measure the difference between channels of stereo
22659 audio stream. A monaural signal, consisting of identical left and right
22660 signal, results in straight vertical line. Any stereo separation is visible
22661 as a deviation from this line, creating a Lissajous figure.
22662 If the straight (or deviation from it) but horizontal line appears this
22663 indicates that the left and right channels are out of phase.
22665 The filter accepts the following options:
22669 Set the vectorscope mode.
22671 Available values are:
22674 Lissajous rotated by 45 degrees.
22677 Same as above but not rotated.
22680 Shape resembling half of circle.
22683 Default value is @samp{lissajous}.
22686 Set the video size for the output. For the syntax of this option, check the
22687 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22688 Default value is @code{400x400}.
22691 Set the output frame rate. Default value is @code{25}.
22697 Specify the red, green, blue and alpha contrast. Default values are @code{40},
22698 @code{160}, @code{80} and @code{255}.
22699 Allowed range is @code{[0, 255]}.
22705 Specify the red, green, blue and alpha fade. Default values are @code{15},
22706 @code{10}, @code{5} and @code{5}.
22707 Allowed range is @code{[0, 255]}.
22710 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}.
22711 Values lower than @var{1} will auto adjust zoom factor to maximal possible value.
22714 Set the vectorscope drawing mode.
22716 Available values are:
22719 Draw dot for each sample.
22722 Draw line between previous and current sample.
22725 Default value is @samp{dot}.
22728 Specify amplitude scale of audio samples.
22730 Available values are:
22746 Swap left channel axis with right channel axis.
22756 Mirror only x axis.
22759 Mirror only y axis.
22767 @subsection Examples
22771 Complete example using @command{ffplay}:
22773 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
22774 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
22778 @section bench, abench
22780 Benchmark part of a filtergraph.
22782 The filter accepts the following options:
22786 Start or stop a timer.
22788 Available values are:
22791 Get the current time, set it as frame metadata (using the key
22792 @code{lavfi.bench.start_time}), and forward the frame to the next filter.
22795 Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
22796 the input frame metadata to get the time difference. Time difference, average,
22797 maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
22798 @code{min}) are then printed. The timestamps are expressed in seconds.
22802 @subsection Examples
22806 Benchmark @ref{selectivecolor} filter:
22808 bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
22814 Concatenate audio and video streams, joining them together one after the
22817 The filter works on segments of synchronized video and audio streams. All
22818 segments must have the same number of streams of each type, and that will
22819 also be the number of streams at output.
22821 The filter accepts the following options:
22826 Set the number of segments. Default is 2.
22829 Set the number of output video streams, that is also the number of video
22830 streams in each segment. Default is 1.
22833 Set the number of output audio streams, that is also the number of audio
22834 streams in each segment. Default is 0.
22837 Activate unsafe mode: do not fail if segments have a different format.
22841 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
22842 @var{a} audio outputs.
22844 There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
22845 segment, in the same order as the outputs, then the inputs for the second
22848 Related streams do not always have exactly the same duration, for various
22849 reasons including codec frame size or sloppy authoring. For that reason,
22850 related synchronized streams (e.g. a video and its audio track) should be
22851 concatenated at once. The concat filter will use the duration of the longest
22852 stream in each segment (except the last one), and if necessary pad shorter
22853 audio streams with silence.
22855 For this filter to work correctly, all segments must start at timestamp 0.
22857 All corresponding streams must have the same parameters in all segments; the
22858 filtering system will automatically select a common pixel format for video
22859 streams, and a common sample format, sample rate and channel layout for
22860 audio streams, but other settings, such as resolution, must be converted
22861 explicitly by the user.
22863 Different frame rates are acceptable but will result in variable frame rate
22864 at output; be sure to configure the output file to handle it.
22866 @subsection Examples
22870 Concatenate an opening, an episode and an ending, all in bilingual version
22871 (video in stream 0, audio in streams 1 and 2):
22873 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
22874 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
22875 concat=n=3:v=1:a=2 [v] [a1] [a2]' \
22876 -map '[v]' -map '[a1]' -map '[a2]' output.mkv
22880 Concatenate two parts, handling audio and video separately, using the
22881 (a)movie sources, and adjusting the resolution:
22883 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
22884 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
22885 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
22887 Note that a desync will happen at the stitch if the audio and video streams
22888 do not have exactly the same duration in the first file.
22892 @subsection Commands
22894 This filter supports the following commands:
22897 Close the current segment and step to the next one
22903 EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness
22904 level. By default, it logs a message at a frequency of 10Hz with the
22905 Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
22906 Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
22908 The filter can only analyze streams which have a sampling rate of 48000 Hz and whose
22909 sample format is double-precision floating point. The input stream will be converted to
22910 this specification, if needed. Users may need to insert aformat and/or aresample filters
22911 after this filter to obtain the original parameters.
22913 The filter also has a video output (see the @var{video} option) with a real
22914 time graph to observe the loudness evolution. The graphic contains the logged
22915 message mentioned above, so it is not printed anymore when this option is set,
22916 unless the verbose logging is set. The main graphing area contains the
22917 short-term loudness (3 seconds of analysis), and the gauge on the right is for
22918 the momentary loudness (400 milliseconds), but can optionally be configured
22919 to instead display short-term loudness (see @var{gauge}).
22921 The green area marks a +/- 1LU target range around the target loudness
22922 (-23LUFS by default, unless modified through @var{target}).
22924 More information about the Loudness Recommendation EBU R128 on
22925 @url{http://tech.ebu.ch/loudness}.
22927 The filter accepts the following options:
22932 Activate the video output. The audio stream is passed unchanged whether this
22933 option is set or no. The video stream will be the first output stream if
22934 activated. Default is @code{0}.
22937 Set the video size. This option is for video only. For the syntax of this
22939 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22940 Default and minimum resolution is @code{640x480}.
22943 Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
22944 @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
22945 other integer value between this range is allowed.
22948 Set metadata injection. If set to @code{1}, the audio input will be segmented
22949 into 100ms output frames, each of them containing various loudness information
22950 in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
22952 Default is @code{0}.
22955 Force the frame logging level.
22957 Available values are:
22960 information logging level
22962 verbose logging level
22965 By default, the logging level is set to @var{info}. If the @option{video} or
22966 the @option{metadata} options are set, it switches to @var{verbose}.
22971 Available modes can be cumulated (the option is a @code{flag} type). Possible
22975 Disable any peak mode (default).
22977 Enable sample-peak mode.
22979 Simple peak mode looking for the higher sample value. It logs a message
22980 for sample-peak (identified by @code{SPK}).
22982 Enable true-peak mode.
22984 If enabled, the peak lookup is done on an over-sampled version of the input
22985 stream for better peak accuracy. It logs a message for true-peak.
22986 (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
22987 This mode requires a build with @code{libswresample}.
22991 Treat mono input files as "dual mono". If a mono file is intended for playback
22992 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
22993 If set to @code{true}, this option will compensate for this effect.
22994 Multi-channel input files are not affected by this option.
22997 Set a specific pan law to be used for the measurement of dual mono files.
22998 This parameter is optional, and has a default value of -3.01dB.
23001 Set a specific target level (in LUFS) used as relative zero in the visualization.
23002 This parameter is optional and has a default value of -23LUFS as specified
23003 by EBU R128. However, material published online may prefer a level of -16LUFS
23004 (e.g. for use with podcasts or video platforms).
23007 Set the value displayed by the gauge. Valid values are @code{momentary} and s
23008 @code{shortterm}. By default the momentary value will be used, but in certain
23009 scenarios it may be more useful to observe the short term value instead (e.g.
23013 Sets the display scale for the loudness. Valid parameters are @code{absolute}
23014 (in LUFS) or @code{relative} (LU) relative to the target. This only affects the
23015 video output, not the summary or continuous log output.
23018 @subsection Examples
23022 Real-time graph using @command{ffplay}, with a EBU scale meter +18:
23024 ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
23028 Run an analysis with @command{ffmpeg}:
23030 ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
23034 @section interleave, ainterleave
23036 Temporally interleave frames from several inputs.
23038 @code{interleave} works with video inputs, @code{ainterleave} with audio.
23040 These filters read frames from several inputs and send the oldest
23041 queued frame to the output.
23043 Input streams must have well defined, monotonically increasing frame
23046 In order to submit one frame to output, these filters need to enqueue
23047 at least one frame for each input, so they cannot work in case one
23048 input is not yet terminated and will not receive incoming frames.
23050 For example consider the case when one input is a @code{select} filter
23051 which always drops input frames. The @code{interleave} filter will keep
23052 reading from that input, but it will never be able to send new frames
23053 to output until the input sends an end-of-stream signal.
23055 Also, depending on inputs synchronization, the filters will drop
23056 frames in case one input receives more frames than the other ones, and
23057 the queue is already filled.
23059 These filters accept the following options:
23063 Set the number of different inputs, it is 2 by default.
23066 @subsection Examples
23070 Interleave frames belonging to different streams using @command{ffmpeg}:
23072 ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
23076 Add flickering blur effect:
23078 select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
23082 @section metadata, ametadata
23084 Manipulate frame metadata.
23086 This filter accepts the following options:
23090 Set mode of operation of the filter.
23092 Can be one of the following:
23096 If both @code{value} and @code{key} is set, select frames
23097 which have such metadata. If only @code{key} is set, select
23098 every frame that has such key in metadata.
23101 Add new metadata @code{key} and @code{value}. If key is already available
23105 Modify value of already present key.
23108 If @code{value} is set, delete only keys that have such value.
23109 Otherwise, delete key. If @code{key} is not set, delete all metadata values in
23113 Print key and its value if metadata was found. If @code{key} is not set print all
23114 metadata values available in frame.
23118 Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}.
23121 Set metadata value which will be used. This option is mandatory for
23122 @code{modify} and @code{add} mode.
23125 Which function to use when comparing metadata value and @code{value}.
23127 Can be one of following:
23131 Values are interpreted as strings, returns true if metadata value is same as @code{value}.
23134 Values are interpreted as strings, returns true if metadata value starts with
23135 the @code{value} option string.
23138 Values are interpreted as floats, returns true if metadata value is less than @code{value}.
23141 Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
23144 Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
23147 Values are interpreted as floats, returns true if expression from option @code{expr}
23151 Values are interpreted as strings, returns true if metadata value ends with
23152 the @code{value} option string.
23156 Set expression which is used when @code{function} is set to @code{expr}.
23157 The expression is evaluated through the eval API and can contain the following
23162 Float representation of @code{value} from metadata key.
23165 Float representation of @code{value} as supplied by user in @code{value} option.
23169 If specified in @code{print} mode, output is written to the named file. Instead of
23170 plain filename any writable url can be specified. Filename ``-'' is a shorthand
23171 for standard output. If @code{file} option is not set, output is written to the log
23172 with AV_LOG_INFO loglevel.
23175 Reduces buffering in print mode when output is written to a URL set using @var{file}.
23179 @subsection Examples
23183 Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values
23186 signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
23189 Print silencedetect output to file @file{metadata.txt}.
23191 silencedetect,ametadata=mode=print:file=metadata.txt
23194 Direct all metadata to a pipe with file descriptor 4.
23196 metadata=mode=print:file='pipe\:4'
23200 @section perms, aperms
23202 Set read/write permissions for the output frames.
23204 These filters are mainly aimed at developers to test direct path in the
23205 following filter in the filtergraph.
23207 The filters accept the following options:
23211 Select the permissions mode.
23213 It accepts the following values:
23216 Do nothing. This is the default.
23218 Set all the output frames read-only.
23220 Set all the output frames directly writable.
23222 Make the frame read-only if writable, and writable if read-only.
23224 Set each output frame read-only or writable randomly.
23228 Set the seed for the @var{random} mode, must be an integer included between
23229 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
23230 @code{-1}, the filter will try to use a good random seed on a best effort
23234 Note: in case of auto-inserted filter between the permission filter and the
23235 following one, the permission might not be received as expected in that
23236 following filter. Inserting a @ref{format} or @ref{aformat} filter before the
23237 perms/aperms filter can avoid this problem.
23239 @section realtime, arealtime
23241 Slow down filtering to match real time approximately.
23243 These filters will pause the filtering for a variable amount of time to
23244 match the output rate with the input timestamps.
23245 They are similar to the @option{re} option to @code{ffmpeg}.
23247 They accept the following options:
23251 Time limit for the pauses. Any pause longer than that will be considered
23252 a timestamp discontinuity and reset the timer. Default is 2 seconds.
23254 Speed factor for processing. The value must be a float larger than zero.
23255 Values larger than 1.0 will result in faster than realtime processing,
23256 smaller will slow processing down. The @var{limit} is automatically adapted
23257 accordingly. Default is 1.0.
23259 A processing speed faster than what is possible without these filters cannot
23264 @section select, aselect
23266 Select frames to pass in output.
23268 This filter accepts the following options:
23273 Set expression, which is evaluated for each input frame.
23275 If the expression is evaluated to zero, the frame is discarded.
23277 If the evaluation result is negative or NaN, the frame is sent to the
23278 first output; otherwise it is sent to the output with index
23279 @code{ceil(val)-1}, assuming that the input index starts from 0.
23281 For example a value of @code{1.2} corresponds to the output with index
23282 @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
23285 Set the number of outputs. The output to which to send the selected
23286 frame is based on the result of the evaluation. Default value is 1.
23289 The expression can contain the following constants:
23293 The (sequential) number of the filtered frame, starting from 0.
23296 The (sequential) number of the selected frame, starting from 0.
23298 @item prev_selected_n
23299 The sequential number of the last selected frame. It's NAN if undefined.
23302 The timebase of the input timestamps.
23305 The PTS (Presentation TimeStamp) of the filtered video frame,
23306 expressed in @var{TB} units. It's NAN if undefined.
23309 The PTS of the filtered video frame,
23310 expressed in seconds. It's NAN if undefined.
23313 The PTS of the previously filtered video frame. It's NAN if undefined.
23315 @item prev_selected_pts
23316 The PTS of the last previously filtered video frame. It's NAN if undefined.
23318 @item prev_selected_t
23319 The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined.
23322 The PTS of the first video frame in the video. It's NAN if undefined.
23325 The time of the first video frame in the video. It's NAN if undefined.
23327 @item pict_type @emph{(video only)}
23328 The type of the filtered frame. It can assume one of the following
23340 @item interlace_type @emph{(video only)}
23341 The frame interlace type. It can assume one of the following values:
23344 The frame is progressive (not interlaced).
23346 The frame is top-field-first.
23348 The frame is bottom-field-first.
23351 @item consumed_sample_n @emph{(audio only)}
23352 the number of selected samples before the current frame
23354 @item samples_n @emph{(audio only)}
23355 the number of samples in the current frame
23357 @item sample_rate @emph{(audio only)}
23358 the input sample rate
23361 This is 1 if the filtered frame is a key-frame, 0 otherwise.
23364 the position in the file of the filtered frame, -1 if the information
23365 is not available (e.g. for synthetic video)
23367 @item scene @emph{(video only)}
23368 value between 0 and 1 to indicate a new scene; a low value reflects a low
23369 probability for the current frame to introduce a new scene, while a higher
23370 value means the current frame is more likely to be one (see the example below)
23372 @item concatdec_select
23373 The concat demuxer can select only part of a concat input file by setting an
23374 inpoint and an outpoint, but the output packets may not be entirely contained
23375 in the selected interval. By using this variable, it is possible to skip frames
23376 generated by the concat demuxer which are not exactly contained in the selected
23379 This works by comparing the frame pts against the @var{lavf.concat.start_time}
23380 and the @var{lavf.concat.duration} packet metadata values which are also
23381 present in the decoded frames.
23383 The @var{concatdec_select} variable is -1 if the frame pts is at least
23384 start_time and either the duration metadata is missing or the frame pts is less
23385 than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
23388 That basically means that an input frame is selected if its pts is within the
23389 interval set by the concat demuxer.
23393 The default value of the select expression is "1".
23395 @subsection Examples
23399 Select all frames in input:
23404 The example above is the same as:
23416 Select only I-frames:
23418 select='eq(pict_type\,I)'
23422 Select one frame every 100:
23424 select='not(mod(n\,100))'
23428 Select only frames contained in the 10-20 time interval:
23430 select=between(t\,10\,20)
23434 Select only I-frames contained in the 10-20 time interval:
23436 select=between(t\,10\,20)*eq(pict_type\,I)
23440 Select frames with a minimum distance of 10 seconds:
23442 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
23446 Use aselect to select only audio frames with samples number > 100:
23448 aselect='gt(samples_n\,100)'
23452 Create a mosaic of the first scenes:
23454 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
23457 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
23461 Send even and odd frames to separate outputs, and compose them:
23463 select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
23467 Select useful frames from an ffconcat file which is using inpoints and
23468 outpoints but where the source files are not intra frame only.
23470 ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
23474 @section sendcmd, asendcmd
23476 Send commands to filters in the filtergraph.
23478 These filters read commands to be sent to other filters in the
23481 @code{sendcmd} must be inserted between two video filters,
23482 @code{asendcmd} must be inserted between two audio filters, but apart
23483 from that they act the same way.
23485 The specification of commands can be provided in the filter arguments
23486 with the @var{commands} option, or in a file specified by the
23487 @var{filename} option.
23489 These filters accept the following options:
23492 Set the commands to be read and sent to the other filters.
23494 Set the filename of the commands to be read and sent to the other
23498 @subsection Commands syntax
23500 A commands description consists of a sequence of interval
23501 specifications, comprising a list of commands to be executed when a
23502 particular event related to that interval occurs. The occurring event
23503 is typically the current frame time entering or leaving a given time
23506 An interval is specified by the following syntax:
23508 @var{START}[-@var{END}] @var{COMMANDS};
23511 The time interval is specified by the @var{START} and @var{END} times.
23512 @var{END} is optional and defaults to the maximum time.
23514 The current frame time is considered within the specified interval if
23515 it is included in the interval [@var{START}, @var{END}), that is when
23516 the time is greater or equal to @var{START} and is lesser than
23519 @var{COMMANDS} consists of a sequence of one or more command
23520 specifications, separated by ",", relating to that interval. The
23521 syntax of a command specification is given by:
23523 [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
23526 @var{FLAGS} is optional and specifies the type of events relating to
23527 the time interval which enable sending the specified command, and must
23528 be a non-null sequence of identifier flags separated by "+" or "|" and
23529 enclosed between "[" and "]".
23531 The following flags are recognized:
23534 The command is sent when the current frame timestamp enters the
23535 specified interval. In other words, the command is sent when the
23536 previous frame timestamp was not in the given interval, and the
23540 The command is sent when the current frame timestamp leaves the
23541 specified interval. In other words, the command is sent when the
23542 previous frame timestamp was in the given interval, and the
23546 If @var{FLAGS} is not specified, a default value of @code{[enter]} is
23549 @var{TARGET} specifies the target of the command, usually the name of
23550 the filter class or a specific filter instance name.
23552 @var{COMMAND} specifies the name of the command for the target filter.
23554 @var{ARG} is optional and specifies the optional list of argument for
23555 the given @var{COMMAND}.
23557 Between one interval specification and another, whitespaces, or
23558 sequences of characters starting with @code{#} until the end of line,
23559 are ignored and can be used to annotate comments.
23561 A simplified BNF description of the commands specification syntax
23564 @var{COMMAND_FLAG} ::= "enter" | "leave"
23565 @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
23566 @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
23567 @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
23568 @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
23569 @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
23572 @subsection Examples
23576 Specify audio tempo change at second 4:
23578 asendcmd=c='4.0 atempo tempo 1.5',atempo
23582 Target a specific filter instance:
23584 asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my
23588 Specify a list of drawtext and hue commands in a file.
23590 # show text in the interval 5-10
23591 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
23592 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
23594 # desaturate the image in the interval 15-20
23595 15.0-20.0 [enter] hue s 0,
23596 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
23598 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
23600 # apply an exponential saturation fade-out effect, starting from time 25
23601 25 [enter] hue s exp(25-t)
23604 A filtergraph allowing to read and process the above command list
23605 stored in a file @file{test.cmd}, can be specified with:
23607 sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
23612 @section setpts, asetpts
23614 Change the PTS (presentation timestamp) of the input frames.
23616 @code{setpts} works on video frames, @code{asetpts} on audio frames.
23618 This filter accepts the following options:
23623 The expression which is evaluated for each frame to construct its timestamp.
23627 The expression is evaluated through the eval API and can contain the following
23631 @item FRAME_RATE, FR
23632 frame rate, only defined for constant frame-rate video
23635 The presentation timestamp in input
23638 The count of the input frame for video or the number of consumed samples,
23639 not including the current frame for audio, starting from 0.
23641 @item NB_CONSUMED_SAMPLES
23642 The number of consumed samples, not including the current frame (only
23645 @item NB_SAMPLES, S
23646 The number of samples in the current frame (only audio)
23648 @item SAMPLE_RATE, SR
23649 The audio sample rate.
23652 The PTS of the first frame.
23655 the time in seconds of the first frame
23658 State whether the current frame is interlaced.
23661 the time in seconds of the current frame
23664 original position in the file of the frame, or undefined if undefined
23665 for the current frame
23668 The previous input PTS.
23671 previous input time in seconds
23674 The previous output PTS.
23677 previous output time in seconds
23680 The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
23684 The wallclock (RTC) time at the start of the movie in microseconds.
23687 The timebase of the input timestamps.
23691 @subsection Examples
23695 Start counting PTS from zero
23697 setpts=PTS-STARTPTS
23701 Apply fast motion effect:
23707 Apply slow motion effect:
23713 Set fixed rate of 25 frames per second:
23719 Set fixed rate 25 fps with some jitter:
23721 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
23725 Apply an offset of 10 seconds to the input PTS:
23731 Generate timestamps from a "live source" and rebase onto the current timebase:
23733 setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
23737 Generate timestamps by counting samples:
23746 Force color range for the output video frame.
23748 The @code{setrange} filter marks the color range property for the
23749 output frames. It does not change the input frame, but only sets the
23750 corresponding property, which affects how the frame is treated by
23753 The filter accepts the following options:
23758 Available values are:
23762 Keep the same color range property.
23764 @item unspecified, unknown
23765 Set the color range as unspecified.
23767 @item limited, tv, mpeg
23768 Set the color range as limited.
23770 @item full, pc, jpeg
23771 Set the color range as full.
23775 @section settb, asettb
23777 Set the timebase to use for the output frames timestamps.
23778 It is mainly useful for testing timebase configuration.
23780 It accepts the following parameters:
23785 The expression which is evaluated into the output timebase.
23789 The value for @option{tb} is an arithmetic expression representing a
23790 rational. The expression can contain the constants "AVTB" (the default
23791 timebase), "intb" (the input timebase) and "sr" (the sample rate,
23792 audio only). Default value is "intb".
23794 @subsection Examples
23798 Set the timebase to 1/25:
23804 Set the timebase to 1/10:
23810 Set the timebase to 1001/1000:
23816 Set the timebase to 2*intb:
23822 Set the default timebase value:
23829 Convert input audio to a video output representing frequency spectrum
23830 logarithmically using Brown-Puckette constant Q transform algorithm with
23831 direct frequency domain coefficient calculation (but the transform itself
23832 is not really constant Q, instead the Q factor is actually variable/clamped),
23833 with musical tone scale, from E0 to D#10.
23835 The filter accepts the following options:
23839 Specify the video size for the output. It must be even. For the syntax of this option,
23840 check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23841 Default value is @code{1920x1080}.
23844 Set the output frame rate. Default value is @code{25}.
23847 Set the bargraph height. It must be even. Default value is @code{-1} which
23848 computes the bargraph height automatically.
23851 Set the axis height. It must be even. Default value is @code{-1} which computes
23852 the axis height automatically.
23855 Set the sonogram height. It must be even. Default value is @code{-1} which
23856 computes the sonogram height automatically.
23859 Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
23860 instead. Default value is @code{1}.
23862 @item sono_v, volume
23863 Specify the sonogram volume expression. It can contain variables:
23866 the @var{bar_v} evaluated expression
23867 @item frequency, freq, f
23868 the frequency where it is evaluated
23869 @item timeclamp, tc
23870 the value of @var{timeclamp} option
23874 @item a_weighting(f)
23875 A-weighting of equal loudness
23876 @item b_weighting(f)
23877 B-weighting of equal loudness
23878 @item c_weighting(f)
23879 C-weighting of equal loudness.
23881 Default value is @code{16}.
23883 @item bar_v, volume2
23884 Specify the bargraph volume expression. It can contain variables:
23887 the @var{sono_v} evaluated expression
23888 @item frequency, freq, f
23889 the frequency where it is evaluated
23890 @item timeclamp, tc
23891 the value of @var{timeclamp} option
23895 @item a_weighting(f)
23896 A-weighting of equal loudness
23897 @item b_weighting(f)
23898 B-weighting of equal loudness
23899 @item c_weighting(f)
23900 C-weighting of equal loudness.
23902 Default value is @code{sono_v}.
23904 @item sono_g, gamma
23905 Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
23906 higher gamma makes the spectrum having more range. Default value is @code{3}.
23907 Acceptable range is @code{[1, 7]}.
23909 @item bar_g, gamma2
23910 Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
23914 Specify the bargraph transparency level. Lower value makes the bargraph sharper.
23915 Default value is @code{1}. Acceptable range is @code{[0, 1]}.
23917 @item timeclamp, tc
23918 Specify the transform timeclamp. At low frequency, there is trade-off between
23919 accuracy in time domain and frequency domain. If timeclamp is lower,
23920 event in time domain is represented more accurately (such as fast bass drum),
23921 otherwise event in frequency domain is represented more accurately
23922 (such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}.
23925 Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it
23926 limits future samples by applying asymmetric windowing in time domain, useful
23927 when low latency is required. Accepted range is @code{[0, 1]}.
23930 Specify the transform base frequency. Default value is @code{20.01523126408007475},
23931 which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
23934 Specify the transform end frequency. Default value is @code{20495.59681441799654},
23935 which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
23938 This option is deprecated and ignored.
23941 Specify the transform length in time domain. Use this option to control accuracy
23942 trade-off between time domain and frequency domain at every frequency sample.
23943 It can contain variables:
23945 @item frequency, freq, f
23946 the frequency where it is evaluated
23947 @item timeclamp, tc
23948 the value of @var{timeclamp} option.
23950 Default value is @code{384*tc/(384+tc*f)}.
23953 Specify the transform count for every video frame. Default value is @code{6}.
23954 Acceptable range is @code{[1, 30]}.
23957 Specify the transform count for every single pixel. Default value is @code{0},
23958 which makes it computed automatically. Acceptable range is @code{[0, 10]}.
23961 Specify font file for use with freetype to draw the axis. If not specified,
23962 use embedded font. Note that drawing with font file or embedded font is not
23963 implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
23967 Specify fontconfig pattern. This has lower priority than @var{fontfile}. The
23968 @code{:} in the pattern may be replaced by @code{|} to avoid unnecessary
23972 Specify font color expression. This is arithmetic expression that should return
23973 integer value 0xRRGGBB. It can contain variables:
23975 @item frequency, freq, f
23976 the frequency where it is evaluated
23977 @item timeclamp, tc
23978 the value of @var{timeclamp} option
23983 midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
23984 @item r(x), g(x), b(x)
23985 red, green, and blue value of intensity x.
23987 Default value is @code{st(0, (midi(f)-59.5)/12);
23988 st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
23989 r(1-ld(1)) + b(ld(1))}.
23992 Specify image file to draw the axis. This option override @var{fontfile} and
23993 @var{fontcolor} option.
23996 Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
23997 the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
23998 Default value is @code{1}.
24001 Set colorspace. The accepted values are:
24004 Unspecified (default)
24013 BT.470BG or BT.601-6 625
24016 SMPTE-170M or BT.601-6 525
24022 BT.2020 with non-constant luminance
24027 Set spectrogram color scheme. This is list of floating point values with format
24028 @code{left_r|left_g|left_b|right_r|right_g|right_b}.
24029 The default is @code{1|0.5|0|0|0.5|1}.
24033 @subsection Examples
24037 Playing audio while showing the spectrum:
24039 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
24043 Same as above, but with frame rate 30 fps:
24045 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
24049 Playing at 1280x720:
24051 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
24055 Disable sonogram display:
24061 A1 and its harmonics: A1, A2, (near)E3, A3:
24063 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),
24064 asplit[a][out1]; [a] showcqt [out0]'
24068 Same as above, but with more accuracy in frequency domain:
24070 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),
24071 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
24077 bar_v=10:sono_v=bar_v*a_weighting(f)
24081 Custom gamma, now spectrum is linear to the amplitude.
24087 Custom tlength equation:
24089 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)))'
24093 Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
24095 fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
24099 Custom font using fontconfig:
24101 font='Courier New,Monospace,mono|bold'
24105 Custom frequency range with custom axis using image file:
24107 axisfile=myaxis.png:basefreq=40:endfreq=10000
24113 Convert input audio to video output representing the audio power spectrum.
24114 Audio amplitude is on Y-axis while frequency is on X-axis.
24116 The filter accepts the following options:
24120 Specify size of video. For the syntax of this option, check the
24121 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24122 Default is @code{1024x512}.
24126 This set how each frequency bin will be represented.
24128 It accepts the following values:
24134 Default is @code{bar}.
24137 Set amplitude scale.
24139 It accepts the following values:
24153 Default is @code{log}.
24156 Set frequency scale.
24158 It accepts the following values:
24167 Reverse logarithmic scale.
24169 Default is @code{lin}.
24172 Set window size. Allowed range is from 16 to 65536.
24174 Default is @code{2048}
24177 Set windowing function.
24179 It accepts the following values:
24202 Default is @code{hanning}.
24205 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
24206 which means optimal overlap for selected window function will be picked.
24209 Set time averaging. Setting this to 0 will display current maximal peaks.
24210 Default is @code{1}, which means time averaging is disabled.
24213 Specify list of colors separated by space or by '|' which will be used to
24214 draw channel frequencies. Unrecognized or missing colors will be replaced
24218 Set channel display mode.
24220 It accepts the following values:
24225 Default is @code{combined}.
24228 Set minimum amplitude used in @code{log} amplitude scaler.
24232 @section showspatial
24234 Convert stereo input audio to a video output, representing the spatial relationship
24235 between two channels.
24237 The filter accepts the following options:
24241 Specify the video size for the output. For the syntax of this option, check the
24242 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24243 Default value is @code{512x512}.
24246 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
24249 Set window function.
24251 It accepts the following values:
24276 Default value is @code{hann}.
24279 Set ratio of overlap window. Default value is @code{0.5}.
24280 When value is @code{1} overlap is set to recommended size for specific
24281 window function currently used.
24284 @anchor{showspectrum}
24285 @section showspectrum
24287 Convert input audio to a video output, representing the audio frequency
24290 The filter accepts the following options:
24294 Specify the video size for the output. For the syntax of this option, check the
24295 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24296 Default value is @code{640x512}.
24299 Specify how the spectrum should slide along the window.
24301 It accepts the following values:
24304 the samples start again on the left when they reach the right
24306 the samples scroll from right to left
24308 frames are only produced when the samples reach the right
24310 the samples scroll from left to right
24313 Default value is @code{replace}.
24316 Specify display mode.
24318 It accepts the following values:
24321 all channels are displayed in the same row
24323 all channels are displayed in separate rows
24326 Default value is @samp{combined}.
24329 Specify display color mode.
24331 It accepts the following values:
24334 each channel is displayed in a separate color
24336 each channel is displayed using the same color scheme
24338 each channel is displayed using the rainbow color scheme
24340 each channel is displayed using the moreland color scheme
24342 each channel is displayed using the nebulae color scheme
24344 each channel is displayed using the fire color scheme
24346 each channel is displayed using the fiery color scheme
24348 each channel is displayed using the fruit color scheme
24350 each channel is displayed using the cool color scheme
24352 each channel is displayed using the magma color scheme
24354 each channel is displayed using the green color scheme
24356 each channel is displayed using the viridis color scheme
24358 each channel is displayed using the plasma color scheme
24360 each channel is displayed using the cividis color scheme
24362 each channel is displayed using the terrain color scheme
24365 Default value is @samp{channel}.
24368 Specify scale used for calculating intensity color values.
24370 It accepts the following values:
24375 square root, default
24386 Default value is @samp{sqrt}.
24389 Specify frequency scale.
24391 It accepts the following values:
24399 Default value is @samp{lin}.
24402 Set saturation modifier for displayed colors. Negative values provide
24403 alternative color scheme. @code{0} is no saturation at all.
24404 Saturation must be in [-10.0, 10.0] range.
24405 Default value is @code{1}.
24408 Set window function.
24410 It accepts the following values:
24435 Default value is @code{hann}.
24438 Set orientation of time vs frequency axis. Can be @code{vertical} or
24439 @code{horizontal}. Default is @code{vertical}.
24442 Set ratio of overlap window. Default value is @code{0}.
24443 When value is @code{1} overlap is set to recommended size for specific
24444 window function currently used.
24447 Set scale gain for calculating intensity color values.
24448 Default value is @code{1}.
24451 Set which data to display. Can be @code{magnitude}, default or @code{phase}.
24454 Set color rotation, must be in [-1.0, 1.0] range.
24455 Default value is @code{0}.
24458 Set start frequency from which to display spectrogram. Default is @code{0}.
24461 Set stop frequency to which to display spectrogram. Default is @code{0}.
24464 Set upper frame rate limit. Default is @code{auto}, unlimited.
24467 Draw time and frequency axes and legends. Default is disabled.
24470 The usage is very similar to the showwaves filter; see the examples in that
24473 @subsection Examples
24477 Large window with logarithmic color scaling:
24479 showspectrum=s=1280x480:scale=log
24483 Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
24485 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
24486 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
24490 @section showspectrumpic
24492 Convert input audio to a single video frame, representing the audio frequency
24495 The filter accepts the following options:
24499 Specify the video size for the output. For the syntax of this option, check the
24500 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24501 Default value is @code{4096x2048}.
24504 Specify display mode.
24506 It accepts the following values:
24509 all channels are displayed in the same row
24511 all channels are displayed in separate rows
24513 Default value is @samp{combined}.
24516 Specify display color mode.
24518 It accepts the following values:
24521 each channel is displayed in a separate color
24523 each channel is displayed using the same color scheme
24525 each channel is displayed using the rainbow color scheme
24527 each channel is displayed using the moreland color scheme
24529 each channel is displayed using the nebulae color scheme
24531 each channel is displayed using the fire color scheme
24533 each channel is displayed using the fiery color scheme
24535 each channel is displayed using the fruit color scheme
24537 each channel is displayed using the cool color scheme
24539 each channel is displayed using the magma color scheme
24541 each channel is displayed using the green color scheme
24543 each channel is displayed using the viridis color scheme
24545 each channel is displayed using the plasma color scheme
24547 each channel is displayed using the cividis color scheme
24549 each channel is displayed using the terrain color scheme
24551 Default value is @samp{intensity}.
24554 Specify scale used for calculating intensity color values.
24556 It accepts the following values:
24561 square root, default
24571 Default value is @samp{log}.
24574 Specify frequency scale.
24576 It accepts the following values:
24584 Default value is @samp{lin}.
24587 Set saturation modifier for displayed colors. Negative values provide
24588 alternative color scheme. @code{0} is no saturation at all.
24589 Saturation must be in [-10.0, 10.0] range.
24590 Default value is @code{1}.
24593 Set window function.
24595 It accepts the following values:
24619 Default value is @code{hann}.
24622 Set orientation of time vs frequency axis. Can be @code{vertical} or
24623 @code{horizontal}. Default is @code{vertical}.
24626 Set scale gain for calculating intensity color values.
24627 Default value is @code{1}.
24630 Draw time and frequency axes and legends. Default is enabled.
24633 Set color rotation, must be in [-1.0, 1.0] range.
24634 Default value is @code{0}.
24637 Set start frequency from which to display spectrogram. Default is @code{0}.
24640 Set stop frequency to which to display spectrogram. Default is @code{0}.
24643 @subsection Examples
24647 Extract an audio spectrogram of a whole audio track
24648 in a 1024x1024 picture using @command{ffmpeg}:
24650 ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
24654 @section showvolume
24656 Convert input audio volume to a video output.
24658 The filter accepts the following options:
24665 Set border width, allowed range is [0, 5]. Default is 1.
24668 Set channel width, allowed range is [80, 8192]. Default is 400.
24671 Set channel height, allowed range is [1, 900]. Default is 20.
24674 Set fade, allowed range is [0, 1]. Default is 0.95.
24677 Set volume color expression.
24679 The expression can use the following variables:
24683 Current max volume of channel in dB.
24689 Current channel number, starting from 0.
24693 If set, displays channel names. Default is enabled.
24696 If set, displays volume values. Default is enabled.
24699 Set orientation, can be horizontal: @code{h} or vertical: @code{v},
24700 default is @code{h}.
24703 Set step size, allowed range is [0, 5]. Default is 0, which means
24707 Set background opacity, allowed range is [0, 1]. Default is 0.
24710 Set metering mode, can be peak: @code{p} or rms: @code{r},
24711 default is @code{p}.
24714 Set display scale, can be linear: @code{lin} or log: @code{log},
24715 default is @code{lin}.
24719 If set to > 0., display a line for the max level
24720 in the previous seconds.
24721 default is disabled: @code{0.}
24724 The color of the max line. Use when @code{dm} option is set to > 0.
24725 default is: @code{orange}
24730 Convert input audio to a video output, representing the samples waves.
24732 The filter accepts the following options:
24736 Specify the video size for the output. For the syntax of this option, check the
24737 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24738 Default value is @code{600x240}.
24743 Available values are:
24746 Draw a point for each sample.
24749 Draw a vertical line for each sample.
24752 Draw a point for each sample and a line between them.
24755 Draw a centered vertical line for each sample.
24758 Default value is @code{point}.
24761 Set the number of samples which are printed on the same column. A
24762 larger value will decrease the frame rate. Must be a positive
24763 integer. This option can be set only if the value for @var{rate}
24764 is not explicitly specified.
24767 Set the (approximate) output frame rate. This is done by setting the
24768 option @var{n}. Default value is "25".
24770 @item split_channels
24771 Set if channels should be drawn separately or overlap. Default value is 0.
24774 Set colors separated by '|' which are going to be used for drawing of each channel.
24777 Set amplitude scale.
24779 Available values are:
24797 Set the draw mode. This is mostly useful to set for high @var{n}.
24799 Available values are:
24802 Scale pixel values for each drawn sample.
24805 Draw every sample directly.
24808 Default value is @code{scale}.
24811 @subsection Examples
24815 Output the input file audio and the corresponding video representation
24818 amovie=a.mp3,asplit[out0],showwaves[out1]
24822 Create a synthetic signal and show it with showwaves, forcing a
24823 frame rate of 30 frames per second:
24825 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
24829 @section showwavespic
24831 Convert input audio to a single video frame, representing the samples waves.
24833 The filter accepts the following options:
24837 Specify the video size for the output. For the syntax of this option, check the
24838 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24839 Default value is @code{600x240}.
24841 @item split_channels
24842 Set if channels should be drawn separately or overlap. Default value is 0.
24845 Set colors separated by '|' which are going to be used for drawing of each channel.
24848 Set amplitude scale.
24850 Available values are:
24870 Available values are:
24873 Scale pixel values for each drawn sample.
24876 Draw every sample directly.
24879 Default value is @code{scale}.
24882 @subsection Examples
24886 Extract a channel split representation of the wave form of a whole audio track
24887 in a 1024x800 picture using @command{ffmpeg}:
24889 ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
24893 @section sidedata, asidedata
24895 Delete frame side data, or select frames based on it.
24897 This filter accepts the following options:
24901 Set mode of operation of the filter.
24903 Can be one of the following:
24907 Select every frame with side data of @code{type}.
24910 Delete side data of @code{type}. If @code{type} is not set, delete all side
24916 Set side data type used with all modes. Must be set for @code{select} mode. For
24917 the list of frame side data types, refer to the @code{AVFrameSideDataType} enum
24918 in @file{libavutil/frame.h}. For example, to choose
24919 @code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}.
24923 @section spectrumsynth
24925 Synthesize audio from 2 input video spectrums, first input stream represents
24926 magnitude across time and second represents phase across time.
24927 The filter will transform from frequency domain as displayed in videos back
24928 to time domain as presented in audio output.
24930 This filter is primarily created for reversing processed @ref{showspectrum}
24931 filter outputs, but can synthesize sound from other spectrograms too.
24932 But in such case results are going to be poor if the phase data is not
24933 available, because in such cases phase data need to be recreated, usually
24934 it's just recreated from random noise.
24935 For best results use gray only output (@code{channel} color mode in
24936 @ref{showspectrum} filter) and @code{log} scale for magnitude video and
24937 @code{lin} scale for phase video. To produce phase, for 2nd video, use
24938 @code{data} option. Inputs videos should generally use @code{fullframe}
24939 slide mode as that saves resources needed for decoding video.
24941 The filter accepts the following options:
24945 Specify sample rate of output audio, the sample rate of audio from which
24946 spectrum was generated may differ.
24949 Set number of channels represented in input video spectrums.
24952 Set scale which was used when generating magnitude input spectrum.
24953 Can be @code{lin} or @code{log}. Default is @code{log}.
24956 Set slide which was used when generating inputs spectrums.
24957 Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
24958 Default is @code{fullframe}.
24961 Set window function used for resynthesis.
24964 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
24965 which means optimal overlap for selected window function will be picked.
24968 Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
24969 Default is @code{vertical}.
24972 @subsection Examples
24976 First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
24977 then resynthesize videos back to audio with spectrumsynth:
24979 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
24980 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
24981 ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
24985 @section split, asplit
24987 Split input into several identical outputs.
24989 @code{asplit} works with audio input, @code{split} with video.
24991 The filter accepts a single parameter which specifies the number of outputs. If
24992 unspecified, it defaults to 2.
24994 @subsection Examples
24998 Create two separate outputs from the same input:
25000 [in] split [out0][out1]
25004 To create 3 or more outputs, you need to specify the number of
25007 [in] asplit=3 [out0][out1][out2]
25011 Create two separate outputs from the same input, one cropped and
25014 [in] split [splitout1][splitout2];
25015 [splitout1] crop=100:100:0:0 [cropout];
25016 [splitout2] pad=200:200:100:100 [padout];
25020 Create 5 copies of the input audio with @command{ffmpeg}:
25022 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
25028 Receive commands sent through a libzmq client, and forward them to
25029 filters in the filtergraph.
25031 @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
25032 must be inserted between two video filters, @code{azmq} between two
25033 audio filters. Both are capable to send messages to any filter type.
25035 To enable these filters you need to install the libzmq library and
25036 headers and configure FFmpeg with @code{--enable-libzmq}.
25038 For more information about libzmq see:
25039 @url{http://www.zeromq.org/}
25041 The @code{zmq} and @code{azmq} filters work as a libzmq server, which
25042 receives messages sent through a network interface defined by the
25043 @option{bind_address} (or the abbreviation "@option{b}") option.
25044 Default value of this option is @file{tcp://localhost:5555}. You may
25045 want to alter this value to your needs, but do not forget to escape any
25046 ':' signs (see @ref{filtergraph escaping}).
25048 The received message must be in the form:
25050 @var{TARGET} @var{COMMAND} [@var{ARG}]
25053 @var{TARGET} specifies the target of the command, usually the name of
25054 the filter class or a specific filter instance name. The default
25055 filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>},
25056 but you can override this by using the @samp{filter_name@@id} syntax
25057 (see @ref{Filtergraph syntax}).
25059 @var{COMMAND} specifies the name of the command for the target filter.
25061 @var{ARG} is optional and specifies the optional argument list for the
25062 given @var{COMMAND}.
25064 Upon reception, the message is processed and the corresponding command
25065 is injected into the filtergraph. Depending on the result, the filter
25066 will send a reply to the client, adopting the format:
25068 @var{ERROR_CODE} @var{ERROR_REASON}
25072 @var{MESSAGE} is optional.
25074 @subsection Examples
25076 Look at @file{tools/zmqsend} for an example of a zmq client which can
25077 be used to send commands processed by these filters.
25079 Consider the following filtergraph generated by @command{ffplay}.
25080 In this example the last overlay filter has an instance name. All other
25081 filters will have default instance names.
25084 ffplay -dumpgraph 1 -f lavfi "
25085 color=s=100x100:c=red [l];
25086 color=s=100x100:c=blue [r];
25087 nullsrc=s=200x100, zmq [bg];
25088 [bg][l] overlay [bg+l];
25089 [bg+l][r] overlay@@my=x=100 "
25092 To change the color of the left side of the video, the following
25093 command can be used:
25095 echo Parsed_color_0 c yellow | tools/zmqsend
25098 To change the right side:
25100 echo Parsed_color_1 c pink | tools/zmqsend
25103 To change the position of the right side:
25105 echo overlay@@my x 150 | tools/zmqsend
25109 @c man end MULTIMEDIA FILTERS
25111 @chapter Multimedia Sources
25112 @c man begin MULTIMEDIA SOURCES
25114 Below is a description of the currently available multimedia sources.
25118 This is the same as @ref{movie} source, except it selects an audio
25124 Read audio and/or video stream(s) from a movie container.
25126 It accepts the following parameters:
25130 The name of the resource to read (not necessarily a file; it can also be a
25131 device or a stream accessed through some protocol).
25133 @item format_name, f
25134 Specifies the format assumed for the movie to read, and can be either
25135 the name of a container or an input device. If not specified, the
25136 format is guessed from @var{movie_name} or by probing.
25138 @item seek_point, sp
25139 Specifies the seek point in seconds. The frames will be output
25140 starting from this seek point. The parameter is evaluated with
25141 @code{av_strtod}, so the numerical value may be suffixed by an IS
25142 postfix. The default value is "0".
25145 Specifies the streams to read. Several streams can be specified,
25146 separated by "+". The source will then have as many outputs, in the
25147 same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers"
25148 section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify
25149 respectively the default (best suited) video and audio stream. Default
25150 is "dv", or "da" if the filter is called as "amovie".
25152 @item stream_index, si
25153 Specifies the index of the video stream to read. If the value is -1,
25154 the most suitable video stream will be automatically selected. The default
25155 value is "-1". Deprecated. If the filter is called "amovie", it will select
25156 audio instead of video.
25159 Specifies how many times to read the stream in sequence.
25160 If the value is 0, the stream will be looped infinitely.
25161 Default value is "1".
25163 Note that when the movie is looped the source timestamps are not
25164 changed, so it will generate non monotonically increasing timestamps.
25166 @item discontinuity
25167 Specifies the time difference between frames above which the point is
25168 considered a timestamp discontinuity which is removed by adjusting the later
25172 It allows overlaying a second video on top of the main input of
25173 a filtergraph, as shown in this graph:
25175 input -----------> deltapts0 --> overlay --> output
25178 movie --> scale--> deltapts1 -------+
25180 @subsection Examples
25184 Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
25185 on top of the input labelled "in":
25187 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
25188 [in] setpts=PTS-STARTPTS [main];
25189 [main][over] overlay=16:16 [out]
25193 Read from a video4linux2 device, and overlay it on top of the input
25196 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
25197 [in] setpts=PTS-STARTPTS [main];
25198 [main][over] overlay=16:16 [out]
25202 Read the first video stream and the audio stream with id 0x81 from
25203 dvd.vob; the video is connected to the pad named "video" and the audio is
25204 connected to the pad named "audio":
25206 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
25210 @subsection Commands
25212 Both movie and amovie support the following commands:
25215 Perform seek using "av_seek_frame".
25216 The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
25219 @var{stream_index}: If stream_index is -1, a default
25220 stream is selected, and @var{timestamp} is automatically converted
25221 from AV_TIME_BASE units to the stream specific time_base.
25223 @var{timestamp}: Timestamp in AVStream.time_base units
25224 or, if no stream is specified, in AV_TIME_BASE units.
25226 @var{flags}: Flags which select direction and seeking mode.
25230 Get movie duration in AV_TIME_BASE units.
25234 @c man end MULTIMEDIA SOURCES